Carousel

A slideshow component for cycling through elements—images or slides of text—like a carousel.

How it works

The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms and a bit of JavaScript. It works with a series of images, text, or custom markup. It also includes support for previous/next controls and indicators.

Example

Carousels don’t automatically normalize slide dimensions. As such, you may need to use additional utilities or custom styles to appropriately size content. While carousels support previous/next controls and indicators, they’re not explicitly required. Add and customize as you see fit.

Here is an example with slides

<ol outputclass="carousel">
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
</ol>

Indicators

Set @otherprops="indicators(true)" to add indicators to the carousel, alongside the previous/next controls. The indicators let users jump directly to a particular slide.

<ol outputclass="carousel" otherprops="indicators(true)">
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
</ol>

With captions

Add captions by using <fig> elements

The First Slide

The Second Slide

The Third Slide

<ol outputclass="carousel">
  <li>
    <fig>
      <title>The First Slide</title>
      <image href="..." />
    </fig>
  </li>
  <li>
    <fig>
      <title>The Second Slide</title>
      <image href="..." />
    </fig>
  </li>
  <li>
    <fig>
      <title>The Third Slide</title>
      <image href="..." />
    </fig>
  </li>
</ol>

With non-image elements

Place additional DITA elements within a <div> element to add them within a carousel. Additional structure and spacing can be added by setting the @outputclass="col-*" attribute.

<ol outputclass="carousel">
  <li>
    <div>
      <div outputclass="col-1"/>
      <div outputclass="col-10">
      ...
      <div>
    <div>
  </li>
  <li>
    <div>
      <div outputclass="col-1"/>
      <div outputclass="col-10">
      ...
      <div>
    <div>
  </li>
  <li>
    <div>
      <div outputclass="col-1"/>
      <div outputclass="col-10">
      ...
      <div>
    <div>
  </li>
</ol>

Multiple slides side-by-side

Add multiple <image> elements within each <li>

<ol outputclass="carousel">
  <li>
    <image href="..." />
    <image href="..." />
    <image href="..." />
  </li>
  <li>
    <image href="..." />
    <image href="..." />
    <image href="..." />
  </li>
  <li>
    <image href="..." />
    <image href="..." />
    <image href="..." />
  </li>
</ol>

Multiple slides with titles

Add multiple <image> elements within each <li> and include a <div> element for title texts.

First Image

Second Image

Third Image

Fourth Image

Fifth Image

Sixth Image

Seventh Image

Eighth Image

Ninth Image

<ol outputclass="carousel">
  <li>
    <image href="..." />
    <image href="..." />
    <image href="..." />
    <div deliveryTarget="html">
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
    </div>
  </li>
  <li>
    <image href="..." />
    <image href="..." />
    <image href="..." />
    <div deliveryTarget="html">
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
    </div>
  </li>
  <li>
    <image href="..." />
    <image href="..." />
    <image href="..." />
    <div deliveryTarget="html">
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
      <div outputclass="col-4">
        <p outputclass="text-center">...</p>
      </div>
    </div>
  </li>
</ol>

Crossfade

Add @outputclass="carousel-fade" to your carousel to animate slides with a fade transition instead of a slide. Depending on your carousel content (e.g., text only slides), you may want to add <div outputclass="bg-body"> or some custom CSS to the carousel items for proper crossfading.

<ol outputclass="carousel-fade">
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
</ol>

Autoplaying carousels

Carousels autoplay on page load by default. Autoplaying carousels automatically pause while hovered with the mouse. In browsers that support the Page Visibility API, the carousel will stop cycling when the webpage is not visible to the user ( such as when the browser tab is inactive, or when the browser window is minimized).

When @otherprops="autoplay(false)" is set, the carousel won’t automatically start to cycle on page load. Instead, it will only start after the first user interaction.

<ol outputclass="carousel" otherprops="autoplay(false)">
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
</ol>

Individual carousel item interval

Add @otherprops="interval(1000)" to a carousel item to change the amount of time to delay between automatically cycling to the next item.

<ol outputclass="carousel">
  <li otherprops="interval(2000)">
    <image href="..." />
  </li>
  <li otherprops="interval(1000)">
    <image href="..." />
  </li>
  <li otherprops="interval(3000)">
    <image href="..." />
  </li>
</ol>

Disable touch swiping

Carousels support swiping left/right on touchscreen devices to move between slides. Add @otherprops="touch(false)" to disable this option.

<ol outputclass="carousel" otherprops="touch(false)">
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
  <li>
    <image href="..." />
  </li>
</ol>