Skip to main content

Components

Carousel

A slideshow built on a scroll-snap track — swipe, scroll or click an indicator; newer engines generate the controls.

How it works

The carousel is a horizontal scroll container. .carousel-inner scrolls with scroll-snap-type: x mandatory; each .carousel-item is a full-width snap point. Users swipe, use the scroll wheel or trackpad, press the arrow keys when the track has focus, or click an indicator — a plain anchor link to the slide's id.

  • Baseline: scroll-snap + fragment links. Every engine. The scrollbar is hidden; the track still scrolls.
  • Enhancement: engines with CSS scroll buttons and markers (::scroll-button(), ::scroll-marker) generate the previous/next arrows and the indicator pips from the track itself, and hide the hand-written .carousel-indicators. The current pip is lit through :target-current.
  • Enhancement: .carousel-fade crossfades slides with a scroll-driven animation (animation-timeline: view(inline)).
  • Fallback: nothing to fall back to; the baseline is the scroll track.
There is no autoplay, no data-bs-ride, no data-bs-slide, no .active slide class and no keyboard option. The hand-written indicators are links, not buttons. Engines without scroll markers show no "current slide" state on them.

Basic examples

Slides only

The minimum: a .carousel, a .carousel-inner track and .carousel-item slides. Scroll sideways or swipe.

HTML
<div class="carousel">
  <div class="carousel-inner">
    <div class="carousel-item" id="carousel-basic-1">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="First slide"><rect width="100%" height="100%" fill="var(--bs-navy-700)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">FIRST SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-basic-2">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Second slide"><rect width="100%" height="100%" fill="var(--bs-navy-500)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">SECOND SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-basic-3">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Third slide"><rect width="100%" height="100%" fill="var(--bs-navy-900)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">THIRD SLIDE</text></svg>
    </div>
  </div>
</div>

With controls

Previous and next arrows are generated by ::scroll-button(left) and ::scroll-button(right) where supported — nothing to add to the markup. They are real buttons: focusable, labelled "Previous" and "Next", and disabled at either end of the track. Engines without scroll buttons show the slides-only version above.

HTML
<div class="carousel">
  <div class="carousel-inner">
    <div class="carousel-item" id="carousel-controls-1">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="First slide"><rect width="100%" height="100%" fill="var(--bs-navy-700)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">FIRST SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-controls-2">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Second slide"><rect width="100%" height="100%" fill="var(--bs-navy-500)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">SECOND SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-controls-3">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Third slide"><rect width="100%" height="100%" fill="var(--bs-navy-900)"/><text x="50%" y="50%" dy=".3em" fill="var(--bs-gold-300)" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">THIRD SLIDE</text></svg>
    </div>
  </div>
</div>
The legacy .carousel-control-prev / .carousel-control-next classes still style a hand-written link, but a link can only point at one fixed slide; it cannot mean "the next one". They are hidden whenever the generated buttons exist.

With indicators

Add a .carousel-indicators block of anchors, one per slide, each linking to the slide's id. Where scroll markers are supported, the hand-written block is hidden and ::scroll-marker pips take its place — those do track the current slide.

HTML
<div class="carousel">
  <div class="carousel-inner">
    <div class="carousel-item" id="carousel-ind-1">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="First slide"><rect width="100%" height="100%" fill="var(--bs-navy-700)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">FIRST SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-ind-2">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Second slide"><rect width="100%" height="100%" fill="var(--bs-navy-500)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">SECOND SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-ind-3">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Third slide"><rect width="100%" height="100%" fill="var(--bs-navy-900)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">THIRD SLIDE</text></svg>
    </div>
  </div>
  <div class="carousel-indicators">
    <a href="#carousel-ind-1" aria-label="Slide 1"></a>
    <a href="#carousel-ind-2" aria-label="Slide 2"></a>
    <a href="#carousel-ind-3" aria-label="Slide 3"></a>
  </div>
</div>

With captions

.carousel-caption inside a slide. Hide it on small screens with .d-none .d-md-block as Bootstrap does.

HTML
<div class="carousel">
  <div class="carousel-inner">
    <div class="carousel-item" id="carousel-cap-1">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="First slide"><rect width="100%" height="100%" fill="var(--bs-navy-700)"/></svg>
      <div class="carousel-caption d-none d-md-block">
        <h5>Clash at the Coliseum, 1987</h5>
        <p>Two out of three falls. The third went twenty-two minutes.</p>
      </div>
    </div>
    <div class="carousel-item" id="carousel-cap-2">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Second slide"><rect width="100%" height="100%" fill="var(--bs-navy-500)"/></svg>
      <div class="carousel-caption d-none d-md-block">
        <h5>Steel Cage Summer, 1994</h5>
        <p>The belt changed hands at the top of the cage.</p>
      </div>
    </div>
    <div class="carousel-item" id="carousel-cap-3">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Third slide"><rect width="100%" height="100%" fill="var(--bs-navy-900)"/></svg>
      <div class="carousel-caption d-none d-md-block">
        <h5>Last Call, 2002</h5>
        <p>Doors closed at midnight.</p>
      </div>
    </div>
  </div>
  <div class="carousel-indicators">
    <a href="#carousel-cap-1" aria-label="Slide 1"></a>
    <a href="#carousel-cap-2" aria-label="Slide 2"></a>
    <a href="#carousel-cap-3" aria-label="Slide 3"></a>
  </div>
