A composable image and content carousel with autoplay, keyboard navigation, touch swipe, and speed control.

Installation

npx vayu-ui init #one time only

npx vayu-ui add carousel

npx vayu-ui add -t carousel #with test case needs

Featured Gallery

WCAG Compliant Interactive Media

Jump to item:

<Carousel totalItems={items.length} autoPlay interval={3000}>
  <div className="flex justify-between items-center">
    <Carousel.PlayPause />
    <Carousel.SpeedControl />
  </div>

  <div className="relative">
    <Carousel.Viewport>
      {items.map((item, index) => (
        <Carousel.Slide key={index} index={index}>
          <img src={item.src} alt={item.alt} />
        </Carousel.Slide>
      ))}
    </Carousel.Viewport>

    <Carousel.Previous />
    <Carousel.Next />
  </div>

  <Carousel.Bullets />

  <Carousel.Gallery items={items} />
</Carousel>

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" and aria-roledescription="slide" on each slide, aria-hidden on inactive slides, aria-current on active bullet and gallery thumbnail
Focus behavior — Viewport is focusable (tabIndex={0}) for keyboard users; navigation buttons receive visible focus rings on focus-visible
Reduced motion — Autoplay is disabled when the user's system prefers-reduced-motion setting is set to reduce

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 readme

Props

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.

Carousel

Installation

Usage

Featured Gallery

Jump to item:

Anatomy

Accessibility

Component Folder Structure

Props

Carousel

Carousel.Viewport

Carousel.Slide

Carousel.Previous

Carousel.Next

Carousel.Bullets

Carousel.PlayPause

Carousel.SpeedControl

Carousel.Gallery

On this page