Carousel
A composable image and content carousel with autoplay, keyboard navigation, touch swipe, and speed control.
Installation
npx vayu-ui-cli@latest add carouselUsage
Featured Gallery
WCAG Compliant Interactive Media
Slide 1 of 5
Jump to item:
Product Showcase
Responsive — 1 on mobile, 2 on sm, 3 on lg
Slide 1 of 8
Anatomy
<Carousel>
{' '}
// Root — provides context and autoplay state
<Carousel.PlayPause /> // Toggle play/pause for autoplay
<Carousel.SpeedControl /> // Adjust playback speed (0.5x–2x)
<Carousel.Viewport>
{' '}
// Touch-swipe and keyboard-navigable wrapper
<Carousel.Slide index={0}> // Individual slide content</Carousel.Slide>
</Carousel.Viewport>
<Carousel.Previous /> // Navigate to the previous slide
<Carousel.Next /> // Navigate to the next slide
<Carousel.Bullets /> // Dot indicators for slide navigation
<Carousel.Gallery /> // Horizontal thumbnail strip
</Carousel>Accessibility
- Keyboard navigation — ArrowLeft / ArrowRight to move slides, Home / End to jump to first / last slide
- ARIA attributes —
role="region"on root,aria-roledescription="carousel",role="group"andaria-roledescription="slide"on each slide,aria-hiddenon inactive slides,aria-currenton active bullet and gallery thumbnail - Focus behavior — Viewport is focusable (
tabIndex={0}) for keyboard users; navigation buttons receive visible focus rings onfocus-visible - Reduced motion — Autoplay is disabled when the user's system
prefers-reduced-motionsetting is set toreduce
Screen reader behavior
The viewport includes an aria-live="polite" region that announces "Slide X of Y" whenever the active slide changes. Inactive slides are marked aria-hidden="true" so they are skipped by screen readers. Bullet indicators use role="tablist" and role="tab" with aria-selected on the active bullet. Gallery thumbnails use aria-current="true" on the active item. The play/pause button uses aria-pressed to communicate its toggled state.
Component Folder Structure
Carousel/
├── Carousel.tsx # Root component and context provider
├── CarouselViewport.tsx # Touch/keyboard navigation wrapper
├── CarouselSlide.tsx # Individual slide wrapper
├── CarouselPrevious.tsx # Previous button
├── CarouselNext.tsx # Next button
├── CarouselBullets.tsx # Dot indicators
├── CarouselPlayPause.tsx # Play/pause toggle
├── CarouselSpeedControl.tsx # Speed selector dropdown
├── CarouselGallery.tsx # Thumbnail gallery strip
├── hooks.ts # useCarouselContext, usePrefersReducedMotion
├── types.ts # Shared TypeScript types
├── index.ts # Public exports
└── README.md # Component readmeProps
Carousel
| Prop | Type | Default | Description |
|---|---|---|---|
totalItems | number | — | Total number of slides. |
autoPlay | boolean | false | Enable autoplay on mount. |
interval | number | 3000 | Autoplay interval in milliseconds. |
loop | boolean | true | Wrap around from last to first slide. |
defaultSpeed | 0.5 | 1 | 1.5 | 2 | 1 | Default playback speed multiplier. |
defaultIndex | number | 0 | Initial slide index. |
Carousel.Viewport
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | — | Carousel.Slide elements. |
Carousel.Slide
| Prop | Type | Default | Description |
|---|---|---|---|
index | number | — | Zero-based slide index. |
children | React.ReactNode | — | Slide content. |
Carousel.Previous
| Prop | Type | Default | Description |
|---|---|---|---|
showLabel | boolean | false | Show "Previous" text next to icon. |
Carousel.Next
| Prop | Type | Default | Description |
|---|---|---|---|
showLabel | boolean | false | Show "Next" text next to icon. |
Carousel.Bullets
| Prop | Type | Default | Description |
|---|---|---|---|
| — | Extends HTMLAttributes<HTMLDivElement> | — | No additional required props. |
Carousel.PlayPause
| Prop | Type | Default | Description |
|---|---|---|---|
showLabel | boolean | false | Show "Play"/"Pause" text next to icon. |
Carousel.SpeedControl
| Prop | Type | Default | Description |
|---|---|---|---|
showLabel | boolean | true | Show "Speed:" label next to dropdown. |
Carousel.Gallery
| Prop | Type | Default | Description |
|---|---|---|---|
items | GalleryItem[] | — | Array of { src: string, alt: string } thumbnails. |