Loading...
Skip to main content

Carousel

A slider or slideshow component for cycling through series of content, ranging from products to images and more, one at a time.

How it works

  • Carousel is built on CSS’s scroll-snap, so sliding, touch dragging, momentum, and keyboard scrolling all come from the browser. The React component manages autoplay, the previous/next controls, the indicators, and active-slide syncing.

  • Because the slides live in a real scroll container, the carousel can show more than one slide at a time, reveal a “peek” of the neighboring slides, and mix variable-width slides—all controlled with CSS.

  • Carousels can have any number of slides, with just about any content within. Our examples show images and text, but you can put anything you like inside each CarouselSlide. We don't support nested carousels.

  • Carousel items or slides do not normalize their dimensions. As such, you may need to use utilities through className or custom styles to size content. Previous/next controls and indicators are optional; add and customize them as needed.

  • Carousel initializes on mount, including active-slide syncing as the user scrolls or swipes. Pass autoplay for autoplaying carousels. Do not initialize the same carousel with Bootstrap’s JavaScript plugin.

  • The React wrapper starts on the first slide. It manages the active state that drives indicator syncing and, with fade, which slide is shown. A child’s active prop does not select the initial slide. Controls and indicators are scoped to their own carousel, so multiple instances do not need Bootstrap target attributes.

The animation effect of this component is dependent on the prefers-reduced-motion media query. Slides swap immediately and the autoplay indicator countdown is disabled for users who prefer reduced motion.

Examples

Top controls

The default carousel has a simple design that you can customize. Controls can be placed outside the inner carousel container. They can sit at the top or bottom, with additional content alongside them. Use controlsStart for content at the start of the controls row.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Top controls"
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Top controls</h5>}
id="carouselStacked"
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Bottom controls

Similar to the controls on top, but with the controls at the bottom of the carousel and different content.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Bottom controls"
controlsPlacement="bottom"
id="carouselStackedBottom"
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Indicators

Pass indicators to include slide indicator buttons and use indicatorPlacement to position them within the controls row. With an overlay carousel, the row sits over the bottom of the slides; its alignment determines where the indicators appear.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Indicators"
controlsPlacement="bottom"
id="carouselStackedIndicators"
indicatorPlacement="end"
indicators
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Custom content

You can put any content inside each CarouselSlide. Add content, then size and style it with utilities through className or CSS Modules as needed.

<Carousel
aria-label="Custom content"
controlsClassName="d-flex justify-content-center gap-2"
controlsPlacement="bottom"
id="carouselExampleContent"
indicatorPlacement="between"
innerClassName="rounded-5"
>
<CarouselSlide>
<div
className="d-flex flex-column justify-content-center bg-subtle-primary p-9 bg-1 rounded-5"
style={{
minHeight: 320
}}
>
<h3>
Build anything
</h3>
<p className="fg-emphasis-secondary mb-3">
Compose slides from your own markup—text, buttons, cards, or media.
</p>
<div>
<Button
href="#"
theme="primary"
variant="solid"
>
Get started
</Button>
</div>
</div>
</CarouselSlide>
<CarouselSlide>
<div
className="d-flex flex-column justify-content-center text-center bg-subtle-success p-9 bg-2 rounded-5"
style={{
minHeight: 320
}}
>
<h3>
Style it your way
</h3>
<p className="fg-emphasis-secondary mb-3">
Use utilities or custom CSS to size and theme each slide however you need.
</p>
<div>
<Button
href="#"
theme="success"
variant="solid"
>
Learn more
</Button>
</div>
</div>
</CarouselSlide>
<CarouselSlide>
<div
className="d-flex flex-column justify-content-center text-end bg-subtle-warning p-9 bg-3 rounded-5"
style={{
minHeight: 320
}}
>
<h3>
Mix and match
</h3>
<p className="fg-emphasis-secondary mb-3">
Combine custom content with controls, indicators, and the overlay layout.
</p>
<div>
<Button
href="#"
theme="inverse"
variant="solid"
>
Browse examples
</Button>
</div>
</div>
</CarouselSlide>
</Carousel>

Modifiers

Change the default carousel appearance with alternate control placement and animations.

Overlay controls

Use controlsPlacement="overlay" to overlay carousel controls on top of the slides. The component wraps its controls in the overlay row automatically.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Overlay controls"
controlsPlacement="overlay"
id="carouselExample"
indicatorPlacement="end"
indicators
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Crossfade

