Carousel·续

<Example code={&lt;div id="carouselVariable" class="carousel carousel-auto slide" data-bs-ends="stop" style="--bs-carousel-items-gap: 1rem;">&lt;!--[!code highlight]--> &lt;div class="d-flex justify-content-between align-items-center"> &lt;h5 class="mb-0">Mixed widths&lt;/h5> &lt;div> &lt;button class="btn-icon btn-sm" type="button" data-bs-target="#carouselVariable" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;"> &lt;span class="carousel-icon-prev" aria-hidden="true">&lt;/span> &lt;span class="visually-hidden">Previous&lt;/span> &lt;/button> &lt;button class="btn-icon btn-sm" type="button" data-bs-target="#carouselVariable" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;"> &lt;span class="carousel-icon-next" aria-hidden="true">&lt;/span> &lt;span class="visually-hidden">Next&lt;/span> &lt;/button> &lt;/div> &lt;/div> &lt;div class="carousel-inner"> &lt;div class="carousel-item active" style="width: 160px;">&lt;!--[!code highlight]--> &lt;/div> &lt;div class="carousel-item" style="width: 320px;">&lt;!--[!code highlight]--> &lt;/div> &lt;div class="carousel-item" style="width: 220px;">&lt;!--[!code highlight]--> &lt;/div> &lt;div class="carousel-item" style="width: 380px;">&lt;!--[!code highlight]--> &lt;/div> &lt;div class="carousel-item" style="width: 200px;">&lt;!--[!code highlight]--> &lt;/div> &lt;div class="carousel-item" style="width: 300px;">&lt;!--[!code highlight]--> &lt;/div> &lt;/div> &lt;/div>} />

Add .carousel-center to snap the active slide to the center of the viewport instead of its start—pairs nicely with --bs-carousel-items-peek.

Autoplay

Set the autoplay option to true (or add data-bs-autoplay="true") to cycle a carousel automatically on page load. Autoplay pauses on hover—configurable with the pause option—and, where the Page Visibility API is supported, while the page isn’t visible. As soon as a visitor takes control—clicking a control or indicator, using the keyboard, or swiping—autoplay stops for good, so content isn’t moved out from under them.

For accessibility reasons, we recommend avoiding the use of autoplaying carousels. If your page does include one, provide a discoverable control to pause and resume it: add a .carousel-control-play-pause button (shown below). This satisfies WCAG 2.2 Success Criterion 2.2.2 Pause, Stop, Hide, which a hover- or focus-only pause does not.

The play/pause button toggles autoplay and reflects the current state automatically—a pause icon while playing, a play icon while stopped. Give each state an accessible name with the data-bs-play-label and data-bs-pause-label attributes. While playing, the active indicator fills like a progress bar over the current slide’s interval as a visual countdown; it pauses with autoplay and is disabled under reduced motion. Set its color with the --bs-carousel-indicator-progress-bg CSS variable.

<div class="carousel-inner"> <div class="carousel-item active"> </div> <div class="carousel-item"> </div> <div class="carousel-item"> </div> </div> <div class="d-flex justify-content-between align-items-center"> <div class="carousel-indicators"> <button type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button> <button type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide-to="1" aria-label="Slide 2"></button> <button type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide-to="2" aria-label="Slide 3"></button> </div> <div> <button class="btn-icon btn-sm carousel-control-play-pause" type="button" data-bs-target="#carouselExampleAutoplaying" aria-label="Pause" data-bs-pause-label="Pause" data-bs-play-label="Play"> <span class="carousel-icon-pause" aria-hidden="true"></span> <span class="carousel-icon-play" aria-hidden="true"></span> </button> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide="prev"> <span class="carousel-icon-prev" aria-hidden="true"></span> <span class="visually-hidden">Previous</span> </button> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselExampleAutoplaying" data-bs-slide="next"> <span class="carousel-icon-next" aria-hidden="true"></span> <span class="visually-hidden">Next</span> </button> </div> </div> </div>`} />

Individual intervals

Add data-bs-interval="" to a .carousel-item to change the amount of time to delay between automatically cycling to the next item. The indicator’s progress fill matches each slide’s own interval, so the countdown speeds up or slows down to match (2s, then 4s, then 6s below).

<div class="carousel-inner rounded-5"> <div class="carousel-item active" data-bs-interval="2000"> </div> <div class="carousel-item" data-bs-interval="4000"> </div> <div class="carousel-item" data-bs-interval="6000"> </div> </div> <div class="d-flex justify-content-between align-items-center mt-3"> <div class="carousel-indicators"> <button type="button" data-bs-target="#carouselExampleInterval" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button> <button type="button" data-bs-target="#carouselExampleInterval" data-bs-slide-to="1" aria-label="Slide 2"></button> <button type="button" data-bs-target="#carouselExampleInterval" data-bs-slide-to="2" aria-label="Slide 3"></button> </div> <button class="btn-icon btn-sm carousel-control-play-pause" type="button" data-bs-target="#carouselExampleInterval" aria-label="Pause" data-bs-pause-label="Pause" data-bs-play-label="Play"> <span class="carousel-icon-pause" aria-hidden="true"></span> <span class="carousel-icon-play" aria-hidden="true"></span> </button> </div> </div>`} />

End behavior

The ends option controls what happens at the first and last slide. Set it with data-bs-ends (or the ends option in JavaScript), choosing from loop (the default), wrap, or stop.

Loop (default)

With data-bs-ends="loop" the carousel scrolls seamlessly past the ends: stepping next from the last slide (or previous from the first) continues in the same direction into the destination slide instead of jumping back, for an endless conveyor effect. This is the default, so it applies with or without the attribute. Seamless looping applies to single-slide carousels driven by the controls, keyboard, or autoplay; multi-item, peek, centered, and variable-width layouts—as well as users who prefer reduced motion—fall back to the wrap jump.

<div class="d-flex justify-content-between align-items-center"> <h5 class="mb-0">Loop</h5> <div> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsLoop" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;"> <span class="carousel-icon-prev" aria-hidden="true"></span> <span class="visually-hidden">Previous</span> </button> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsLoop" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;"> <span class="carousel-icon-next" aria-hidden="true"></span> <span class="visually-hidden">Next</span> </button> </div> </div> <div class="carousel-inner rounded-5"> <div class="carousel-item active"> </div> <div class="carousel-item"> </div> <div class="carousel-item"> </div> </div> </div>`} />

