Carousel
A slideshow component for cycling through a series of slides — with prev/next controls, indicator dots, optional captions, autoplay, crossfade, and full keyboard, swipe, and controlled-state support.
Import
import { Carousel, CarouselItem, CarouselCaption } from '@metatoy/bootstrap-styled';Basic
Wrap each slide in a CarouselItem. By default the carousel renders prev/next
controls and indicators, is uncontrolled, and wraps from the last slide back to the
first. Add a CarouselCaption to overlay text on a slide.
Autoplay & crossfade
ride="carousel" (or ride alone) starts autoplay; interval sets the dwell time in
milliseconds. Add fade to crossfade between slides instead of sliding, and
pause="hover" (the default) to pause cycling while the pointer is over the carousel.
Controlled
Drive the active slide yourself with activeIndex + onSelect. Set interval={null}
to disable autoplay. This is how you sync a carousel to external thumbnails or buttons.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| activeIndex | number | — | Controlled active slide index. |
| defaultActiveIndex | number | — | Uncontrolled initial index. |
| onSelect | (index: number, direction: 'next' | 'prev') => void | — | — |
| onSlide | (event: CarouselSlideEvent) => void | — | Fired when a slide transition BEGINS (Bootstrap `slide.bs.carousel`). Distinct from `onSlid`, which fires once the transition settles. |
| onSlid | (event: CarouselSlideEvent) => void | — | Fired when a slide transition SETTLES (Bootstrap `slid.bs.carousel`). |
| ride | boolean | 'carousel' | — | Autoplay. `'carousel'` (or true) cycles automatically. |
| interval | number | null | — | Autoplay dwell time in ms. Default 5000. Set 0/null to disable. |
| keyboard | boolean | — | Left/Right arrow navigation when focused. Default true. |
| pause | 'hover' | false | — | `'hover'` pauses autoplay while hovered. Default `'hover'`. |
| wrap | boolean | — | Wrap from last→first (and first→last). Default true. |
| touch | boolean | — | Touch/swipe (pointer) gestures advance the carousel. Default true. |
| fade | boolean | — | Crossfade instead of slide (`.carousel-fade`). |
| indicators | boolean | — | Render the indicator dots. Default true. |
| controls | boolean | — | Render the prev/next controls. Default true. |
| dark | boolean | — | Dark control/indicator/caption theming (`.carousel-dark`). |
| children● | React.ReactNode | — | — |
CarouselItem accepts an optional per-slide interval (ms) plus all native <div>
attributes; CarouselCaption is a styled <div>. The onSlide / onSlid callbacks
fire when a transition begins / settles with a { from, to, direction } payload.
Theming
Carousel reads Bootstrap’s carousel tokens, including
--bs-carousel-control-icon-filter, --bs-carousel-indicator-active-bg, and
--bs-carousel-caption-color. Setting dark applies the .carousel-dark treatment
(dark controls, indicators, and captions) for use over light slides.
Accessibility
The carousel root is a labelled region; controls are real <button>s with descriptive
labels and the indicators expose the current slide. Left/Right arrow keys navigate when
the carousel is focused (keyboard, default on). Autoplay pauses on hover and on focus.
For content that conveys meaning, prefer non-autoplaying carousels (or a visible
pause control) so users who need more time aren’t rushed.