# Carousel

URL: https://ark-ui.com/docs/components/carousel
LLM: https://ark-ui.com/llms.txt/components/carousel

An interactive slideshow component for cycling through elements.

---



## Anatomy



```tsx
<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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const Basic = () => {
  return (
    <Carousel.Root className={styles.Root} slideCount={images.length}>
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.ItemGroup className={styles.ItemGroup}>
          {images.map((image, index) => (
            <Carousel.Item className={styles.Item} key={index} index={index}>
              <img src={image.src} alt={image.alt} width="500" height="300" />
            </Carousel.Item>
          ))}
        </Carousel.ItemGroup>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
        {images.map((_, index) => (
          <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
        ))}
      </Carousel.IndicatorGroup>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import { useState } from 'react'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const Controlled = () => {
  const [page, setPage] = useState(0)

  return (
    <Carousel.Root className={styles.Root} slideCount={images.length} page={page} onPageChange={(e) => setPage(e.page)}>
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.ItemGroup className={styles.ItemGroup}>
          {images.map((image, index) => (
            <Carousel.Item className={styles.Item} key={index} index={index}>
              <img src={image.src} alt={image.alt} width="500" height="300" />
            </Carousel.Item>
          ))}
        </Carousel.ItemGroup>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
        {images.map((_, index) => (
          <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
        ))}
      </Carousel.IndicatorGroup>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel, useCarousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const RootProvider = () => {
  const carousel = useCarousel({ slideCount: images.length })

  return (
    <div className="vstack">
      <output>Page: {carousel.page}</output>
      <Carousel.RootProvider className={styles.Root} value={carousel}>
        <Carousel.Control className={styles.Control}>
          <Carousel.PrevTrigger className={styles.Trigger}>
            <ArrowLeftIcon />
          </Carousel.PrevTrigger>
          <Carousel.ItemGroup className={styles.ItemGroup}>
            {images.map((image, index) => (
              <Carousel.Item className={styles.Item} key={index} index={index}>
                <img src={image.src} alt={image.alt} width="500" height="300" />
              </Carousel.Item>
            ))}
          </Carousel.ItemGroup>
          <Carousel.NextTrigger className={styles.Trigger}>
            <ArrowRightIcon />
          </Carousel.NextTrigger>
        </Carousel.Control>
        <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
          {images.map((_, index) => (
            <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
          ))}
        </Carousel.IndicatorGroup>
      </Carousel.RootProvider>
    </div>
  )
}
```

