Carousel Autoplay

ProNew

A looping slide show with a Pause button, a progress bar, dots and arrows that holds still for the pointer, focus, a hidden tab or an off-screen carousel.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it when content should rotate on its own, such as promotions or highlights, and you need the controls that WCAG 2.2.2 asks for.

Do not use it for content people need to read carefully or act on: moving content competes with the task. Prefer manual paging.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/carousel-autoplay

Usage

Props

Part	Prop	Type	Default	Description
`AutoplayCarousel`	`items`	`CarouselItem[]`	`required`	`{ id, label, content }`.
`AutoplayCarousel`	`label`	`string`	`required`	Accessible name of the carousel.
`CarouselAutoplay`	`interval`	`number`	`5000`	Time on each slide, in ms.
`CarouselAutoplay`	`pauseOnHover`	`boolean`	`true`	Hold while the pointer is over the carousel.
`CarouselAutoplay`	`pauseOnFocus`	`boolean`	`true`	Hold while focus is inside the carousel.
`CarouselAutoplay`	`stopOnInteraction`	`boolean`	`false`	Pause for good after a drag.
`CarouselAutoplay`	`startPaused`	`boolean`	`false`	Start paused. Always true with reduced motion.
`AutoplayCarousel`	`onIndexChange`	`(index) => void`	`-`	Called with the snap index when the selection changes.
`AutoplayCarousel`	`setApi`	`(api) => void`	`-`	Receives the Embla API, for controls placed outside the carousel.

Keyboard

Tab to the Pause / Start button; Enter or Space toggles it.
Left / Right: previous or next slide (also pauses by focus).
Home / End: first or last slide.

Accessibility

There is always a Pause / Start slide show button with aria-pressed (WCAG 2.2.2).
The live region is off while it rotates and polite when paused, so a screen reader is not interrupted (WAI-ARIA Authoring Practices).
Rotation holds while focus or the pointer is inside, the tab is hidden or the carousel is off screen.
With prefers-reduced-motion it starts paused; a person can still start it.

Testing

The component ships with a Testing Library test (carousel-autoplay.test.tsx). Embla needs layout to count snaps, and jsdom has none, so the repo's mockCarouselLayout helper gives the viewport and slides real sizes in tests.

Guide and examples

When to use it

Use it when content should rotate on its own, such as promotions or highlights, and you need the controls that WCAG 2.2.2 asks for.

Do not use it for content people need to read carefully or act on: moving content competes with the task. Prefer manual paging.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/carousel-autoplay

Usage

Props

Part	Prop	Type	Default	Description
`AutoplayCarousel`	`items`	`CarouselItem[]`	`required`	`{ id, label, content }`.
`AutoplayCarousel`	`label`	`string`	`required`	Accessible name of the carousel.
`CarouselAutoplay`	`interval`	`number`	`5000`	Time on each slide, in ms.
`CarouselAutoplay`	`pauseOnHover`	`boolean`	`true`	Hold while the pointer is over the carousel.
`CarouselAutoplay`	`pauseOnFocus`	`boolean`	`true`	Hold while focus is inside the carousel.
`CarouselAutoplay`	`stopOnInteraction`	`boolean`	`false`	Pause for good after a drag.
`CarouselAutoplay`	`startPaused`	`boolean`	`false`	Start paused. Always true with reduced motion.
`AutoplayCarousel`	`onIndexChange`	`(index) => void`	`-`	Called with the snap index when the selection changes.
`AutoplayCarousel`	`setApi`	`(api) => void`	`-`	Receives the Embla API, for controls placed outside the carousel.

Keyboard

Tab to the Pause / Start button; Enter or Space toggles it.
Left / Right: previous or next slide (also pauses by focus).
Home / End: first or last slide.

Accessibility

There is always a Pause / Start slide show button with aria-pressed (WCAG 2.2.2).
The live region is off while it rotates and polite when paused, so a screen reader is not interrupted (WAI-ARIA Authoring Practices).
Rotation holds while focus or the pointer is inside, the tab is hidden or the carousel is off screen.
With prefers-reduced-motion it starts paused; a person can still start it.