Skip to main content

Carousel

Horizontal content slideshow using CSS scroll-snap with JS-enhanced navigation, autoplay, and indicator controls. The baseline carousel is a pure CSS scroll-snap strip that works without JavaScript - users swipe, scroll, or Tab through slides. Progressive enhancement layers prev/next buttons, indicator dots, autoplay with a visible pause control, and active-state tracking on top. Each slide is a generic slot that accepts any content: images, cards, testimonials, rich text, or mixed media.

Usage​

When to use

  • To present a set of equally-weighted items that do not all fit on screen (testimonials, partner logos, related cards)
  • To expose a gallery where users can step or swipe through content
  • To show a curated sequence where each slide holds a different content type

When not to use

  • For the most important content on a page - put it in the main layout instead
  • For long lists of items - use a grid or a list
  • For primary navigation - use navbar or a link list

Do

  • Provide a clear aria-label describing what the carousel contains
  • Keep slide count small and predictable
  • Pair autoplay with a visible, keyboard-reachable pause control

Don't

  • Don't autoplay by default - autoplay is opt-in per instance
  • Don't hide essential content behind a carousel
  • Don't autoplay while prefers-reduced-motion is set

API​

Props​

PropTypeDefaultDescription
slidesarray-Array of HTML strings. Each entry becomes a slide.
labelstringCarouselAccessible name for the carousel region.
is_loopboolean-When true, wraps around when prev/next passes the first/last slide.
has_controlsbooleantrueWhen true, shows prev/next buttons injected by JS.
has_indicatorsbooleantrueWhen true, shows indicator-dot navigation injected by JS.
use_autoplayboolean-Opts in to autoplay. JS pauses on focus/hover and respects prefers-reduced-motion.
autoplay_delaynumber5000Milliseconds between autoplay advances.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.fluidLayout-Full-width, no max-width.
.containedLayoutYesConstrained to a max-width.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.

Attributes​

AttributeSet byRequiredDescription
data-carouselConsumerYesMarks an element as a carousel root. Required for the JS to enhance the element.
data-carousel-no-controlsConsumer-Suppresses the injected prev/next button pair.
data-carousel-no-indicatorsConsumer-Suppresses the injected indicator-dot nav.
data-carousel-autoplayConsumer-Numeric delay (ms) between auto-advances. Presence enables autoplay.
data-carousel-loopConsumer-When present, prev/next wraps around at the first/last slide.
data-carousel-prevConsumer-Marks the injected previous-slide control button.
data-carousel-nextConsumer-Marks the injected next-slide control button.
data-carousel-pauseConsumer-Marks the injected autoplay pause/resume control button.

Events​

EventDirectionDescription
carousel-initializedEmitsFired once after the JS has set up controls, indicators, and active-state tracking.
carousel-destroyedEmitsFired after the JS has torn down its listeners for a carousel that is being removed.
carousel-slide-startedEmitsFired when a slide transition begins.
carousel-slide-changedEmitsFired each time the active slide index changes while a scroll is in progress.
carousel-slide-endedEmitsFired when the scroll-snap settles on a new slide.
carousel-autoplay-startedEmitsFired when autoplay starts (or resumes after a user pause).
carousel-autoplay-pausedEmitsFired when autoplay is paused (user, hover, focus, or reduced-motion).

Examples​

Single image​

Single-image slides with optional caption.

Cards​

Card component used as slide content.

Testimonials​

Quote/testimonial slide layout.

Mixed content​

Mixed content types in a single carousel (image, card, testimonial, rich text).

Multi slide​

Multi-slide view controlled via --carousel-slide-width (e.g. three-at-a-time).

Sizes​

Chrome scale via the .sm, .md, and .lg values. Each tier sets the caption font size and padding, the prev/next control diameter, and the indicator dot. The dot's button keeps its target size across all three, so only the dot itself shrinks.

Autoplay​

Autoplay with a visible pause control and reduced-motion support.

Accessibility​

  • WCAG 2.2 AA
  • Container identifies itself as a carousel region to assistive tech
  • Each slide is announced with its position (N of M)
  • Prev/next buttons expose descriptive labels
  • Indicator buttons expose a descriptive label and the active one is announced
  • Autoplay pauses on focus or hover and always exposes a visible pause control
  • The pause control carries the pause the user asked for, which hover and focus never lift; they stop the timer only while the pointer or focus stays on the carousel
  • Without looping, prev and next are disabled at the first and last slide, so a control that cannot act reads as unavailable to pointer and assistive-technology users
  • prefers-reduced-motion disables autoplay, and zeroes --option-animations so slide transitions jump instead of gliding. Setting that option to 0 directly has the same effect on the transitions
  • Keyboard: Tab reaches controls; arrow keys navigate when the slides container has focus
  • Tab-to-focus navigation between slides works without JS only when slides (or their descendants) are focusable - either because they contain focusable content (links, buttons, form controls) or because the slide container has an explicit tabindex="0".

Progressive enhancement​

  • No JS: CSS scroll-snap provides horizontal scrolling with snap points. Native touch/swipe works via browser scrolling. Scrollbar is hidden but scrolling remains functional. All slides are reachable via swipe, scroll, Tab, or direct link.
  • With JS: adds prev/next buttons, indicator dots, autoplay, keyboard arrow navigation, and active-state tracking via IntersectionObserver
  • How to enable: include the carousel script; the enhancement attaches to any .carousel container on the page
  • scrollspy - shared IntersectionObserver pattern for active-state tracking
  • card - common carousel slide content
  • image - single-image slides