# Carousel

Slides you swipe, drag or step through, with momentum, snapping, loop and autoplay.

```ehtml Example
import {
  Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext,
} from "@elements/ui/carousel";

<Carousel label="Featured" opts={{ loop: true }}>
  <CarouselContent>
    <CarouselItem e:for={item of items}>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

<!-- index is two-way; autoplay adds the rotation control -->
<Carousel index={state.slide} autoplay={4000} dots>...</Carousel>
```

## Parts

| Part | What it is |
|---|---|
| `Carousel` | The root: a region with aria-roledescription carousel. Owns the engine, the index and the keyboard. |
| `CarouselContent` | The viewport (clips) and the track the engine moves. class goes on the track. |
| `CarouselItem` | One slide: a group with aria-roledescription slide, named "N of M" unless label is set. |
| `CarouselPrevious` | An icon button that scrolls back; disabled at the start unless looping. |
| `CarouselNext` | An icon button that scrolls forward; disabled at the end unless looping. |
| `.carousel-rotation` | The rotation control autoplay renders: the first tab stop, its label says what it will do. |
| `.carousel-dots` | The slide pickers dots renders: one button per snap, the current one aria-disabled. |

## Attributes

### Carousel

| Attribute | Type | Default | Description |
|---|---|---|---|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Scroll axis (engine axis x or y). |
| `opts` | `CarouselOpts` | `{}` | Engine options: align, loop, dragFree, slidesToScroll, containScroll, skipSnaps, duration, startIndex, watchDrag, breakpoints and the rest. |
| `plugins` | `CarouselPlugin[]` | `[]` | Plugins with init(api) and destroy(). This package ships Autoplay, AutoScroll, AutoHeight, ClassNames, Fade and WheelGestures. |
| `index` | `number` (two-way) | `0` | The selected snap. Bind it to read the current slide or set it to go to one. |
| `label` | `string` | `""` | The region's accessible name. Do not include the word carousel. |
| `dir` | `"ltr" \| "rtl" \| ""` | `""` | Reading direction; the engine's direction follows it. |
| `autoplay` | `number` | `0` | Milliseconds per slide; 0 is off. Adds the rotation control; hovering pauses, keyboard focus stops. |
| `dots` | `boolean` | `false` | Renders a picker button per snap under the slides. |
| `pickers` | `"group" \| "tabs"` | `"group"` | group: picker buttons, the current one aria-disabled. tabs: a tablist whose tabs control the slides as tabpanels (APG tabbed carousel). |
| `role` | `"region" \| "group"` | `"region"` | The container's role. Name a group with attrs aria-labelledby when a heading labels it. |
| `onSelect` | `(index: number) => void` | `() => {}` | The selected snap changed. |
| `onApi` | `(api: CarouselApi) => void` | `() => {}` | The engine's API once ready: scrollTo, scrollSnapList, scrollProgress, on(event). |

### CarouselItem

| Attribute | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | `""` | The slide's name; default "N of M". |

### CarouselPrevious, CarouselNext

| Attribute | Type | Default | Description |
|---|---|---|---|
| `variant` | `"primary" \| "secondary" \| "outline" \| "ghost"` | `"outline"` | Button look. |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | Button size; the button stays centered just outside the track. |
| `label` | `string` | `"Previous slide" / "Next slide"` | The button's accessible name. |

### all

| Attribute | Type | Default | Description |
|---|---|---|---|
| `class, attrs` | `string, Record` | `"", {}` | Extra classes and attributes. On CarouselContent, class goes on the track and attrs on the viewport. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` | `Carousel` | CarouselContent, then CarouselPrevious and CarouselNext (anywhere inside). |
| `default` | `CarouselContent` | CarouselItem slides. |
| `default` | `CarouselItem` | The slide's content. |

## Keyboard

| Keys | Action |
|---|---|
| `ArrowLeft / ArrowRight` | Focus inside a horizontal carousel: previous and next slide (mirrored under rtl). |
| `ArrowUp / ArrowDown` | Focus inside a vertical carousel: previous and next slide. |
| `Tab / Shift + Tab` | Through the rotation control, the slides' content, the buttons and the pickers, in page order. |
| `Enter / Space` | On a button: activates it without moving focus, so it can be pressed again. |
| `ArrowLeft / ArrowRight, Home / End` | On a tab picker (pickers tabs): the previous, next, first or last tab and its slide; wraps. |

## Data attributes

| Attribute | Values | On | Description |
|---|---|---|---|
| `data-orientation` | `"horizontal" \| "vertical"` | root |  |
| `data-ready` | present | root | Once the engine is running. |
| `data-autoplay` | present | root |  |
| `data-in-view` | present | .carousel-item | While the slide is in view. |
| `data-disabled` | present | CarouselPrevious, CarouselNext | Nothing more that way. |
| `data-state` | `"active" \| "inactive"` | .carousel-dot |  |
| `data-pickers` | `"group" \| "tabs"` | .carousel-dots |  |
| `data-state` | `"playing" \| "stopped"` | .carousel-rotation |  |
| `--carousel-item-size` | length | root or item | Slide flex-basis; default 100%. |
| `--carousel-gap` | length | root | Space between slides; default --space-4. |

## Accessibility

- The root is a region with aria-roledescription="carousel" and label as its name; each slide is a group with aria-roledescription="slide" named "N of M" (WAI-ARIA carousel pattern).
- The track is a polite live region (aria-atomic false) so a screen reader hears the new slide, and off while autoplay rotates.
- Previous, next, picker and rotation buttons keep focus when pressed. The current picker is aria-disabled, not disabled, so it stays reachable.
- pickers tabs follows the APG tabbed carousel: a tablist labelled "Choose slide to display", tabs named for their slides, slides as tabpanels.
- Autoplay: the rotation control is the first tab stop and its label says what it will do; rotation pauses while hovered and stops when keyboard focus enters.

## See also

- [Sidebar](sidebar): An app sidebar that collapses to icons or off the canvas and becomes a sheet on phones.
- [Resizable](resizable): Panels separated by handles you drag or move with the arrow keys.
- [ScrollArea](scroll-area): A scroll container with thin, themed scrollbars over native scrolling.