Skip to main content
ShadcnUI
Navigation

Carousel

A complete ordered list in a named native horizontal scroll region, with real item links.

When to use it. Use it to browse a finite collection while keeping every card and its ordinary destinations available.

Native baseline One named region contains an ordered list. Stable item keys generate unique fragment targets. An item link is not remote pagination, an active slide or synchronized selection. There are no tab/menu/listbox roles, fake previous/next buttons, clones, autoplay or generated scroll controls. Exact fallback Without snap, ordinary scrolling remains. Without CSS, every item and real index link forms a complete ordered document. Without JavaScript, all component operations still work. Reduce motion, motion=:none or your system preference removes smooth scrolling, not navigation.

How it works

  • <.carousel> One named region contains an ordered list. Stable item keys generate unique fragment targets. An item link is not remote pagination, an active slide or synchronized selection. There are no tab/menu/listbox roles, fake previous/next buttons, clones, autoplay or generated scroll controls.
  • package CSS Package CSS applies scoped shadcn-style tokens, layout, focus, and state presentation without changing the native contract.
  • gallery only Theme switching, source copying, search, fixtures, and inspection controls on this page belong to the gallery only; :carousel does not ship them.
  • application boundary ShadcnUI does not add application state, authorization, persistence, transport events, or a JavaScript behavior layer to this component.

Examples use package semantic tokens in explicit light and dark scopes.

Accessibility and browser support

Tab reaches the named region and native child controls according to browser keyboard preferences (some skip links). Arrow keys, touch, wheel and item links use native scrolling. Index links focus their item; no roving focus or live announcements are supplied. Focus outlines and logical padding remain visible in RTL, narrow and zoomed layouts.

Carousel support and fallback
Feature Locked-engine evidence When missing
Native baseline Reviewed in the locked Chromium, Firefox, and WebKit evidence matrix. Without snap, ordinary scrolling remains. Without CSS, every item and real index link forms a complete ordered document. Without JavaScript, all component operations still work. Reduce motion, motion=:none or your system preference removes smooth scrolling, not navigation.
Exact fallback The locked-engine matrix retains the documented native or static outcome. Without snap, ordinary scrolling remains. Without CSS, every item and real index link forms a complete ordered document. Without JavaScript, all component operations still work. Reduce motion, motion=:none or your system preference removes smooth scrolling, not navigation.

Application ownership and API

You own content, image rights/privacy, alternative text, intrinsic sizes, destinations, form actions and scroll restoration after replacement. This demo only edits local form controls; reset really restores their defaults.

Attributes and item slots. Required: unique id and exactly one of accessible_label / labelledby (existing heading IDs). Optional escaped description. Repeated item slots require nonblank key, label and trusted HEEx body, and accept class/rest. snap=:none|:proximity|:mandatory (proximity default), alignment=:start|:center (start default), motion=:system|:none (system default). Root class/rest preserve unrelated caller styling and framework globals; required native identities, roles, focus and names are protected. No raw HTML or active-slide attribute exists.

Public API Package source

Provenance

Catalogue identity media.carousel, adapted from unscripted/ui commit bd8f403030c8d1f46804da6eda733fde7e908e63 under its MIT notice.

The documentation presentation is adapted locally; ShadcnUI's Phoenix API and native semantic contract remain authoritative.

Retain native scrolling but use a named focusable region, ordered keyed items and real fragment links. Default to proximity snap with logical layout, visible scrollbars and focus, bounded cards and motion suppression. Omit reviewed generated markers/buttons, hidden scrollbars, containment and all slide state/runtime.