Carousel
AlphaAn 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
| Prop | Type | Default | Description |
|---|---|---|---|
ariaLabel | string | - | Accessible label for the carousel region |
value | number | - | Controlled current slide index |
defaultValue | number | 0 | Default slide index |
onValueChange | (index: number) => void | - | Called when slide changes |
loop | boolean | false | Enable infinite looping |
autoplay | boolean | false | Enable automatic slide advancement |
autoplayInterval | number | 5000 | Autoplay interval in ms |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Carousel orientation |
Sub-components
Carousel.Content
| Prop | Type | Default | Description |
|---|---|---|---|
children* | ReactNode | - | Carousel slides |
Carousel.Item
| Prop | Type | Default | Description |
|---|---|---|---|
children* | ReactNode | - | Slide content |
Carousel.Prev
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Previous button content |
Carousel.Next
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Next button content |
Carousel.Pause
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Pause/resume toggle |
Carousel.Pagination
Carousel.Status
Keyboard Interactions
Accessibility
All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.
| Key | Action |
|---|---|
| ArrowLeft / ArrowUp | Go to previous slide |
| ArrowRight / ArrowDown | Go to next slide |
| Enter / Space | Pause/resume autoplay (on pause button) |
| Tab | Navigate between carousel controls |