</div>

Crossfade

.carousel-fade fades each slide in and out as it moves through the viewport, using a scroll-driven animation. The slide still scrolls underneath; the opacity ramps so the motion reads as a crossfade. Without scroll-driven animations it is a plain slide.

HTML
<div class="carousel carousel-fade">
  <div class="carousel-inner">
    <div class="carousel-item" id="carousel-fade-1">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="First slide"><rect width="100%" height="100%" fill="var(--bs-navy-700)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">FIRST SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-fade-2">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Second slide"><rect width="100%" height="100%" fill="var(--bs-navy-500)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">SECOND SLIDE</text></svg>
    </div>
    <div class="carousel-item" id="carousel-fade-3">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Third slide"><rect width="100%" height="100%" fill="var(--bs-navy-900)"/><text x="50%" y="50%" fill="var(--bs-gold-300)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">THIRD SLIDE</text></svg>
    </div>
  </div>
  <div class="carousel-indicators">
    <a href="#carousel-fade-1" aria-label="Slide 1"></a>
    <a href="#carousel-fade-2" aria-label="Slide 2"></a>
    <a href="#carousel-fade-3" aria-label="Slide 3"></a>
  </div>
</div>

Autoplay

Not available. A carousel that advances on its own needs a timer, and a timer needs a script. The theme's position is that this is a feature, not a gap: motion the user did not ask for is the most common WCAG 2.2.2 failure on marketing pages. If you need a rotating hero, link to a page per slide instead. data-bs-ride and data-bs-interval are inert.

Dark variant

.carousel-dark flips the generated arrows, the pips and the captions to black for light slides. Note that Bootstrap 5.3 deprecates this class in favour of data-bs-theme="dark" on the carousel; both work here.

HTML
<div class="carousel carousel-dark">
  <div class="carousel-inner">
    <div class="carousel-item" id="carousel-dark-1">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="First slide"><rect width="100%" height="100%" fill="var(--bs-cream-300)"/><text x="50%" y="50%" fill="var(--bs-navy-700)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">FIRST SLIDE</text></svg>
      <div class="carousel-caption d-none d-md-block">
        <h5>First slide label</h5>
        <p>Some representative placeholder content for the first slide.</p>
      </div>
    </div>
    <div class="carousel-item" id="carousel-dark-2">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Second slide"><rect width="100%" height="100%" fill="var(--bs-cream-100)"/><text x="50%" y="50%" fill="var(--bs-navy-700)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">SECOND SLIDE</text></svg>
      <div class="carousel-caption d-none d-md-block">
        <h5>Second slide label</h5>
        <p>Some representative placeholder content for the second slide.</p>
      </div>
    </div>
    <div class="carousel-item" id="carousel-dark-3">
      <svg class="d-block w-100" width="800" height="400" viewBox="0 0 800 400" role="img" aria-label="Third slide"><rect width="100%" height="100%" fill="var(--bs-gold-300)"/><text x="50%" y="50%" fill="var(--bs-navy-700)" dy=".3em" text-anchor="middle" font-family="var(--bs-font-display)" font-size="48">THIRD SLIDE</text></svg>
      <div class="carousel-caption d-none d-md-block">
        <h5>Third slide label</h5>
        <p>Some representative placeholder content for the third slide.</p>
      </div>
    </div>
  </div>
  <div class="carousel-indicators">
    <a href="#carousel-dark-1" aria-label="Slide 1"></a>
    <a href="#carousel-dark-2" aria-label="Slide 2"></a>
    <a href="#carousel-dark-3" aria-label="Slide 3"></a>
  </div>
</div>

Accessibility

  • Give every slide image an accessible name (alt, or role="img" + aria-label on an SVG).
  • The track is a scroll container, so keyboard users can focus it and use the arrow keys. Generated scroll buttons are focusable and announced as "Previous" and "Next".
  • Indicator links need an aria-label; their text is pushed off-screen.
  • Because there is no autoplay, there is no pause control to provide.
  • scroll-behavior: smooth is set on the track; engines honour prefers-reduced-motion for scroll smoothing at the OS level.

CSS

Bootstrap's carousel variables apply, plus the ones the theme sets for the generated controls.

:root {
  --bs-carousel-indicator-active-bg: #fff;
  --bs-carousel-caption-color: #fff;
  --bs-carousel-control-icon-filter: ;
}

.carousel-dark {
  --bs-carousel-indicator-active-bg: #000;
  --bs-carousel-caption-color: #000;
  --bs-carousel-control-icon-filter: invert(1) grayscale(100);
}

The pieces from scss/components/_carousel.scss:

.carousel-inner                           // flex track, scroll-snap-type: x mandatory, scrollbar hidden
.carousel-item                            // flex: 0 0 100%, scroll-snap-align: start
.carousel-indicators > a                  // hand-written indicator links
.carousel-inner::scroll-button(left)      // generated "Previous" (progressive)
.carousel-inner::scroll-button(right)     // generated "Next"
.carousel-inner::scroll-marker-group      // generated pip row, positioned like .carousel-indicators
.carousel-item::scroll-marker             // one pip per slide
.carousel-item::scroll-marker:target-current  // the current pip
.carousel-fade .carousel-item             // animation-timeline: view(inline) (progressive)