# Carousel

> Swipeable slides with arrows, animated dots, keys and pausable autoplay.

Component · Pro · https://lodeui.com/components/carousel

## When to use

- Featured content, product galleries and onboarding slides.

## When not to use

- Critical content: most people never see slide 3.
- Comparing items: use a grid.

## Installation

```bash
npx shadcn@latest add @lode/carousel
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion, lucide-react

## Usage

```tsx title="example.tsx"
import { Carousel } from "@/components/ui/carousel";

<Carousel aria-label="Highlights" autoPlay={5000} slides={features.map((f) => <FeatureSlide key={f.id} feature={f} />)} />
```

## API reference

### Carousel

Full-width slides with drag, arrows, dots, keys and optional autoplay.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| slides | `ReactNode[]` | – | One element per slide. |
| loop | `boolean` | `true` | Wrap around at the ends. |
| autoPlay | `number` | `0` | ms between slides; 0 is off. Pauses on hover and focus. |
| aspectRatio | `string` | `"16 / 9"` | Viewport ratio. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| ← / → | Previous or next slide |
| Tab | Reach arrows, dots and pause |

## Accessibility

- Follows the WAI carousel pattern: labelled region, slides announced as "n of m".
- Off-screen slides are inert and hidden.
- Autoplay pauses on hover and focus and has a pause button.

## Motion

- Slides glide with a spring; drags settle by distance plus velocity.
- The active dot stretches into a pill.
- Instant under reduced motion.

## Responsive behavior

- Measures its width, so slides always fill the viewport.

## Performance

- One transformed track; slides stay mounted for instant swipes.

## Notes for AI

- Keep autoplay at 4 seconds or slower.

## Related

- [Swipe deck](https://lodeui.com/components/swipe-deck) — Tinder-style card stack: drag, tap or use arrow keys to pass or like, with undo.
- [Image compare](https://lodeui.com/components/image-compare) — Before and after slider with drag, hover and keyboard control.
- [Marquee](https://lodeui.com/components/marquee) — Endless, seamless scroller for logos and testimonials that glides to a stop on hover.