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 <div> element to add them within a carousel. Additional structure and spacing can be added by setting the @outputclass="col-*" attribute.

Is it for fear to wet a widow’s eye
That thou consum’st thyself in single life?
Ah, if thou issueless shalt hap to die,
The world will wail thee like a makeless wife;

The world will be thy widow and still weep
That thou no form of thee hast left behind,
When every private widow well may keep,
By children’s eyes, her husband’s shape in mind.

Look what an unthrift in the world doth spend
Shifts but his place, for still the world enjoys it;
But beauty’s waste hath in the world an end,
And, kept unused, the user so destroys it.

No love toward others in that bosom sits
That on himself such murd’rous shame commits.

Sonnet 9 - William Shakespeare

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

<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 <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 <div> element for title texts.

First Image

Second Image

Third Image

Fourth Image

Fifth Image

Sixth Image

Seventh Image

Eighth Image

Ninth Image

<carousel>
  <carousel-item>
    <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>
  </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>