Carousel

A carousel is a set of items, often images, that users can navigate through.

Features

Accessible navigation
Keyboard support
Loop mode
Multiple slides
Headless styling

Installation

npm install @ariaui/carousel

Examples

Default

A basic carousel with previous and next controls and a stack of numbered slides.

Preview

No preview output yet.

live.tsxReady

Multiple slides

Use slidesPerView with calculated slide widths to keep several slides visible in one viewport.

Preview

No preview output yet.

live.tsxReady

Infinite loop multiple slides

Combine loop and slidesPerView to keep the three-up carousel wrapping continuously.

Preview

No preview output yet.

live.tsxReady

Vertical

Set orientation="vertical" for a stacked carousel with up and down navigation.

Preview

No preview output yet.

live.tsxReady

Infinite loop vertical

Combine loop with orientation="vertical" to keep the stacked carousel wrapping continuously.

Preview

No preview output yet.

live.tsxReady

Infinite loop

Set loop on Carousel.Root to keep previous and next navigation wrapping through cloned boundary slides.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as Carousel from "@ariaui/carousel";

export default function Example() {
  return (
    <Carousel.Root>
      <Carousel.Viewport>
        <Carousel.Container>
          <Carousel.Slide />
        </Carousel.Container>
      </Carousel.Viewport>
      <Carousel.PreviousButton />
      <Carousel.NextButton />
    </Carousel.Root>
  );
}

API Reference

Root

The outermost container. Provides `aria-roledescription="carousel"` and owns selection state.

Prop	Type	Default
aria-label*	string	—
defaultIndex	number	0
index	number	—
onIndexChange	(index: number) => void	—
loop	boolean	false
orientation	"horizontal" \| "vertical"	"horizontal"
slidesPerView	number	—

Attribute	Values
role	"region"
aria-roledescription	"carousel"
data-axis	"x" \| "y"
data-orientation	"horizontal" \| "vertical"

Viewport

Clipping region for the carousel track.

Attribute	Values
aria-live	"polite"
aria-atomic	"false"

Container

Track element that positions slides along the selected axis.

Attribute	Values
data-axis	"x" \| "y"
data-orientation	"horizontal" \| "vertical"

Slide

Individual carousel item. Announces position (e.g., "1 of 5").

Attribute	Values
role	"group"
aria-roledescription	"slide"
aria-label	"N of M"
data-active	"true" \| undefined
data-clone	"true" \| undefined

PreviousButton

Navigates to the previous slide.

NextButton

Navigates to the next slide.

Keyboard interactions

Shortcut	Action
`Tab`	Move focus to the next focusable carousel control or slide content.
`Shift`+`Tab`	Move focus to the previous focusable carousel control or slide content.
`Enter`	Activate the focused PreviousButton or NextButton to move one slide.
`Space`	Activate the focused PreviousButton or NextButton to move one slide.

Accessibility

Role — Root uses aria-roledescription="carousel".
Naming — always provide aria-label or aria-labelledby for accessible name.
Keyboard — Tab moves focus between carousel controls. Enter and Space activate the focused previous or next button.
Announcements — slide position announced (e.g., "1 of 5").