---
id: carousel
title: Carousel
description: An interactive slideshow component for cycling through elements.
---

<ComponentPreview id="Carousel" />

## Anatomy

<Anatomy id="carousel" />

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

<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

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.

<Example id="root-provider" />

### Autoplay

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

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

<Example id="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:

<Example id="thumbnail-indicator" />

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

<Example id="vertical" />

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

<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" />

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

<Example id="spacing" />

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

<Example id="variable-size" />

## API Reference

### Props

<ComponentTypes id="carousel" />

### Context

<ContextType id="carousel" />

## Accessibility

Complies with the [Carousel WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
