Carousel

Alpha

An accessible content carousel with autoplay, looping, pagination, and full keyboard navigation following the ARIA carousel pattern.

Import

import { Carousel } from "@compa11y/react";

Usage

Example.tsx
import { Carousel, Button } from "@compa11y/react";

function ImageCarousel() {
  const slides = [
    { title: "Accessible by Default", desc: "Every component ships with ARIA, keyboard, and screen reader support." },
    { title: "React + Web Components", desc: "Use the same primitives in React or any framework via CDN." },
    { title: "Zero Configuration", desc: "Install, import, render. Accessibility is built in." },
  ];

  return (
    <Carousel ariaLabel="Feature highlights" loop autoplay>
      <Carousel.Content>
        {slides.map((slide, i) => (
          <Carousel.Item key={i}>
            <h3>{slide.title}</h3>
            <p>{slide.desc}</p>
          </Carousel.Item>
        ))}
      </Carousel.Content>
      <Carousel.Controls>
        <Carousel.Prev>
          <Button variant="ghost" size="sm">Previous</Button>
        </Carousel.Prev>
        <Carousel.Pagination />
        <Carousel.Next>
          <Button variant="ghost" size="sm">Next</Button>
        </Carousel.Next>
      </Carousel.Controls>
      <Carousel.Pause />
      <Carousel.Status />
    </Carousel>
  );
}

Features

  • role='region' with aria-roledescription='carousel'
  • aria-roledescription='slide' on each item
  • Autoplay with pause button (respects prefers-reduced-motion)
  • Loop and slides-per-view options
  • Horizontal and vertical orientations
  • Pagination dots and prev/next controls
  • Live region announces current slide
  • Compound component API

Props

Carousel component props
PropTypeDefaultDescription
ariaLabelstring-Accessible label for the carousel region
valuenumber-Controlled current slide index
defaultValuenumber0Default slide index
onValueChange(index: number) => void-Called when slide changes
loopbooleanfalseEnable infinite looping
autoplaybooleanfalseEnable automatic slide advancement
autoplayIntervalnumber5000Autoplay interval in ms
orientation'horizontal' | 'vertical''horizontal'Carousel orientation

Sub-components

Carousel.Content

Carousel.Content props
PropTypeDefaultDescription
children*ReactNode-Carousel slides

Carousel.Item

Carousel.Item props
PropTypeDefaultDescription
children*ReactNode-Slide content

Carousel.Prev

Carousel.Prev props
PropTypeDefaultDescription
childrenReactNode-Previous button content

Carousel.Next

Carousel.Next props
PropTypeDefaultDescription
childrenReactNode-Next button content

Carousel.Pause

Carousel.Pause props
PropTypeDefaultDescription
childrenReactNode-Pause/resume toggle

Carousel.Pagination

Carousel.Status

Keyboard Interactions

Accessibility
All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.
Keyboard shortcuts for Carousel
KeyAction
ArrowLeft / ArrowUpGo to previous slide
ArrowRight / ArrowDownGo to next slide
Enter / SpacePause/resume autoplay (on pause button)
TabNavigate between carousel controls