---
title: Carousel
description: A scroll-snapping slideshow with keyboard, button, and optional drag navigation.
---

<PackageInfo name="carousel" />

**bun**

```bash
bun add @data-slot/carousel
```

**npm**

```bash
npm install @data-slot/carousel
```

**pnpm**

```bash
pnpm add @data-slot/carousel
```

## Anatomy

The content element is a native scroll container and every direct `carousel-item` child is a slide. Style the content with `scroll-snap-type` and size each slide to fill it; the component reads the resulting layout rather than imposing one. The previous and next controls are optional.

```html
<div data-slot="carousel" data-default-index="0">
  <div data-slot="carousel-content">
    <div data-slot="carousel-item">Slide 1</div>
    <div data-slot="carousel-item">Slide 2</div>
    <div data-slot="carousel-item">Slide 3</div>
  </div>
  <button data-slot="carousel-previous">Previous</button>
  <button data-slot="carousel-next">Next</button>
</div>
```

The active slide is the one the scroll position rests on. Navigation scrolls smoothly, or instantly when the visitor prefers reduced motion, and the index follows once scrolling settles. Inactive slides are `inert` and `aria-hidden`, so the layout should show one slide at a time.

## Examples

### Navigate with buttons and keys

Arrow keys move between slides while focus is inside the carousel, and `Home` and `End` jump to the first and last slide. `data-loop` lets the controls wrap around. The dots below the slides are demo markup: each one dispatches `carousel:set` with its index, and they follow `carousel:change` to highlight the active slide.

<Example name="carousel" />

### Drag to navigate

Add `data-drag` to let people drag or swipe the slides. Native scroll snapping pauses while a drag is in progress and the carousel settles on the nearest slide when the pointer lifts. Presses on links, buttons, and form controls inside a slide never start a drag.

<Example name="carousel" variant="extra" />

## API reference

### `create(scope?)`

Auto-discover and bind all carousel roots in a scope (`document` by default).

```ts
import { create } from "@data-slot/carousel";

const controllers = create(); // CarouselController[]
```

### `createCarousel(root, options?)`

Create a controller for a specific root element.

```ts
import { createCarousel } from "@data-slot/carousel";

const carousel = createCarousel(element, {
  defaultIndex: 1,
  orientation: "horizontal",
  drag: true,
  loop: false,
  onIndexChange: (index) => console.log(index),
});
```

### Data Attributes

JS options take precedence over data attributes.

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `data-default-index` | number | `0` | Initial active index |
| `data-orientation` | `horizontal \| vertical` | `horizontal` | Carousel orientation |
| `data-drag` | boolean | `false` | Enable pointer drag/swipe navigation |
| `data-loop` | boolean | `false` | Enable soft-wrap loop navigation |

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultIndex` | `number` | `0` | Initial active slide index |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Axis used for keyboard navigation and scrolling |
| `drag` | `boolean` | `false` | Enable pointer drag/swipe navigation on the scroll container |
| `loop` | `boolean` | `false` | Enable soft-wrap for `prev`/`next`/keyboard/API navigation |
| `onIndexChange` | `(index: number) => void` | `undefined` | Called when active slide changes |

### Controller

| Method / Property | Description |
|-------------------|-------------|
| `prev()` | Navigate to previous slide |
| `next()` | Navigate to next slide |
| `goTo(index)` | Navigate to specific slide |
| `index` | Current active index |
| `count` | Total number of slides |
| `canScrollPrev` | Whether previous navigation is available |
| `canScrollNext` | Whether next navigation is available |
| `destroy()` | Cleanup listeners and observers |

### Navigation Animation

Carousel navigation uses native smooth scrolling by default for:

- `prev()` / `next()` / `goTo()`
- keyboard navigation (`Arrow*`, `Home`, `End`)
- inbound `carousel:set` events
- optional `carousel-previous` / `carousel-next` button clicks

When the user prefers reduced motion (`prefers-reduced-motion: reduce`), navigation falls back to instant scroll behavior.

When `drag` is enabled, the carousel also supports pointer drag/swipe gestures and snaps to the nearest slide on release.

### Events

#### Outbound (on root)

| Event | Detail | Description |
|-------|--------|-------------|
| `carousel:change` | `{ index: number }` | Fires when active index changes |

#### Inbound (on root)

| Event | Detail | Description |
|-------|--------|-------------|
| `carousel:set` | `{ index?: number, action?: "next" \| "prev" }` | Programmatically navigate carousel |

```js
root.addEventListener("carousel:change", (event) => {
  console.log(event.detail.index);
});

root.dispatchEvent(
  new CustomEvent("carousel:set", { detail: { action: "next" } }),
);

root.dispatchEvent(
  new CustomEvent("carousel:set", { detail: { index: 2 } }),
);
```

### Required Slots

- `carousel` (root)
- `carousel-content` (scroll container)
- `carousel-item` (direct slide children)

### Optional Slots

- `carousel-previous`
- `carousel-next`

### Styling

The component is unstyled and relies on CSS hooks:

```css
[data-slot="carousel"] { position: relative; }

[data-slot="carousel-content"] {
  display: flex;
  overflow: auto;
  scroll-snap-type: x mandatory;
}

[data-slot="carousel"][data-dragging="true"] {
  cursor: grabbing;
}

[data-slot="carousel-item"] {
  flex: 0 0 100%;
  scroll-snap-align: start;
}

[data-slot="carousel-item"][data-state="active"] {
  opacity: 1;
}

[data-slot="carousel-item"][data-state="inactive"] {
  opacity: 0.75;
}
```

For vertical carousels, switch `scroll-snap-type` to `y mandatory` and use column layout.

### Accessibility

The carousel shows one slide at a time. Inactive slides are marked `aria-hidden` and `inert`, which removes them and their content from the accessibility tree and the tab order until they become active. Size slides to fill the viewport, as in the styling example above; a layout that shows several slides at once would hide visible neighbours from assistive technology.

The controller automatically sets:

- root: `role="region"`, `aria-roledescription="carousel"`
- item: `role="group"`, `aria-roledescription="slide"`, `aria-label="n of total"`
- item state: `data-state`, `aria-hidden`, `inert`
- root drag state: `data-dragging="true"` during an active pointer drag
- nav controls: `disabled` / `aria-disabled` synced to scrollability