Carousel

Overview

<Carousel /> is an accessible, keyboard- and touch-friendly carousel built on CSS scroll-snap with a thin JS coordination layer for index tracking, controls, and optional autoplay. Zero new runtime dependencies — no Embla, no Swiper.

It ships two equivalent APIs that resolve to the same DOM:

• Prop-driven (90% case) — drop <Carousel.Slide> children in and the Viewport, Track, Controls, and Indicators are auto-wrapped for you.
• Compound (power users) — render the full <Carousel.Viewport> / <Carousel.Track> / <Carousel.Slide> shape yourself for precise layout control.

Anatomy

Examples

Props

Imperative ref

const ref = useRef<CarouselRef>(null);

ref.current?.scrollTo(2);
ref.current?.next();
ref.current?.prev();
ref.current?.getIndex();
ref.current?.getSlideCount();
ref.current?.isAutoplaying();
ref.current?.pauseAutoplay();
ref.current?.playAutoplay();

const ref = useRef<CarouselRef>(null);

ref.current?.scrollTo(2);
ref.current?.next();
ref.current?.prev();
ref.current?.getIndex();
ref.current?.getSlideCount();
ref.current?.isAutoplaying();
ref.current?.pauseAutoplay();
ref.current?.playAutoplay();

Keyboard

Focus the <Carousel.Viewport> (Tab into it) — then:

Prev / Next buttons and Indicators are in the standard Tab order; the Viewport itself is also focusable for power keyboard users who want to skip the controls.

Accessibility

• Root is a <section role="region"> with a required aria-label (default 'Carousel') and aria-roledescription="carousel".
• Each slide is a role="group" with aria-roledescription="slide" and an auto-generated aria-label="Slide N of M".
• Indicators render as role="tab" inside a role="tablist", with aria-selected + aria-current.
• Autoplay is off by default (WCAG 2.2.2). When enabled, the <Carousel.AutoplayControl> is rendered automatically and gives the user a visible pause/play toggle. Autoplay also pauses when the user hovers / focuses the carousel, when prefers-reduced-motion: reduce is set, when the tab is backgrounded, and when the user has explicitly paused via the button.
• A live region (<Carousel.LiveRegion>) is rendered when liveRegionPoliteness="polite" or whenever the user pauses autoplay; it announces "Slide N of M" on manual navigation only, never during autoplay (to avoid AT spam).
• Loop wrap-around uses programmatic scrollTo; no DOM clones means screen readers always see the real slide list once.

RTL

Direction is read from useDirection(). ArrowLeft / ArrowRight semantics flip automatically for horizontal carousels; vertical and PageUp / PageDown remain direction-neutral. The Prev / Next chevron glyphs mirror automatically.

i18n

Strings are English defaults with prop overrides:

• ariaLabel (region)
• ariaRoleDescription (region)
• <Carousel.Slide ariaLabel> (per-slide override)
• <Carousel.PrevButton ariaLabel> (default 'Previous slide')
• <Carousel.NextButton ariaLabel> (default 'Next slide')
• <Carousel.AutoplayControl ariaLabelPlay / ariaLabelPause> (defaults 'Play carousel' / 'Pause carousel')
• <Carousel.Indicators renderLabel> callback (index, total) => string

Once <I18nProvider> lands, these will default to provider-supplied strings; the prop overrides will remain higher precedence.

Theming

The full recipe matrix (root, viewport, track, slide, controls, controlButton, indicators, indicator) is exposed through theme styleOverrides.Carousel so brands can restyle every slot without forking the source.

Do / Don't

Do

• Use a single <Carousel> per region; if you have many lanes on a page, give each a unique ariaLabel so AT users can tell them apart.
• Provide an accessible name for image-only slides via <Carousel.Slide ariaLabel> (image galleries lean on this).
• Use loop for hero banners, leave it off for content lanes (otherwise the keyboard order loops infinitely).
• Use slidesPerView with a responsive object ({ base: 1, md: 3 }) — let small screens show one slide.

Don't

• Don't enable autoplay without a visible pause/play control (the component does this for you; the AutoplayControl renders automatically).
• Don't put critical actions inside autoplaying slides — users won't have time to click.
• Don't disable pauseOnReducedMotion; users have set this preference explicitly.
• Don't nest a <Carousel> inside another <Carousel> — the keyboard semantics conflict.