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

<carousel>
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
</carousel>

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

Indicators

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

<carousel indicators="yes">
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
</carousel>

<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

<carousel>
  <carousel-item>
    <fig>
      <title>The First Slide</title>
      <image href="..." />
    </fig>
  </carousel-item>
  <carousel-item>
    <fig>
      <title>The Second Slide</title>
      <image href="..." />
    </fig>
  </carousel-item>
  <carousel-item>
    <fig>
      <title>The Third Slide</title>
      <image href="..." />
    </fig>
  </carousel-item>
</carousel>

<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 <grid-row> element to add them within a carousel. Additional structure and spacing can be added by using the <grid-col> element.

<carousel>
  <carousel-item>
    <grid-row>
      <grid-col colspan="1"/>
      <grid-col colspan="10">
      ...
      </grid-col>
    </grid-row>
  </carousel-item>
  <carousel-item>
    <grid-row>
      <grid-col colspan="1"/>
      <grid-col colspan="10">
      ...
      </grid-col>
    </grid-row>
  </carousel-item>
  <carousel-item>
    <grid-row>
      <grid-col colspan="1"/>
      <grid-col colspan="10">
      ...
      </grid-col>
    </grid-row>
  </carousel-item>
</carousel>

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

Multiple slides side-by-side

Add multiple <image> elements within each <carousel-item>

<carousel>
  <carousel-item>
    <image href="..." />
    <image href="..." />
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
    <image href="..." />
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
    <image href="..." />
    <image href="..." />
  </carousel-item>
</carousel>

<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 <carousel-item> and include a <grid-row> element for title texts.

<carousel>
  <carousel-item>
    <image href="..." />
    <image href="..." />
    <image href="..." />
    <grid-row deliveryTarget="html">
      <grid-col colspan="4">
        <p outputclass="text-center">...</p>
      </grid-col>
      <grid-col colspan="4">
        <p outputclass="text-center">...</p>
      </grid-col>
      <grid-col colspan="4">
        <p outputclass="text-center">...</p>
      </grid-col>
    </grid-row>
  </carousel-item>
  ...
</carousel>

Crossfade

Add @fade="yes" 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.

<carousel fade="yes">
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
</carousel>

<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 @autoplay="no" is set, the carousel won’t automatically start to cycle on page load. Instead, it will only start after the first user interaction.

<carousel autoplay="no">
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
</carousel>

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

Carousel interval

Add @interval="2000" to the <carousel> to change the amount of time to delay between automatically cycling to the next item.

<carousel interval="2000">
  ...
</carousel>

Individual carousel item interval

Add @interval="1000" to a <carousel-item> to change the amount of time to delay between automatically cycling to the next item.

<carousel>
  <carousel-item interval="2000">
    <image href="..." />
  </carousel-item>
  <carousel-item interval="1000">
    <image href="..." />
  </carousel-item>
  <carousel-item interval="3000">
    <image href="..." />
  </carousel-item>
</carousel>

<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 @touch="no" to disable this option.

<carousel touch="no">
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
  <carousel-item>
    <image href="..." />
  </carousel-item>
</carousel>

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