Carousel

An interactive slideshow component for cycling through elements.

Anatomy

<Carousel.Root>
  <Carousel.Control>
    <Carousel.PrevTrigger />
    <Carousel.NextTrigger />
  </Carousel.Control>
  <Carousel.ItemGroup>
    <Carousel.Item />
  </Carousel.ItemGroup>
  <Carousel.IndicatorGroup>
    <Carousel.Indicator />
  </Carousel.IndicatorGroup>
</Carousel.Root>

Examples

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:

Root Provider

An alternative way to control the carousel is to use the RootProvider component and the useCarousel hook. This way you can access the state and methods from outside the component.

Autoplay

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

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.

Thumbnail Indicators

Replace default indicator dots with image thumbnails. Render each thumbnail inside Carousel.Indicator to create a visual preview of each slide:

Vertical

Add the orientation="vertical" prop to Carousel.Root to switch the carousel to vertical scrolling. This can be helpful for displaying vertical galleries or content feeds.

Dynamic

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.

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.

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.

Spacing

Control the gap between slides using the spacing prop on Carousel.Root. Combine it with slidesPerPage to create layouts that show partial previews of adjacent slides.

Variable Sizes

To allow slides with different widths, set the autoSize prop on Carousel.Root. This lets each Carousel.Item define its own width, and the carousel will adjust automatically. You can also use the snapAlign prop on individual items to control where each one snaps into view.

API Reference

Props

Root

Renders a <div> element.

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.

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

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

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

Renders a <button> element.

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.

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

Control

Renders a <div> element.

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.

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

IndicatorGroup

Renders a <div> element.

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.

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

Indicator

Renders a <button> element.

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.

Attribute	Description
`[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

Renders a <div> element.

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.

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

Item

Renders a <div> element.

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.

Attribute	Description
`[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

Renders a <button> element.

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.

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

PrevTrigger

Renders a <button> element.

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.

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

ProgressText

Renders a <span> element.

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

Renders a <div> element.

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

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
`getProgressText`	`() => string` Returns the progress text
`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.