Wrap

With data-bs-ends="wrap" the carousel jumps from the last slide back to the first, and vice versa, so the controls never reach a dead end.

<div class="d-flex justify-content-between align-items-center"> <h5 class="mb-0">Wrap around</h5> <div> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsWrap" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;"> <span class="carousel-icon-prev" aria-hidden="true"></span> <span class="visually-hidden">Previous</span> </button> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsWrap" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;"> <span class="carousel-icon-next" aria-hidden="true"></span> <span class="visually-hidden">Next</span> </button> </div> </div> <div class="carousel-inner rounded-5"> <div class="carousel-item active"> </div> <div class="carousel-item"> </div> <div class="carousel-item"> </div> </div> </div>`} />

Stop

With data-bs-ends="stop" the carousel hard-stops at the first and last slide. The previous control is automatically disabled on the first slide and the next control on the last (via the native disabled attribute on <button> controls); when a focused control becomes disabled, focus shifts to the opposite control so it isn’t lost.

<div class="d-flex justify-content-between align-items-center"> <h5 class="mb-0">Stop at the ends</h5> <div> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsStop" data-bs-slide="prev" style="--bs-carousel-control-icon-width: 1rem;"> <span class="carousel-icon-prev" aria-hidden="true"></span> <span class="visually-hidden">Previous</span> </button> <button class="btn-icon btn-sm" type="button" data-bs-target="#carouselEndsStop" data-bs-slide="next" style="--bs-carousel-control-icon-width: 1rem;"> <span class="carousel-icon-next" aria-hidden="true"></span> <span class="visually-hidden">Next</span> </button> </div> </div> <div class="carousel-inner rounded-5"> <div class="carousel-item active"> </div> <div class="carousel-item"> </div> <div class="carousel-item"> </div> </div> </div>`} />

Add data-bs-theme="dark" to the .carousel for darker controls and indicators. This is typically most useful with overlay carousels when you need the reverse contrast against the background of the slides.

