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-labeldescribing 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-motionis set
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
slides | array | - | Array of HTML strings. Each entry becomes a slide. |
label | string | Carousel | Accessible name for the carousel region. |
is_loop | boolean | - | When true, wraps around when prev/next passes the first/last slide. |
has_controls | boolean | true | When true, shows prev/next buttons injected by JS. |
has_indicators | boolean | true | When true, shows indicator-dot navigation injected by JS. |
use_autoplay | boolean | - | Opts in to autoplay. JS pauses on focus/hover and respects prefers-reduced-motion. |
autoplay_delay | number | 5000 | Milliseconds between autoplay advances. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.fluid | Layout | - | Full-width, no max-width. |
.contained | Layout | Yes | Constrained to a max-width. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-carousel | Consumer | Yes | Marks an element as a carousel root. Required for the JS to enhance the element. |
data-carousel-no-controls | Consumer | - | Suppresses the injected prev/next button pair. |
data-carousel-no-indicators | Consumer | - | Suppresses the injected indicator-dot nav. |
data-carousel-autoplay | Consumer | - | Numeric delay (ms) between auto-advances. Presence enables autoplay. |
data-carousel-loop | Consumer | - | When present, prev/next wraps around at the first/last slide. |
data-carousel-prev | Consumer | - | Marks the injected previous-slide control button. |
data-carousel-next | Consumer | - | Marks the injected next-slide control button. |
data-carousel-pause | Consumer | - | Marks the injected autoplay pause/resume control button. |
Events
| Event | Direction | Description |
|---|---|---|
carousel-initialized | Emits | Fired once after the JS has set up controls, indicators, and active-state tracking. |
carousel-destroyed | Emits | Fired after the JS has torn down its listeners for a carousel that is being removed. |
carousel-slide-started | Emits | Fired when a slide transition begins. |
carousel-slide-changed | Emits | Fired each time the active slide index changes while a scroll is in progress. |
carousel-slide-ended | Emits | Fired when the scroll-snap settles on a new slide. |
carousel-autoplay-started | Emits | Fired when autoplay starts (or resumes after a user pause). |
carousel-autoplay-paused | Emits | Fired 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-motiondisables autoplay, and zeroes--option-animationsso slide transitions jump instead of gliding. Setting that option to0directly 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
.carouselcontainer on the page