Carousel

An interactive slideshow component for cycling through elements.

Features

Native CSS Scroll Snap integration for smooth, performant animations
Flexible orientation support (horizontal and vertical layouts)
Customizable slide alignment (start, center, or end positions)
Multi-slide display capabilities for complex layouts
Automatic playback with configurable looping behavior
Adjustable slide spacing and gap controls

Anatomy

To set up the carousel correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the Carousel component in your project. Let's take a look at the most basic example:

Example not found

Example not found

Example not found

Example not found

Controlled

To create a controlled Carousel component, you can manage the state of the carousel using the page prop and update it when the onPageChange event handler is called:

Example not found

Example not found

Example not found

Example not found

Root Provider

Use the useCarousel hook to create the carousel store and pass it to the Carousel.RootProvider component. This allows you to have maximum control over the carousel programmatically.

Example not found

Example not found

Example not found

Example not found

If you're using the Carousel.RootProvider component, you don't need to use the Carousel.Root component.

Autoplay

Pass the autoplay and loop props to Carousel.Root to make the carousel play automatically.

Note: Adding loop ensures the carousel keeps going after the last slide.

Example not found

Example not found

Example not found

Example not found

Pause on Hover

This feature isn't built-in, but you can use the play() and pause() methods from Carousel.Context to implement pause on hover.

Add the autoplay and loop props to Carousel.Root, then attach onPointerOver and onPointerLeave handlers to Carousel.ItemGroup that call api.pause() and api.play() respectively.

Example not found

Example not found

Example not found

Example not found

Custom Indicators

Replace default indicator dots with custom content by wrapping Carousel.IndicatorGroup in Carousel.Context. Use api.page to determine the active indicator and render image thumbnails for each slide:

Example not found

Example not found

Example not found

Example not found

Vertical Orientation

Set the orientation="vertical" prop on Carousel.Root to change the carousel from horizontal to vertical scrolling. This is useful for vertical galleries or content feeds.

Example not found

Example not found

Example not found

Example not found

Dynamic Slides

Manage slides dynamically by storing them in state and syncing the carousel page. Pass the page prop and onPageChange handler to Carousel.Root, and update slideCount when slides are added or removed. This demonstrates bidirectional state synchronization between your component state and the carousel.

Example not found

Example not found

Example not found

Example not found

Scroll to Slide

Use Carousel.Context to access the carousel API and call api.scrollToIndex(index) to programmatically navigate to a specific slide. This is useful for creating custom navigation or jump-to-slide functionality.

Example not found

Example not found

Example not found

Example not found

Slides Per Page

Display multiple slides simultaneously by setting the slidesPerPage prop on Carousel.Root. Use api.pageSnapPoints from Carousel.Context to render the correct number of indicators based on pages rather than individual slides. Add the spacing prop to control the gap between slides.

Example not found

Example not found

Example not found

Example not found

API Reference

Props

Root

Prop	Default	Type
`slideCount`		`number` The total number of slides. Useful for SSR to render the initial ating the snap points.
`allowMouseDrag`	`false`	`boolean` Whether to allow scrolling via dragging with mouse
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`autoplay`	`false`	`boolean \| { delay: number }` Whether to scroll automatically. The default delay is 4000ms.
`defaultPage`	`0`	`number` The initial page to scroll to when rendered. Use when you don't need to control the page of the carousel.
`ids`		`Partial<{ root: string item: (index: number) => string itemGroup: string nextTrigger: string prevTrigger: string indicatorGroup: string indicator: (index: number) => string }>` The ids of the elements in the carousel. Useful for composition.
`inViewThreshold`	`0.6`	`number \| number[]` The threshold for determining if an item is in view.
`loop`	`false`	`boolean` Whether the carousel should loop around.
`onAutoplayStatusChange`		`(details: AutoplayStatusDetails) => void` Function called when the autoplay status changes.
`onDragStatusChange`		`(details: DragStatusDetails) => void` Function called when the drag status changes.
`onPageChange`		`(details: PageChangeDetails) => void` Function called when the page changes.
`orientation`	`'horizontal'`	`'horizontal' \| 'vertical'` The orientation of the element.
`padding`		`string` Defines the extra space added around the scrollable area, enabling nearby items to remain partially in view.
`page`		`number` The controlled page of the carousel.
`slidesPerMove`	`'auto'`	`number \| 'auto'` The number of slides to scroll at a time. When set to `auto`, the number of slides to scroll is determined by the `slidesPerPage` property.
`slidesPerPage`	`1`	`number` The number of slides to show at a time.
`snapType`	`'mandatory'`	`'proximity' \| 'mandatory'` The snap type of the item.
`spacing`	`'0px'`	`string` The amount of space between items.
`translations`		`IntlTranslations` The localized messages to use.

