# Carousel

URL: https://ark-ui.com/docs/components/carousel
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/carousel.mdx

An interactive slideshow component for cycling through elements.

---

<ComponentPreview id="Carousel" />

## 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.

<Anatomy id="carousel" />

## Examples

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

<Example id="basic" />

### 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 id="controlled" />

### 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 id="root-provider" />

> 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 id="autoplay" />

### 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 id="pause-on-hover" />

### 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 id="custom-indicator" />

### 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 id="vertical" />

### 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 id="dynamic-slides" />

### 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 id="scroll-to" />

### 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 id="slides-per-page" />

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `slideCount` | `number` | Yes | The total number of slides.
Useful for SSR to render the initial ating the snap points. |
| `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. |
| `defaultPage` | `number` | No | 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
}>` | No | The ids of the elements in the carousel. Useful for composition. |
| `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. |
| `loop` | `boolean` | No | Whether the carousel should loop around. |
| `onAutoplayStatusChange` | `(details: AutoplayStatusDetails) => void` | No | Function called when the autoplay status changes. |
| `onDragStatusChange` | `(details: DragStatusDetails) => void` | No | Function called when the drag status changes. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Function called when the page changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `padding` | `string` | No | Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view. |
| `page` | `number` | No | The controlled page of the carousel. |
| `slidesPerMove` | `number | 'auto'` | No | 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` | `number` | No | The number of slides to show at a time. |
| `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. |
| `spacing` | `string` | No | The amount of space between items. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

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


**AutoplayIndicator Props:**

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


**AutoplayTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**AutoplayTrigger Data Attributes:**

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


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

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


**IndicatorGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**IndicatorGroup Data Attributes:**

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


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the indicator. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `readOnly` | `boolean` | No | Whether the indicator is read only. |


**Indicator Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the item. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `snapAlign` | `'center' | 'start' | 'end'` | No | The snap alignment of the item. |


**Item Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

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


**ProgressText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCarouselReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `slideCount` | `number` | Yes | The total number of slides.
Useful for SSR to render the initial ating the snap points. |
| `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. |
| `defaultPage` | `number` | No | 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
}>` | No | The ids of the elements in the carousel. Useful for composition. |
| `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. |
| `loop` | `boolean` | No | Whether the carousel should loop around. |
| `onAutoplayStatusChange` | `(details: AutoplayStatusDetails) => void` | No | Function called when the autoplay status changes. |
| `onDragStatusChange` | `(details: DragStatusDetails) => void` | No | Function called when the drag status changes. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Function called when the page changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `padding` | `string` | No | Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view. |
| `page` | `number` | No | The controlled page of the carousel. |
| `slidesPerMove` | `number | 'auto'` | No | 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` | `number` | No | The number of slides to show at a time. |
| `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. |
| `spacing` | `string` | No | The amount of space between items. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

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


**AutoplayTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**AutoplayTrigger Data Attributes:**

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


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

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


**IndicatorGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**IndicatorGroup Data Attributes:**

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


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the indicator. |
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `readOnly` | `boolean` | No | Whether the indicator is read only. |


**Indicator Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the item. |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `snapAlign` | `'start' | 'end' | 'center'` | No | The snap alignment of the item. |


**Item Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCarouselReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `slideCount` | `number` | Yes | The total number of slides.
Useful for SSR to render the initial ating the snap points. |
| `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. |
| `defaultPage` | `number` | No | The initial page to scroll to when rendered.
Use when you don't need to control the page of the carousel. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  item(index: number): string
  itemGroup: string
  nextTrigger: string
  prevTrigger: string
  indicatorGroup: string
  indicator(index: number): string
}>` | No | The ids of the elements in the carousel. Useful for composition. |
| `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. |
| `loop` | `boolean` | No | Whether the carousel should loop around. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `padding` | `string` | No | Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view. |
| `page` | `number` | No | The controlled page of the carousel. |
| `slidesPerMove` | `number | 'auto'` | No | 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` | `number` | No | The number of slides to show at a time. |
| `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. |
| `spacing` | `string` | No | The amount of space between items. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

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


**AutoplayTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**AutoplayTrigger Data Attributes:**

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


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

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


**IndicatorGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**IndicatorGroup Data Attributes:**

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


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the indicator. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `readOnly` | `boolean` | No | Whether the indicator is read only. |


**Indicator Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemGroup Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the item. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `snapAlign` | `'start' | 'end' | 'center'` | No | The snap alignment of the item. |


**Item Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `CarouselApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `slideCount` | `number` | Yes | The total number of slides.
Useful for SSR to render the initial ating the snap points. |
| `allowMouseDrag` | `boolean` | No | Whether to allow scrolling via dragging with mouse |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoplay` | `boolean | { delay: number }` | No | Whether to scroll automatically. The default delay is 4000ms. |
| `defaultPage` | `number` | No | The initial page to scroll to when rendered.
Use when you don't need to control the page of the carousel. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  item: (index: number) => string
  itemGroup: string
  nextTrigger: string
  prevTrigger: string
  indicatorGroup: string
  indicator: (index: number) => string
}>` | No | The ids of the elements in the carousel. Useful for composition. |
| `inViewThreshold` | `number | number[]` | No | The threshold for determining if an item is in view. |
| `loop` | `boolean` | No | Whether the carousel should loop around. |
| `onAutoplayStatusChange` | `(details: AutoplayStatusDetails) => void` | No | Function called when the autoplay status changes. |
| `onDragStatusChange` | `(details: DragStatusDetails) => void` | No | Function called when the drag status changes. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Function called when the page changes. |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the element. |
| `padding` | `string` | No | Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view. |
| `page` | `number` | No | The controlled page of the carousel. |
| `ref` | `Element` | No |  |
| `slidesPerMove` | `number | 'auto'` | No | 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` | `number` | No | The number of slides to show at a time. |
| `snapType` | `'proximity' | 'mandatory'` | No | The snap type of the item. |
| `spacing` | `string` | No | The amount of space between items. |
| `translations` | `IntlTranslations` | No | The localized messages to use. |


**Root Data Attributes:**

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


**AutoplayTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**AutoplayTrigger Data Attributes:**

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


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseCarouselContext]>` | Yes |  |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Control Data Attributes:**

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


**IndicatorGroup Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**IndicatorGroup Data Attributes:**

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


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the indicator. |
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `readOnly` | `boolean` | No | Whether the indicator is read only. |
| `ref` | `Element` | No |  |


**Indicator Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**ItemGroup Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes | The index of the item. |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |
| `snapAlign` | `'start' | 'end' | 'center'` | No | The snap alignment of the item. |


**Item Data Attributes:**

| 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 Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**NextTrigger Data Attributes:**

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


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**PrevTrigger Data Attributes:**

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


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseCarouselReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


### Context

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

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `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](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).