Pass fade to animate slides with a fade transition instead of a slide. Depending on your content (e.g., text-only slides), you may want to add bg-body or a CSS module to the slides for proper crossfading. The crossfade is a CSS opacity transition over --bs-carousel-fade-duration, and collapses to an instant swap for users who prefer reduced motion.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Crossfade"
controlsPlacement="bottom"
fade
id="carouselExampleFade"
>
<CarouselSlide>
<CarouselImage rounded>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
rounded
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
rounded
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Items

Because the carousel is a real scroll container, you can change how many slides are visible and how they’re sized with a few CSS custom properties on Carousel without writing any JavaScript.

  • --bs-carousel-items sets the number of whole slides visible per view (default 1).
  • --bs-carousel-items-gap sets the space between slides (default 0px).
  • --bs-carousel-items-peek sets how much of the neighboring slides to reveal (default 0px).

Multiple items

Set items to show several slides at once. Combine it with itemsGap for spacing; these props set the corresponding CSS custom properties.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Multiple items"
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Three at a time</h5>}
ends="stop"
id="carouselMultiple"
items={3}
itemsGap="1rem"
>
<CarouselSlide>
<CarouselImage
background="#777"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
1
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#6c6c6c"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
2
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
3
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#5c5c5c"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
4
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
5
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#4c4c4c"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
6
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#444"
color="#fff"
height={200}
large={false}
rounded
width={260}
>
7
</CarouselImage>
</CarouselSlide>
</Carousel>

Set items={3} to control the count, or set --bs-carousel-items through a CSS module for responsive layouts.

Navigation follows distinct, reachable scroll-snap positions, not every card independently. Targets beyond the scroll range share one end position, represented by the first slide that reaches it. activeIndex and onChange identify that slide; active does not mean it is the only visible card. Controls, indicators, swipe synchronization, and autoplay use the same positions, so there are no extra steps at the end. Selecting another slide that shares the end position selects its representative instead. Positions are recalculated when the viewport or slides resize. Autoplay uses the representative slide’s interval.

Peeking

Set itemsPeek to reveal a sliver of the previous and next slides, hinting that there’s more to scroll.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Peeking"
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Peek the neighbors</h5>}
ends="stop"
id="carouselPeek"
itemsGap="1rem"
itemsPeek="3rem"
>
<CarouselSlide>
<CarouselImage
background="#777"
color="#fff"
height={300}
rounded
>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#fff"
height={300}
rounded
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#fff"
height={300}
rounded
>
Third slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#444"
color="#fff"
height={300}
rounded
>
Fourth slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#333"
color="#fff"
height={300}
rounded
>
Fifth slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Variable width

Pass auto and size each CarouselSlide yourself with className, style, or a CSS Module. Snap points still land on every slide.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Variable width"
auto
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Mixed widths</h5>}
ends="stop"
id="carouselVariable"
itemsGap="1rem"
>
<CarouselSlide
style={{
width: 160
}}
>
<CarouselImage
background="#777"
color="#fff"
height={200}
large={false}
rounded
width={160}
>
A
</CarouselImage>
</CarouselSlide>
<CarouselSlide
style={{
width: 320
}}
>
<CarouselImage
background="#666"
color="#fff"
height={200}
large={false}
rounded
width={320}
>
B
</CarouselImage>
</CarouselSlide>
<CarouselSlide
style={{
width: 220
}}
>
<CarouselImage
background="#555"
color="#fff"
height={200}
large={false}
rounded
width={220}
>
C
</CarouselImage>
</CarouselSlide>
<CarouselSlide
style={{
width: 380
}}
>
<CarouselImage
background="#4c4c4c"
color="#fff"
height={200}
large={false}
rounded
width={380}
>
D
</CarouselImage>
</CarouselSlide>
<CarouselSlide
style={{
width: 200
}}
>
<CarouselImage
background="#444"
color="#fff"
height={200}
large={false}
rounded
width={200}
>
E
</CarouselImage>
</CarouselSlide>
<CarouselSlide
style={{
width: 300
}}
>
<CarouselImage
background="#333"
color="#fff"
height={200}
large={false}
rounded
width={300}
>
F
</CarouselImage>
</CarouselSlide>
</Carousel>

Pass center to snap the active slide to the center of the viewport instead of its start—pairs nicely with itemsPeek.

Autoplay