### Autoplay

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ChevronLeftIcon, ChevronRightIcon, PauseIcon, PlayIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const Autoplay = () => {
  return (
    <Carousel.Root className={styles.Root} slideCount={images.length} autoplay loop>
      <Carousel.ItemGroup className={styles.ItemGroup}>
        {images.map((image, index) => (
          <Carousel.Item className={styles.Item} key={index} index={index}>
            <img src={image.src} alt={image.alt} width="500" height="300" />
          </Carousel.Item>
        ))}
      </Carousel.ItemGroup>
      <Carousel.Control className={styles.Control} data-justify="center">
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ChevronLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.AutoplayTrigger className={styles.AutoplayTrigger}>
          <Carousel.AutoplayIndicator fallback={<PlayIcon />}>
            <PauseIcon />
          </Carousel.AutoplayIndicator>
        </Carousel.AutoplayTrigger>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ChevronRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const PauseOnHover = () => {
  return (
    <Carousel.Root className={styles.Root} slideCount={images.length} autoplay loop>
      <Carousel.Control className={styles.Control}>
        <Carousel.Context>
          {({ isPlaying }) => (
            <span className={styles.StatusText}>Autoplay is: {isPlaying ? 'playing' : 'paused'}</span>
          )}
        </Carousel.Context>
      </Carousel.Control>
      <Carousel.Context>
        {(api) => (
          <Carousel.ItemGroup
            className={styles.ItemGroup}
            onPointerOver={() => api.pause()}
            onPointerLeave={() => api.play()}
          >
            {images.map((image, index) => (
              <Carousel.Item className={styles.Item} key={index} index={index}>
                <img src={image.src} alt={image.alt} width="500" height="300" />
              </Carousel.Item>
            ))}
          </Carousel.ItemGroup>
        )}
      </Carousel.Context>
      <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
        {images.map((_, index) => (
          <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
        ))}
      </Carousel.IndicatorGroup>
    </Carousel.Root>
  )
}
```

### Thumbnail Indicators

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const ThumbnailIndicator = () => {
  return (
    <Carousel.Root className={styles.Root} defaultPage={0} slideCount={images.length}>
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.ItemGroup className={styles.ItemGroup}>
          {images.map((image, index) => (
            <Carousel.Item className={styles.Item} key={index} index={index}>
              <img src={image.src} alt={image.alt} width="500" height="300" />
            </Carousel.Item>
          ))}
        </Carousel.ItemGroup>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
        {images.map((image, index) => (
          <Carousel.Indicator className={styles.ThumbnailIndicator} key={index} index={index}>
            <img src={image.src} alt={image.alt} width="500" height="300" />
          </Carousel.Indicator>
        ))}
      </Carousel.IndicatorGroup>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowDownIcon, ArrowUpIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const images = [
  { src: 'https://picsum.photos/seed/1/500/300', alt: 'Nature landscape' },
  { src: 'https://picsum.photos/seed/2/500/300', alt: 'City skyline' },
  { src: 'https://picsum.photos/seed/3/500/300', alt: 'Mountain view' },
  { src: 'https://picsum.photos/seed/4/500/300', alt: 'Ocean sunset' },
  { src: 'https://picsum.photos/seed/5/500/300', alt: 'Forest path' },
]

export const Vertical = () => {
  return (
    <Carousel.Root className={styles.Root} defaultPage={0} orientation="vertical" slideCount={images.length}>
      <Carousel.ItemGroup className={styles.ItemGroup}>
        {images.map((image, index) => (
          <Carousel.Item className={styles.Item} key={index} index={index}>
            <img src={image.src} alt={image.alt} width="500" height="300" />
          </Carousel.Item>
        ))}
      </Carousel.ItemGroup>
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowUpIcon />
        </Carousel.PrevTrigger>
        <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
          {images.map((_, index) => (
            <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
          ))}
        </Carousel.IndicatorGroup>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowDownIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon, PlusIcon } from 'lucide-react'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/carousel.module.css'

export const DynamicSlides = () => {
  const [slides, setSlides] = useState([0, 1, 2, 3, 4])
  const [page, setPage] = useState(0)

  const addSlide = () => {
    setSlides((prevSlides) => {
      const max = Math.max(...prevSlides)
      return [...prevSlides, max + 1]
    })
  }

  return (
    <div className="stack">
      <Carousel.Root
        className={styles.Root}
        slideCount={slides.length}
        page={page}
        onPageChange={(details) => setPage(details.page)}
      >
        <Carousel.ItemGroup className={styles.ItemGroup}>
          {slides.map((slide, index) => (
            <Carousel.Item className={styles.Item} key={index} index={index}>
              <div className={styles.Slide}>Slide {slide + 1}</div>
            </Carousel.Item>
          ))}
        </Carousel.ItemGroup>
        <Carousel.Control className={styles.Control}>
          <Carousel.PrevTrigger className={styles.Trigger}>
            <ArrowLeftIcon />
          </Carousel.PrevTrigger>
          <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
            {slides.map((_, index) => (
              <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
            ))}
          </Carousel.IndicatorGroup>
          <Carousel.NextTrigger className={styles.Trigger}>
            <ArrowRightIcon />
          </Carousel.NextTrigger>
        </Carousel.Control>
      </Carousel.Root>
      <button className={button.Root} onClick={addSlide}>
        <PlusIcon />
        Add Slide
      </button>
    </div>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import button from 'styles/button.module.css'
import styles from 'styles/carousel.module.css'

export const ScrollTo = () => {
  return (
    <Carousel.Root className={styles.Root} slideCount={5}>
      <Carousel.Context>
        {(api) => (
          <button className={button.Root} onClick={() => api.scrollToIndex(3)}>
            Go to slide 4
          </button>
        )}
      </Carousel.Context>
      <Carousel.ItemGroup className={styles.ItemGroup}>
        {Array.from({ length: 5 }, (_, index) => (
          <Carousel.Item className={styles.Item} key={index} index={index}>
            <div className={styles.Slide}>Slide {index + 1}</div>
          </Carousel.Item>
        ))}
      </Carousel.ItemGroup>
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
        {Array.from({ length: 5 }, (_, index) => (
          <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
        ))}
      </Carousel.IndicatorGroup>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

export const SlidesPerPage = () => {
  const slides = Array.from({ length: 6 })

  return (
    <Carousel.Root className={styles.Root} slideCount={slides.length} slidesPerPage={2} spacing="20px">
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.ItemGroup className={styles.ItemGroup}>
        {slides.map((_, index) => (
          <Carousel.Item className={styles.Item} key={index} index={index}>
            <div className={styles.Slide}>Slide {index + 1}</div>
          </Carousel.Item>
        ))}
      </Carousel.ItemGroup>
      <Carousel.Context>
        {(api) => (
          <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
            {api.pageSnapPoints.map((_, index) => (
              <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
            ))}
          </Carousel.IndicatorGroup>
        )}
      </Carousel.Context>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const slides = Array.from({ length: 6 })

export const Spacing = () => {
  return (
    <Carousel.Root className={styles.Root} slideCount={slides.length} slidesPerPage={1.5} spacing="48px">
      <span className={styles.StatusText}>spacing='48px'</span>
      <Carousel.ItemGroup className={styles.ItemGroup}>
        {slides.map((_, index) => (
          <Carousel.Item className={styles.Item} key={index} index={index}>
            <div className={styles.Slide}>{index + 1}</div>
          </Carousel.Item>
        ))}
      </Carousel.ItemGroup>
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.Context>
          {(api) => (
            <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
              {api.pageSnapPoints.map((_, index) => (
                <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
              ))}
            </Carousel.IndicatorGroup>
          )}
        </Carousel.Context>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
    </Carousel.Root>
  )
}
```

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

```tsx
import { Carousel } from '@ark-ui/react/carousel'
import { ArrowLeftIcon, ArrowRightIcon } from 'lucide-react'
import styles from 'styles/carousel.module.css'

const items = [
  { id: '1', width: '120px', label: 'Small' },
  { id: '2', width: '200px', label: 'Medium Size' },
  { id: '3', width: '80px', label: 'XS' },
  { id: '4', width: '250px', label: 'Large Content Here' },
  { id: '5', width: '150px', label: 'Regular' },
]

export const VariableSize = () => {
  return (
    <Carousel.Root className={styles.Root} slideCount={items.length} autoSize spacing="8px">
      <Carousel.Control className={styles.Control}>
        <Carousel.PrevTrigger className={styles.Trigger}>
          <ArrowLeftIcon />
        </Carousel.PrevTrigger>
        <Carousel.NextTrigger className={styles.Trigger}>
          <ArrowRightIcon />
        </Carousel.NextTrigger>
      </Carousel.Control>
      <Carousel.ItemGroup className={styles.ItemGroup}>
        {items.map((item, index) => (
          <Carousel.Item key={item.id} index={index} snapAlign="center">
            <div className={styles.Slide} style={{ width: item.width, height: '6rem' }}>
              {item.label}
            </div>
          </Carousel.Item>
        ))}
      </Carousel.ItemGroup>
      <Carousel.Context>
        {(api) => (
          <Carousel.IndicatorGroup className={styles.IndicatorGroup}>
            {api.pageSnapPoints.map((_, index) => (
              <Carousel.Indicator className={styles.Indicator} key={index} index={index} />
            ))}
          </Carousel.IndicatorGroup>
        )}
      </Carousel.Context>
    </Carousel.Root>
  )
}
```

## API Reference

### Props

### Root

#### Props

**`slideCount`**
Type: `number`
Required: true
Default Value: `undefined`
Description: The total number of slides.
Useful for SSR to render the initial ating the snap points.

**`allowMouseDrag`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to allow scrolling via dragging with mouse

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`autoplay`**
Type: `boolean | { delay: number }`
Required: false
Default Value: `false`
Description: Whether to scroll automatically. The default delay is 4000ms.

**`autoSize`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether to enable variable width slides.

**`defaultPage`**
Type: `number`
Required: false
Default Value: `0`
Description: The initial page to scroll to when rendered.
Use when you don't need to control the page of the carousel.

**`ids`**
Type: `Partial<{
  root: string
  item: (index: number) => string
  itemGroup: string
  nextTrigger: string
  prevTrigger: string
  indicatorGroup: string
  indicator: (index: number) => string
}>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the carousel. Useful for composition.

**`inViewThreshold`**
Type: `number | number[]`
Required: false
Default Value: `0.6`
Description: The threshold for determining if an item is in view.

**`loop`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether the carousel should loop around.

**`onAutoplayStatusChange`**
Type: `(details: AutoplayStatusDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called when the autoplay status changes.

**`onDragStatusChange`**
Type: `(details: DragStatusDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called when the drag status changes.

**`onPageChange`**
Type: `(details: PageChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Function called when the page changes.

**`orientation`**
Type: `'horizontal' | 'vertical'`
Required: false
Default Value: `"horizontal"`
Description: The orientation of the element.

**`padding`**
Type: `string`
Required: false
Default Value: `undefined`
Description: Defines the extra space added around the scrollable area,
enabling nearby items to remain partially in view.

**`page`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The controlled page of the carousel.

**`slidesPerMove`**
Type: `number | 'auto'`
Required: false
Default Value: `"auto"`
Description: 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`**
Type: `number`
Required: false
Default Value: `1`
Description: The number of slides to show at a time.

**`snapType`**
Type: `'proximity' | 'mandatory'`
Required: false
Default Value: `"mandatory"`
Description: The snap type of the item.

**`spacing`**
Type: `string`
Required: false
Default Value: `"0px"`
Description: The amount of space between items.

**`translations`**
Type: `IntlTranslations`
Required: false
Default Value: `undefined`
Description: The localized messages to use.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: root
**`data-orientation`**: The orientation of the carousel

### AutoplayIndicator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`fallback`**
Type: `string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...>`
Required: false
Default Value: `undefined`
Description: The fallback content to render when autoplay is paused.

### AutoplayTrigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: autoplay-trigger
**`data-orientation`**: The orientation of the autoplaytrigger
**`data-pressed`**: Present when pressed

### Control

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: control
**`data-orientation`**: The orientation of the control

### IndicatorGroup

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: indicator-group
**`data-orientation`**: The orientation of the indicatorgroup

### Indicator

#### Props

**`index`**
Type: `number`
Required: true
Default Value: `undefined`
Description: The index of the indicator.

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`readOnly`**
Type: `boolean`
Required: false
Default Value: `false`
Description: Whether the indicator is read only.

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: item-group
**`data-orientation`**: The orientation of the item
**`data-dragging`**: Present when in the dragging state

### Item

#### Props

**`index`**
Type: `number`
Required: true
Default Value: `undefined`
Description: The index of the item.

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`snapAlign`**
Type: `'center' | 'start' | 'end'`
Required: false
Default Value: `"start"`
Description: The snap alignment of the item.

#### Data Attributes

**`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

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: next-trigger
**`data-orientation`**: The orientation of the nexttrigger

### PrevTrigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-scope`**: carousel
**`data-part`**: prev-trigger
**`data-orientation`**: The orientation of the prevtrigger

### ProgressText

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### RootProvider

#### Props

**`value`**
Type: `UseCarouselReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

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