Carousel

When not to use a carousel

Worth reading before the API, because it is the part most carousel documentation leaves out.

More first-party design systems refuse to ship a carousel than ship one. Base UI, MUI, Adobe Spectrum, Polaris, PatternFly, Atlassian and Primer have none. USWDS filed the request to prohibit them as "our first anti-feature request". GOV.UK removed its homepage carousel in 2012 after testing found users did not scroll past it. Carbon for IBM.com ships one but forbids autoplay and looping outright, citing WCAG 2.2.2.

The recurring finding is that content below the first slide is rarely seen. So:

• Do not put anything important on slide two. If every item matters, use a grid or a list — both are scannable at a glance and need no interaction.
• Prefer a carousel for browsing, not for deciding. Galleries, related products, editorial rails: good. A comparison someone must reason about: bad.
• Keep it short. Five frames or fewer is the usability recommendation. Past about eight, dots stop being countable — use CarouselCounter.
• Give each carousel a real name describing what it holds, and do not stack two under one heading.

Examples

Default

A full-width slide carousel with looping, arrow nav and dot indicators.

Card

The card variant scales and fades adjacent slides for a centre-focused look.

Fade

Crossfades between slides — for testimonials and hero rotations, where a side-scroll would feel jarring.

Multi-peek

Fixed-width items leave the next slide cut off at the edge. That partial slide is the strongest discoverability cue a carousel has on a phone — stronger than dots.

Free-scroll rail

variant="scroll" is the momentum rail: no snapping, no arrows, no dots. The shape used by story rows and category rails.

Autoplay and the rotation control

Counter

Past about eight slides, dots stop working. A fraction scales to any length.

Dot variants and the ceiling

Clickable dots carry real target floors — 24px pitch on desktop, 44px on phones — so the row spreads with them. interactive={false} drops the targets and the floors with them: the tight indicator pitch holds on every width, and swipe, arrows and keyboard navigate. That is the form the showcase examples on this page use.

Nav placement

All three layouts below use the same position="inline" — flanking the viewport, below it beside the dots, or parked in a section header. Only the surrounding markup differs, so there is no prop for this.

On a coloured surface

Vertical

RTL

Accessibility

Loading

Installation

npx shadcn@latest add https://tessinaui.com/r/carousel.json

Usage

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselPrevious,
  CarouselNext,
  CarouselDots,
} from "@tessinaui/ui/carousel";

<Carousel size="full" loop aria-label="Featured products">
  <CarouselContent>
    <CarouselItem>Slide 1</CarouselItem>
    <CarouselItem>Slide 2</CarouselItem>
    <CarouselItem>Slide 3</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
  <CarouselDots />
</Carousel>

aria-label is required in practice: a role="region" with no name is not exposed as a landmark at all. Describe what the carousel contains, and do not include the word "carousel" — aria-roledescription already says that, and repeating it makes screen readers announce "Featured products, carousel, carousel". The component dev-warns when the name is missing.

API

Carousel

CarouselItem

CarouselPrevious / CarouselNext

CarouselDots

CarouselCounter

Rendered aria-hidden: the carousel's live region already announces the same position on change, and announcing it twice is worse than once.

CarouselPlayPause

Renders null when the carousel has no autoplay, so it is safe to leave in a composition whose autoplay is conditional. Render it before CarouselContent so it is the first tab stop inside the carousel, which is what APG asks for.

CarouselProgress

A thin rail that fills over the autoplay interval, driven by the plugin's own timer. With rotation off it shows position in the set instead. Decorative.

CarouselScrollbar

A scroll-position line. The thumb's width is the fraction of the rail you can see and its position is how far along you are — a map of the track rather than a clock, so it stays meaningful with no autoplay and with more slides than you could ever dot. This is the affordance a long free-scrolling row wants; IKEA, Skillshare and Shop all pair one with theirs. Decorative.

<Carousel variant="scroll" size="auto" aria-label="Categories">
  <CarouselContent>…</CarouselContent>
  <CarouselScrollbar className="mt-4" />
</Carousel>

CarouselSkeleton

useCarouselApi

const { setApi, current, count } = useCarouselApi();

<Carousel setApi={setApi} aria-label="Gallery" />
<p>{current + 1} / {count}</p>

Trackpad and wheel

Wheel support is on for every variant: a two-finger trackpad swipe along the carousel's axis moves it. Embla is transform-driven and has no native scroller to receive that gesture, so the official wheel plugin bridges it.

The variants differ only in how much of the wheel they take. Snapping carousels listen on their own axis alone — a vertical scroll over a horizontal carousel still scrolls the page, which is what keeps this from being the most complained-about carousel behaviour on the web. variant="scroll" also remaps the cross axis onto the rail, so a plain mouse wheel — which has no X axis — can move it. wheel={false} opts any carousel out.

Autoplay behaviour

The contract follows the ARIA APG, which is stricter than the engine's defaults:

• Hover pauses and resumes. Moving the pointer away restarts rotation.
• Keyboard focus stops it for good. Tabbing in is a signal that someone is reading; rotation does not resume unless they ask for it.
• A pointer press stops it for good, same reasoning.
• Reduced motion starts it paused. Under prefers-reduced-motion: reduce nothing rotates until the play button is pressed.
• The live region goes silent while rotating, so an auto-advancing carousel never narrates itself over the rest of the page.

Autoplay alone does not satisfy WCAG 2.2.2 — a visible, keyboard-operable control does. Render CarouselPlayPause whenever you set autoplay.

Accessibility

• The root is a region with aria-roledescription="carousel" and a name you supply. Missing names are dev-warned.
• Each slide is a group with aria-roledescription="slide" and a name — "3 of 10" by default, per APG's fallback for slides with no unique name.
• Slides that are not in view are inert, so hidden content stays out of both the tab order and the accessibility tree. A partially visible peeking slide stays interactive; only fully off-screen ones are taken out.
• A polite live region announces the position after it settles, and is silent while autoplay runs.
• Dots are buttons in a named group, marked with aria-current. They are not a tablist: that pattern demands roving focus and aria-selected, and half of it is worse than none.
• Arrows are named and disable at the bounds.

Keyboard

The viewport itself is focusable, which is what gives the arrow keys somewhere to land — a carousel whose slides hold no focusable content would otherwise be unreachable by keyboard entirely.

This is ours, not the engine's. Embla ships no keyboard navigation; earlier versions of this page claimed it did. Set keyboard={false} to drop both the bindings and the tab stop.

Assistive technology

aria-roledescription is not universally supported: NVDA announces it, JAWS announces it twice, VoiceOver is inconsistent and TalkBack ignores it. Treat it as an enhancement, never as the thing that tells a user this is a carousel.

Migration

The rounded change is visual and affects existing carousels. Everything else either fixes a defect or adds API.

Notes for agents

• Every part carries a stable data-slot: carousel, carousel-viewport, carousel-track, carousel-item, carousel-previous, carousel-next, carousel-dots, carousel-dot, carousel-counter, carousel-play-pause, carousel-progress, carousel-status, carousel-skeleton.
• The active slide carries data-active; the root carries data-variant, data-orientation and data-tone.
• Do not assert on slide visibility via CSS. Read inert or data-active.
• For unbounded or generated content, keep loop={false}, use CarouselCounter rather than dots, and offer a "see all" link — an infinite carousel has no honest indicator and no end.