Skip to content

Carousel

A finite set of related slides on a scroll-snap track, with Previous and Next and slide markers.

<section class="cap-carousel" id="car-loop" data-cap="carousel" aria-roledescription="carousel" aria-label="Featured posts">
  <div class="cap-carousel-viewport">
    <div class="cap-carousel-controls">
      <button type="button" data-cap-dir="prev" aria-label="Previous slide"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m15 6-6 6 6 6" /></svg></button>
      <button type="button" data-cap-dir="next" aria-label="Next slide"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6" /></svg></button>
    </div>
    <div class="cap-carousel-track" tabindex="0" role="group" aria-label="Slides">
      <div role="group" aria-roledescription="slide" aria-label="1 of 5">
        <article class="cap-card"><h3>Field notes</h3><p>What the spring survey found.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="2 of 5">
        <article class="cap-card"><h3>Spring update</h3><p>Three changes to the schedule.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="3 of 5">
        <article class="cap-card"><h3>Annual report</h3><p>Twelve sites and four new members.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="4 of 5">
        <article class="cap-card"><h3>Release notes</h3><p>Every change, grouped by area.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="5 of 5">
        <article class="cap-card"><h3>Getting started</h3><p>Set up a site and publish.</p></article>
      </div>
    </div>
  </div>
  <p class="cap-carousel-status cap-sr-only" role="status" aria-live="polite"></p>
  <nav class="cap-carousel-markers" aria-label="Choose a slide: Featured posts">
    <button type="button" aria-label="Go to slide 1" aria-current="true"></button>
    <button type="button" aria-label="Go to slide 2" aria-current="false"></button>
    <button type="button" aria-label="Go to slide 3" aria-current="false"></button>
    <button type="button" aria-label="Go to slide 4" aria-current="false"></button>
    <button type="button" aria-label="Go to slide 5" aria-current="false"></button>
  </nav>
</section>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/carousel.css";
import { enhance } from "capsomer/behavior/carousel";

enhance();

Usage

<section class="cap-carousel" data-cap="carousel" aria-roledescription="carousel" aria-label="Testimonials">
  <div class="cap-carousel-viewport">
    <div class="cap-carousel-controls">
      <button type="button" data-cap-dir="prev" aria-label="Previous slide">…</button>
      <button type="button" data-cap-dir="next" aria-label="Next slide">…</button>
    </div>
    <div class="cap-carousel-track" tabindex="0" role="group" aria-label="Slides">
      <div role="group" aria-roledescription="slide" aria-label="1 of 3">…</div>
      …
    </div>
  </div>
  <p class="cap-carousel-status cap-sr-only" role="status" aria-live="polite"></p>
  <nav class="cap-carousel-markers" aria-label="Choose a slide: Testimonials">
    <button type="button" aria-label="Go to slide 1" aria-current="true"></button>
    …
  </nav>
</section>
import { Carousel } from "capsomer/react/carousel";

<Carousel label="Testimonials" perView={2} status="Testimonials {n} of {total}">
  {quotes.map((q) => <Quote key={q.id} {...q} />)}
</Carousel>

Examples

Finite (two slides)

<section class="cap-carousel" id="car-finite" data-cap="carousel" aria-roledescription="carousel" aria-label="Two quotes">
  <div class="cap-carousel-viewport">
    <div class="cap-carousel-controls">
      <button type="button" data-cap-dir="prev" aria-label="Previous slide"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m15 6-6 6 6 6" /></svg></button>
      <button type="button" data-cap-dir="next" aria-label="Next slide"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6" /></svg></button>
    </div>
    <div class="cap-carousel-track" tabindex="0" role="group" aria-label="Slides">
      <div role="group" aria-roledescription="slide" aria-label="1 of 2">
        <article class="cap-card"><h3>Field notes</h3><p>What the spring survey found.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="2 of 2">
        <article class="cap-card"><h3>Spring update</h3><p>Three changes to the schedule.</p></article>
      </div>
    </div>
  </div>
  <p class="cap-carousel-status cap-sr-only" role="status" aria-live="polite"></p>
  <nav class="cap-carousel-markers" aria-label="Choose a slide: Two quotes">
    <button type="button" aria-label="Go to slide 1" aria-current="true"></button>
    <button type="button" aria-label="Go to slide 2" aria-current="false"></button>
  </nav>
</section>

Two per view, with a peek

<section class="cap-carousel" id="car-two" data-cap="carousel" aria-roledescription="carousel" aria-label="Updates" data-per-view="2" data-peek data-cap-status="Updates {n} of {total}">
  <div class="cap-carousel-viewport">
    <div class="cap-carousel-controls">
      <button type="button" data-cap-dir="prev" aria-label="Previous slide"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m15 6-6 6 6 6" /></svg></button>
      <button type="button" data-cap-dir="next" aria-label="Next slide"><svg class="cap-icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6" /></svg></button>
    </div>
    <div class="cap-carousel-track" tabindex="0" role="group" aria-label="Slides">
      <div role="group" aria-roledescription="slide" aria-label="1 of 4">
        <article class="cap-card"><h3>Field notes</h3><p>What the spring survey found.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="2 of 4">
        <article class="cap-card"><h3>Spring update</h3><p>Three changes to the schedule.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="3 of 4">
        <article class="cap-card"><h3>Annual report</h3><p>Twelve sites and four new members.</p></article>
      </div>
      <div role="group" aria-roledescription="slide" aria-label="4 of 4">
        <article class="cap-card"><h3>Release notes</h3><p>Every change, grouped by area.</p></article>
      </div>
    </div>
  </div>
  <p class="cap-carousel-status cap-sr-only" role="status" aria-live="polite"></p>
  <nav class="cap-carousel-markers" aria-label="Choose a slide: Updates">
    <button type="button" aria-label="Go to slide 1" aria-current="true"></button>
    <button type="button" aria-label="Go to slide 2" aria-current="false"></button>
    <button type="button" aria-label="Go to slide 3" aria-current="false"></button>
    <button type="button" aria-label="Go to slide 4" aria-current="false"></button>
  </nav>
</section>

API reference

PropTypeRequiredDoes
labelstringYes
slideLabel(n: number, total: number) => string
markerLabel(n: number) => string
statusstring
prevLabelstring
nextLabelstring
trackLabelstring
perView2 | 3
peekboolean
loopboolean
childrenReactNodeYes

Functions

FunctionSignatureDoes
partsOf(root: HTMLElement): CarouselParts | null
statusText(template: string | undefined, n: number, total: number): stringThe status message for a slide; a carousel may name its own with data-cap-status="Testimonial {n} of {total}".
canLoop(count: number): booleanWhether the track can loop: three slides at least, and the parking rule's sibling-count().
attach(parts: CarouselParts): () => void
enhance(root?: ParentNode): () => void

CSS variables

VariableDefault
--carousel-block20rem
--carousel-gapvar(--space-6)
--carousel-overhangvar(--space-3)
--carousel-per-view1
--currentset by the page

Parts and data attributes

ClassIs
.cap-carouselthe root
.cap-carousel-controlsa part
.cap-carousel-markersa part
.cap-carousel-tracka part
.cap-carousel-viewporta part
AttributeValues
data-axisblock
data-cap-loopspresent or absent
data-peekpresent or absent
data-per-view2 3
StateRead from
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-current="true"]an attribute

Accessibility

KeyDoes
TabPrevious, Next, the track, then the markers
Left and Right arrows on the trackScroll it (the browser's own)
Enter or Space on Previous, Next or a markerMoves there