Set autoplay to true to cycle a carousel automatically on page load. Autoplay pauses on hover—configurable with the pause option—and while the page isn’t visible, using the Page Visibility API. As soon as a visitor takes control—clicking a control or indicator, using the keyboard, or swiping—autoplay stops, 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: pass playPause to add a 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 wrapper also includes this button automatically when autoplay is enabled.

The play/pause button reflects the current state automatically—a pause icon while playing, a play icon while stopped. The wrapper supplies an accessible name for each state. 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.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Autoplay"
autoplay
controlsPlacement="bottom"
id="carouselExampleAutoplaying"
indicators
playPause
>
<CarouselSlide>
<CarouselImage rounded>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
rounded
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
rounded
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Individual intervals

Pass interval to a CarouselSlide to change the 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).

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Individual intervals"
autoplay
controls={false}
controlsClassName="d-flex justify-content-between align-items-center mt-3"
controlsPlacement="bottom"
id="carouselExampleInterval"
indicators
innerClassName="rounded-5"
playPause
>
<CarouselSlide interval={2000}>
<CarouselImage>
First: 2 seconds
</CarouselImage>
</CarouselSlide>
<CarouselSlide interval={4000}>
<CarouselImage
background="#666"
color="#444"
>
Second: 4 seconds
</CarouselImage>
</CarouselSlide>
<CarouselSlide interval={6000}>
<CarouselImage
background="#555"
color="#333"
>
Third: 6 seconds
</CarouselImage>
</CarouselSlide>
</Carousel>

End behavior

The ends prop controls what happens at the first and last slide. Choose from loop (the default), wrap, or stop.

Loop (default)

With 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 prop. Seamless looping applies to full-width single-slide carousels driven by the controls, keyboard, or autoplay. Multi-item, peek, centered, and variable-width layouts fall back to wrap: a smooth scroll back across the content, not a same-direction seamless loop. Reduced motion switches immediately instead.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Loop"
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Loop</h5>}
ends="loop"
id="carouselEndsLoop"
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage rounded>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
rounded
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
rounded
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Wrap

With ends="wrap" the carousel scrolls back from the last reachable position to the first, and vice versa, so the controls never reach a dead end. This scroll has intermediate positions under normal motion preferences and is immediate under reduced motion.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Wrap"
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Wrap around</h5>}
ends="wrap"
id="carouselEndsWrap"
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Stop

With 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; when a focused control becomes disabled, focus shifts to the opposite control so it isn’t lost.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Stop"
controlsPlacement="top"
controlsStart={<h5 className="mb-0">Stop at the ends</h5>}
ends="stop"
id="carouselEndsStop"
innerClassName="rounded-5"
>
<CarouselSlide>
<CarouselImage>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#666"
color="#444"
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#555"
color="#333"
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

Dark carousel

Set data-bs-theme="dark" on 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.

document/component/Document/CarouselImage/index.tsx
<Carousel
aria-label="Dark carousel"
controlsPlacement="overlay"
data-bs-theme="dark"
id="carouselExampleDark"
indicatorPlacement="between"
indicators
>
<CarouselSlide interval={10000}>
<CarouselImage
background="#f5f5f5"
color="#aaa"
rounded
>
First slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide interval={2000}>
<CarouselImage
background="#eee"
color="#bbb"
rounded
>
Second slide
</CarouselImage>
</CarouselSlide>
<CarouselSlide>
<CarouselImage
background="#e5e5e5"
color="#999"
rounded
>
Third slide
</CarouselImage>
</CarouselSlide>
</Carousel>

CSS

Variables

Local CSS custom properties expose spacing, colors, sizing, and transitions for all carousels. Override them through style or a CSS module. These defaults come from Bootstrap 6.0.0-alpha.1; see the variable reference for the control icon masks.

VariableDefault
--bs-carousel-gap0.75rem
--bs-carousel-indicator-bgvar(--bs-fg-3)
--bs-carousel-indicator-width0.75rem
--bs-carousel-indicator-height0.75rem
--bs-carousel-indicator-spacer0.25rem
--bs-carousel-indicator-opacity-duration0.6s
--bs-carousel-indicator-opacity-timingease
--bs-carousel-indicator-width-duration0.3s
--bs-carousel-indicator-width-timingease
--bs-carousel-indicator-progress-bgvar(--bs-carousel-indicator-bg)
--bs-carousel-control-icon-width1rem
--bs-carousel-items1
--bs-carousel-items-gap0px
--bs-carousel-items-peek0px
--bs-carousel-fade-duration0.6s
--bs-carousel-fade-timingease

