Carousel

The carousel is a slideshow component which can be used to cycle through content such as images or slides of text.

Create amazing Typeform-like forms and pages just by writing Markdown!

Overview #

Carousels work with a series of images, text, or custom markup, requiring a bit of JavaScript to handle everything. They also support previous/next controls and indicators. A few important things to know when using the carousel plugin:

  • For performance reasons, carousels must be manually initialized using the carousel constructor method. Without initialization, some of the event listeners (specifically, the events needed touch/swipe support) will not be registered until a user has explicitly activated a control or indicator.
  • When creating autoplaying carousels with the data-bs-ride="carousel" attribute, don't explicitly initialize them with the constructor method. These are initialized automatically on page load.
  • Nested carousels are not supported.

Here is a basic example of a carousel with three slides. Note the previous/next controls. We recommend using <button> elements, but you can also use <a> elements with role="button".

HTML
<div id="carousel-example-1" class="carousel slide">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-1" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-1" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

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.

You must add the .active class to one of the slides, otherwise the carousel will not be visible. Also be sure to set a unique id on the .carousel for optional controls, especially if you're using multiple carousels on a single page. Control and indicator elements must have a data-bs-target attribute (or href for links) that matches the id of the .carousel element.

Indicators and captions #

You can add indicators to the carousel with .carousel-indicators, alongside the previous/next controls. The indicators let users jump directly to a particular slide. You can also add captions to your slides with the .carousel-caption element within any .carousel-item. Please note, you may want to hide captions in smaller screens because of visibility issues with the actual slide image. The best way to do that would be using the display utilities.

HTML
<div id="carousel-example-2" class="carousel slide">
  <div class="carousel-indicators">
    <button type="button" data-bs-target="#carousel-example-2" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carousel-example-2" data-bs-slide-to="1" aria-label="Slide 2"></button>
    <button type="button" data-bs-target="#carousel-example-2" data-bs-slide-to="2" aria-label="Slide 3"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
      <div class="carousel-caption">
        <h1>Slide 1</h1>
        <p class="px-2">Placeholder content that spans across multiple lines.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
      <div class="carousel-caption">
        <h1>Slide 2</h1>
        <p class="px-2">Placeholder content that spans across multiple lines.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
      <div class="carousel-caption">
        <h1>Slide 3</h1>
        <p class="px-2">Placeholder content that spans across multiple lines.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-2" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-2" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Indicators and captions Color mode and contrast #

Depending on the user's color mode of choice (light vs dark) and the content of the carousel item, there may be contrast issues with the indicators and captions. In such cases, it is recommended that color utilities are used on captions, and the background for the indicators is styled to make sure the individual buttons are always at least somewhat visible.

In the example below, the first slide contains an image that is very light in color. The second slide contains an image that is very dark. In both cases, thanks to the extra utilities and styling described above, the indicators and captions are visible/readable in both color modes.

HTML
<div id="carousel-example-3" class="carousel slide">
  <div class="carousel-indicators rounded" style="background-color: hsla(var(--bs-emphasis-color-hsl), 0.1);">
    <button type="button" data-bs-target="#carousel-example-3" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button>
    <button type="button" data-bs-target="#carousel-example-3" data-bs-slide-to="1" aria-label="Slide 2"></button>
  </div>
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
      <div class="carousel-caption text-black">
        <h1>Slide 1</h1>
        <p class="px-2 mb-4">Placeholder content that spans across multiple lines.</p>
      </div>
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
      <div class="carousel-caption text-white">
        <h1>Slide 2</h1>
        <p class="px-2 mb-4">Placeholder content that spans across multiple lines.</p>
      </div>
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-3" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-3" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Crossfade #

Add .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 .bg-body or some custom CSS to the .carousel-item elements for proper crossfading.

HTML
<div id="carousel-example-4" class="carousel slide carousel-fade">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-4" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-4" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Autoplaying carousels #

You can make your carousels autoplay on page load by setting the ride option to carousel (e.g., using data-bs-ride="carousel"). Autoplaying carousels automatically pause while hovered with the mouse. This behavior can be controlled with the pause option. In browsers that support the Page Visibility API (opens in new tab), 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).

HTML
<div id="carousel-example-5" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-5" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-5" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

When the ride option is set to true (e.g., using data-bs-ride="true"), rather than carousel, the carousel won't automatically start to cycle on page load. Instead, it will only start after the first user interaction.

HTML
<div id="carousel-example-6" class="carousel slide" data-bs-ride="true">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-6" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-6" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Autoplaying carousels Individual item interval #

Add data-bs-interval="{interval}" to a .carousel-item to change the amount of time to delay between automatically cycling to the next item.

HTML
<div id="carousel-example-7" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active" data-bs-interval="10000">
      <img src="..." class="d-block w-100" alt="First slide">
    </div>
    <div class="carousel-item" data-bs-interval="2000">
      <img src="..." class="d-block w-100" alt="Second slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
    </div>
  </div>
  <button class="carousel-control-prev" type="button" data-bs-target="#carousel-example-7" data-bs-slide="prev">
    <span class="carousel-control-prev-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Previous</span>
  </button>
  <button class="carousel-control-next" type="button" data-bs-target="#carousel-example-7" data-bs-slide="next">
    <span class="carousel-control-next-icon" aria-hidden="true"></span>
    <span class="visually-hidden">Next</span>
  </button>
</div>

Autoplaying carousels Autoplaying carousels without controls #

Here's a carousel with slides only. This is generally not recommended, but it's available to use as you see fit.

HTML
<div id="carousel-example-8" class="carousel slide" data-bs-ride="carousel">
  <div class="carousel-inner">
    <div class="carousel-item active">
      <img src="..." class="d-block w-100" alt="First slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Second slide">
    </div>
    <div class="carousel-item">
      <img src="..." class="d-block w-100" alt="Third slide">
    </div>
  </div>
</div>

Disable touch swiping #

Carousels support swiping left/right on touchscreen devices to move between slides. This can be disabled by setting the touch option to false (e.g., using data-bs-touch="false").

JavaScript usage #

The examples on this page use data-bs-* attributes for functionality, which is usually enough to cover a majority of use-cases. You can read about options, methods, events, and more in the official Bootstrap documentation.

Carousel - Bootstrap
Continue reading on the offical documentation website

Up next
Collapse

Help us grow

Our main goal is to make Halfmoon the go-to framework for building websites, dashboards and tools. If you believe in our mission, consider becoming a sponsor and help us grow.

You can email us directly if you have any queries. We are always happy to answer.

Subscribe for updates

We will notify you when the framework gets a substantial update. No spam ever.

Follow us on Twitter so that you can stay updated that way.