<div class="carousel-inner"> <div class="carousel-item active" data-bs-interval="10000"> </div> <div class="carousel-item" data-bs-interval="2000"> </div> <div class="carousel-item"> </div> </div> <div class="carousel-overlay-controls"> <button class="btn-icon btn-sm btn-subtle theme-secondary" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="prev"> <span class="carousel-icon-prev" aria-hidden="true"></span> <span class="visually-hidden">Previous</span> </button> <div class="carousel-indicators"> <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="0" class="active" aria-current="true" aria-label="Slide 1"></button> <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="1" aria-label="Slide 2"></button> <button type="button" data-bs-target="#carouselExampleDark" data-bs-slide-to="2" aria-label="Slide 3"></button> </div> <button class="btn-icon btn-sm btn-subtle theme-secondary" type="button" data-bs-target="#carouselExampleDark" data-bs-slide="next"> <span class="carousel-icon-next" aria-hidden="true"></span> <span class="visually-hidden">Next</span> </button> </div> </div>`} />

CSS

Variables

Tokens for all carousels:

Usage

Via data attributes

Use data attributes to easily control the position of the carousel. data-bs-slide accepts the keywords prev or next, which alters the slide position relative to its current position. Alternatively, use data-bs-slide-to to pass a raw slide index to the carousel data-bs-slide-to="2", which shifts the slide position to a particular index beginning with 0.

Attribute Description
data-bs-autoplay Set to true to autoplay the carousel on load.
data-bs-slide prev or next to move the carousel relative to the current slide.
data-bs-slide-to Zero-based index of the slide to show.
data-bs-interval Autoplay interval in milliseconds between slides.
data-bs-ends How the carousel behaves at its ends: stop, wrap, or loop.
data-bs-play-label On a .carousel-control-play-pause button, the aria-label to apply while autoplay is stopped.
data-bs-pause-label On a .carousel-control-play-pause button, the aria-label to apply while autoplay is playing.

Via JavaScript

Call carousel manually with:

const carousel = new bootstrap.Carousel('#myCarousel')

Dependencies

Options

Name Type Default Description
autoplay boolean false If set to true, autoplays the carousel on load. Otherwise the carousel does not autoplay.
ends string "loop" How the carousel behaves at its ends. "stop" hard-stops at the first/last slide—and disables the previous control on the first slide and the next control on the last (via the native disabled attribute on <button> controls, so <a> controls aren’t affected). "wrap" jumps from the last slide back to the first (and vice versa), and "loop" scrolls seamlessly past the ends for single-slide carousels (falling back to "wrap" for multi-item/peek/centered/variable-width layouts and under reduced motion).
interval number 5000 The amount of time to delay between automatically cycling an item.
keyboard boolean true Whether the carousel should react to keyboard events.
pause string, boolean "hover" If set to "hover", pauses the cycling of the carousel on mouseenter and resumes it on mouseleave. If set to false, hovering over the carousel won’t pause it.

The number of visible slides, the gap between them, and the peek of adjacent slides are controlled with CSS, not these options—see Items.

Methods

You can create a carousel instance with the carousel constructor, and pass on any additional options. For example, to manually initialize an autoplaying carousel (assuming you’re not using the data-bs-autoplay="true" attribute in the markup itself) with a specific interval, you can use:

const myCarouselElement = document.querySelector('#myCarousel')

const carousel = new bootstrap.Carousel(myCarouselElement, {
  autoplay: true,
  interval: 2000
})
Method Description
cycle Starts cycling through the carousel items from left to right.
dispose Destroys an element’s carousel. (Removes stored data on the DOM element)
getInstance Static method which allows you to get the carousel instance associated to a DOM element. You can use it like this: bootstrap.Carousel.getInstance(element).
getOrCreateInstance Static method which returns a carousel instance associated to a DOM element, or creates a new one in case it wasn’t initialized. You can use it like this: bootstrap.Carousel.getOrCreateInstance(element).
next Cycles to the next item. Returns to the caller before the next item has been shown (e.g., before the slid.bs.carousel event occurs).
nextWhenVisible Don’t cycle carousel to next when the page, the carousel, or the carousel’s parent aren’t visible. Returns to the caller before the target item has been shown.
pause Stops the carousel from cycling through items.
prev Cycles to the previous item. Returns to the caller before the previous item has been shown (e.g., before the slid.bs.carousel event occurs).
to Cycles the carousel to a particular frame (0 based, similar to an array). Returns to the caller before the target item has been shown (e.g., before the slid.bs.carousel event occurs).

Events

Bootstrap’s carousel class exposes two events for hooking into carousel functionality. Both events have the following additional properties:

  • direction: The direction in which the carousel is sliding (either "left" or "right").
  • relatedTarget: The DOM element that is being slid into place as the active item.
  • from: The index of the current item
  • to: The index of the next item

All carousel events are fired at the carousel itself (i.e. at the <div class="carousel">).

Event type Description
slid.bs.carousel Fired when the new slide has scrolled into place and settled (in .carousel-fade, once the crossfade is applied). A multi-slide to() jump may emit intermediate slid events as it scrolls past slides.
slide.bs.carousel Fires immediately when the slide instance method is invoked.
const myCarousel = document.getElementById('myCarousel')

myCarousel.addEventListener('slide.bs.carousel', event => {
  // do something...
})