The React controls use Icon with Bootstrap Icons rather than Bootstrap’s CSS-mask glyphs. The active countdown sets --bs-carousel-interval to the current slide’s interval in milliseconds.

Usage

Via props

Use props to control the carousel rather than Bootstrap’s data-attribute plugin. Previous/next buttons and indicator buttons are wired automatically to their own instance.

PropDescription
autoplayAutomatically cycle through slides on mount.
intervalAutoplay interval in milliseconds between slides; individual slides can override it.
endsChoose stop, wrap, or loop behavior at the ends.
playPauseRender an accessible play/pause control.
controlsPlacementPut the controls at the top, bottom, or over the slides.
controlsStartContent to display at the start of the controls row.
controlsClassNameBootstrap utilities or a CSS module for the non-overlay controls row.
innerClassNameBootstrap utilities or a CSS module for the scroll viewport.
indicatorPlacementPosition indicators before, after, or between the previous/next buttons.

Via React

Mount the component to initialize it. Timers and scroll listeners are cleaned up on unmount.

import { Carousel, CarouselSlide } from 'idea-react';

<Carousel aria-label="My carousel" controlsPlacement="bottom" indicators>
<CarouselSlide>First slide</CarouselSlide>
<CarouselSlide>Second slide</CarouselSlide>
</Carousel>;

Dependencies

Load Bootstrap CSS and Bootstrap Icons alongside Idea React. The component manages its own state and scrolling and does not require Bootstrap’s JavaScript plugin. Follow the installation guide.

Options

PropTypeDefaultDescription
autoplaybooleanfalseAutomatically cycle through slides on mount.
endsstring"loop"stop disables previous/next at the reachable ends. wrap smoothly scrolls to the opposite end. loop scrolls seamlessly for full-width single-slide carousels, falling back to wrap for multi-item, peek, centered, and variable-width layouts. Reduced motion switches immediately.
intervalnumber5000Delay in milliseconds between automatically cycling an item.
keyboardbooleantrueReact to left/right arrow keys outside editable controls.
pausestring, boolean"hover"Pause temporarily while the pointer or focus is inside the carousel. Pass false to disable this pause.
controlsbooleantrueRender previous and next buttons.
controlsPlacementstring"overlay"Choose top, bottom, or overlay.
indicatorsbooleanfalseRender slide indicators.
indicatorPlacementstring"start"Choose start, end, or between.
playPausebooleanfalseProvide an explicit autoplay control; also included automatically for autoplay.
autobooleanfalseLet slides retain their individual widths.
centerbooleanfalseSnap the active slide to the center of the viewport.
fadebooleanfalseCrossfade stacked slides instead of scrolling.

The visible slide count, gap, and peek are controlled with CSS custom properties, exposed through items, itemsGap, and itemsPeek—see Items.

Methods

For imperative controls, attach a React ref to Carousel and use its model methods. Methods return before the scrolling or crossfade has visually completed.

Scroll and crossfade modes expose the same model methods and selection/playback state. Changing fade replaces the mode model while preserving selection and playback intent, so read carousel.current.store when needed rather than caching the model across mode changes. Layout and control updates keep the existing model and do not restart an unchanged autoplay interval.

import { createRef } from 'react';
import { Carousel } from 'idea-react';

const carousel = createRef<Carousel>();

carousel.current?.store.play();
carousel.current?.store.pause();
carousel.current?.store.next(true);
carousel.current?.store.previous(true);
carousel.current?.store.setIndex(2, true);
MethodDescription
store.play()Start cycling through the carousel items.
store.pause()Stop cycling through items.
store.toggle()Toggle autoplay.
store.next(true)Move to the next slide and stop autoplay for user-initiated navigation.
store.previous(true)Move to the previous slide and stop autoplay for user-initiated navigation.
store.setIndex(index, true)Select a zero-based slide index and stop autoplay for user-initiated navigation.

The component disposes its model and scroll animation when unmounted; do not use Bootstrap’s getInstance, getOrCreateInstance, or dispose methods on it.

Events

onChange(index) receives the zero-based active slide index after navigation or scroll synchronization. It reports logical selection, not the end of the scroll or crossfade animation. Bootstrap’s slide.bs.carousel and slid.bs.carousel plugin events are not emitted by this wrapper.

<Carousel onChange={handleSlideChange}>
<CarouselSlide>First slide</CarouselSlide>
<CarouselSlide>Second slide</CarouselSlide>
</Carousel>
Documentation navigation
On this page
On this page