CSS Variable	Description
`--slides-per-page`	The number of slides visible per page
`--slide-spacing`	The spacing between slides
`--slide-item-size`	The calculated size of each slide item

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	root
`[data-orientation]`	The orientation of the carousel

AutoplayIndicator

Prop	Default	Type
`paused`		`string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>` The content to render when autoplay is paused.
`playing`		`string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>` The content to render when autoplay is playing.

AutoplayTrigger

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	autoplay-trigger
`[data-orientation]`	The orientation of the autoplaytrigger
`[data-pressed]`	Present when pressed

Control

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	control
`[data-orientation]`	The orientation of the control

IndicatorGroup

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	indicator-group
`[data-orientation]`	The orientation of the indicatorgroup

Indicator

Prop	Default	Type
`index`		`number` The index of the indicator.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`readOnly`	`false`	`boolean` Whether the indicator is read only.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	indicator
`[data-orientation]`	The orientation of the indicator
`[data-index]`	The index of the item
`[data-readonly]`	Present when read-only
`[data-current]`	Present when current

ItemGroup

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	item-group
`[data-orientation]`	The orientation of the item
`[data-dragging]`	Present when in the dragging state

Item

Prop	Default	Type
`index`		`number` The index of the item.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`snapAlign`	`'start'`	`'center' \| 'start' \| 'end'` The snap alignment of the item.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	item
`[data-index]`	The index of the item
`[data-inview]`	Present when in viewport
`[data-orientation]`	The orientation of the item

NextTrigger

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	next-trigger
`[data-orientation]`	The orientation of the nexttrigger

PrevTrigger

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	carousel
`[data-part]`	prev-trigger
`[data-orientation]`	The orientation of the prevtrigger

ProgressText

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

RootProvider

Prop	Default	Type
`value`		`UseCarouselReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

These are the properties available when using Carousel.Context, useCarouselContext hook or useCarousel hook.

API

Property	Type
`page`	`number` The current index of the carousel
`pageSnapPoints`	`number[]` The current snap points of the carousel
`isPlaying`	`boolean` Whether the carousel is auto playing
`isDragging`	`boolean` Whether the carousel is being dragged. This only works when `draggable` is true.
`canScrollNext`	`boolean` Whether the carousel is can scroll to the next view
`canScrollPrev`	`boolean` Whether the carousel is can scroll to the previous view
`scrollToIndex`	`(index: number, instant?: boolean) => void` Function to scroll to a specific item index
`scrollTo`	`(page: number, instant?: boolean) => void` Function to scroll to a specific page
`scrollNext`	`(instant?: boolean) => void` Function to scroll to the next page
`scrollPrev`	`(instant?: boolean) => void` Function to scroll to the previous page
`getProgress`	`() => number` Returns the current scroll progress as a percentage
`play`	`VoidFunction` Function to start/resume autoplay
`pause`	`VoidFunction` Function to pause autoplay
`isInView`	`(index: number) => boolean` Whether the item is in view
`refresh`	`VoidFunction` Function to re-compute the snap points and clamp the page

Accessibility

Complies with the Carousel WAI-ARIA design pattern.