# Carousel

A horizontally scrollable row of items with arrow controls.

- Category: Core Elements
- Page: https://wunderui.com/components/carousel
- Tier: Free

## Install

```bash
npx wunderui-cli add carousel
```

## Import

```tsx
import { Carousel, CarouselNavigationShape, CarouselProps } from "@/components/wunderui/carousel"
```

## Minimal usage

Then use it:

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
]

export function RecentProjects() {
  return (
    <Carousel label="Recent projects">
      {PROJECTS.map((project) => (
        <Card key={project.id} className="w-48">
          <CardMedia className="h-24" />
          <CardHeader>
            <CardTitle>{project.title}</CardTitle>
            <CardDescription>{project.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </Carousel>
  )
}
```

Expected result: You see a row of project cards between two arrow buttons. The cards are wider than the row, so the next arrow works and the previous one is disabled.

## Usage

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
  { id: "onboarding", title: "Onboarding", text: "A short tour for new teammates." },
]

export function Example() {
  return (
    <Carousel label="Recent projects">
      {PROJECTS.map((project) => (
        <Card key={project.id} className="w-48">
          <CardMedia className="h-24" />
          <CardHeader>
            <CardTitle>{project.title}</CardTitle>
            <CardDescription>{project.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </Carousel>
  )
}
```

## When to use

### Use Carousel for

- A row of similar items that people browse, such as project cards, screenshots or template previews
- One slide at a time, for a gallery or a short product tour driven by dots, thumbnails or buttons
- A row of cards that is wider than its container, on a narrow screen

### Use something else

- [Card](https://wunderui.com/components/card) for a grid of cards when every item matters or the numbers need comparing side by side
- [Tabs](https://wunderui.com/components/tabs) for a few different views that people switch between
- [Stepper](https://wunderui.com/components/stepper) for the steps of a process that someone moves through in order

## Keyboard

The slide strip is a focusable region, so the browser scrolls it with arrow keys. The two arrows are buttons.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus through the previous button, the slide strip, the controls inside the slides and the next button, in that order. An arrow at either end of the row stays focusable. |
| `←` or `→` | With focus in the slide strip, scrolls the row to the left or right. It snaps to the start of a slide when it stops. |
| `Enter` or `Space` | Presses the focused arrow and steps one slide. On a disabled arrow nothing happens. |

## Behavior

What the carousel does with its slides, its arrows and the scroll, and what it leaves to you.

- **Slides:** Each child snaps to the start. A slide keeps its own width by default, so a row of cards shows part of the next one, and full-width mode shows one slide at a time.
- **Arrows:** An arrow steps to the next slide, or back to the nearest one, and stays focusable but disabled at an end. When nothing overflows, both arrows are hidden but keep their place.
- **Scroll and snap:** The strip snaps to slides. Arrows and the index move it with a spring that settles in about a second, and touch, the wheel and a drag take over at once.
- **Drag:** With a mouse or pen the row follows the pointer after 5 px and springs to the nearest slide on release. A quick flick goes one further, and the click ending a drag opens nothing.
- **Controlled index:** The index scrolls to a slide and the change handler reports the one in view, so dots, thumbnails, a counter and buttons stay in step. You write those controls yourself.
- **Autoplay:** Autoplay moves one slide per interval and starts over after the last. It waits while the pointer or focus is inside or the tab is hidden, and does not run with reduced motion.
- **Names for screen readers:** The strip is a region named by its label, and after a scroll stops a polite live region reads the visible items, such as 2 to 4 of 6. Name your own dots and thumbnails.
- **Motion:** The row scrolls with a critically damped spring of about a second. The arrows fade when they become disabled, and your dots and thumbnails should animate colour only.
- **Reduced motion:** With reduced motion the row jumps to its target at once and autoplay does not start.

## Anatomy

- `Carousel`: A row with a previous button, the slide strip and a next button. It snaps to each slide, takes the width of its parent and pauses autoplay while the pointer or focus is inside.
- `Previous button`: A plain icon button on the left, square or round, that steps one slide back. It stays visible but disabled on the first slide, and is hidden but keeps its place when nothing overflows.
- `Slide strip`: The focusable region, named by its label. It scrolls with arrow keys, swipes on touch and drags with a mouse or pen, and announces the visible items, such as 2 to 4 of 6, once a scroll stops.
- `Slide`: Each child sits in a snap point. Slides keep their own width, or each fills the strip in full-width mode.
- `Next button`: The same icon button on the right. It steps one slide forward and is disabled, not hidden, on the last slide.

## Best practices

### When to use

- Use a Carousel for a row of similar items people browse, such as project cards, screenshots or template previews. When every item matters or needs comparing, use a grid.

### Do

- Set the label to what the row holds, such as Recent projects. The default Carousel tells nobody what is inside.
- Keep the arrows beside the row. They never sit on top of a card, so a slide can hold its own buttons and links.
- Drive dots, thumbnails or a counter through the index and its change handler instead of scrolling the strip yourself. The carousel springs to the slide and reports the one in view.
- Show how many slides there are, with a counter like Slide 2 of 5, dots or thumbnails. Arrows alone do not tell people where they are.
- Offer a pause button next to autoplay, and use autoplay for images, not text. It already pauses on hover, focus, a hidden tab and reduced motion, but moving slides are hard to read.

### Don't

- Don't put the only way to reach important content inside a carousel. People skip it, and a grid shows everything at once.
- Don't leave drag on when slides hold controls that need the mouse, such as a slider. Turn it off; touch still swipes.
- Don't autoplay in a dashboard or on a page people read. Moving content competes with the text.

## API reference

### Carousel

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The slides. Each child becomes one slide in its own snap point, so pass one element per slide, such as a card. |
| autoPlay | number |  | Advances one slide every this many milliseconds and starts over after the last one. It stops while the pointer or the keyboard focus is inside, while the tab is hidden and with reduced motion. `0` or leaving it out turns it off. |
| className | string |  | Extra classes for the row, merged with its own `flex w-full items-center gap-3`. Use it for a width such as `max-w-xl` or a margin. |
| drag | boolean | true | Drags the slides left or right with a mouse or a pen. The row follows the pointer and springs to the nearest slide on release; a quick flick goes one slide further. Touch swipes either way. Turn it off when slides hold controls that need the mouse. |
| index | number |  | The slide the row shows, for dots, thumbnails and buttons that control it. A new value scrolls to that slide with the spring, and the row stays free to scroll on its own. |
| label | string | "Carousel" | The accessible name of the slide strip, such as `Recent projects`. The default is `Carousel`. |
| navigationShape | "circle" \| "rounded" | "rounded" | The shape of the two arrow buttons: `rounded` is a rounded square, `circle` is a circle. |
| onIndexChange | (index: number) => void |  | Called with the number of the slide the row now shows, counting from 0. It also fires when someone swipes, drags or uses an arrow, so the controls outside stay in step. |
| showArrows | boolean | true | Shows the previous and next buttons beside the row. Turn them off when dots, thumbnails or your own buttons do the navigating. |
| slideSize | "auto" \| "full" | "auto" | `auto` keeps every slide at its own width, so part of the next slide shows. `full` makes each slide as wide as the strip, one slide at a time. |

## Examples

### Slide size: own width or the full row

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
  { id: "onboarding", title: "Onboarding", text: "A short tour for new teammates." },
]

export function Example() {
  return (
    <Carousel label="Recent projects">
      {PROJECTS.map((project) => (
        <Card key={project.id} className="w-48">
          <CardMedia className="h-24" />
          <CardHeader>
            <CardTitle>{project.title}</CardTitle>
            <CardDescription>{project.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </Carousel>
  )
}
```

### Content: cards, images and quotes

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
  { id: "onboarding", title: "Onboarding", text: "A short tour for new teammates." },
]

export function Example() {
  return (
    <Carousel label="Recent projects">
      {PROJECTS.map((project) => (
        <Card key={project.id} className="w-48">
          <CardMedia className="h-24" />
          <CardHeader>
            <CardTitle>{project.title}</CardTitle>
            <CardDescription>{project.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </Carousel>
  )
}
```

### Position: first, middle and last

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
  { id: "onboarding", title: "Onboarding", text: "A short tour for new teammates." },
  { id: "support", title: "Support portal", text: "Tickets, answers and status in one place." },
]

export function Example() {
  // On the first slide Previous is disabled.
  return (
    <Carousel label="Recent projects">
      {PROJECTS.map((project) => (
        <Card key={project.id} className="w-48">
          <CardMedia className="h-24" />
          <CardHeader>
            <CardTitle>{project.title}</CardTitle>
            <CardDescription>{project.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </Carousel>
  )
}
```

## In context

### Featured projects: autoplay with a pause button

The row moves one card every three seconds and loops. It waits while the pointer or focus is inside and never runs with reduced motion, and the button pauses it for good.

```tsx
import { useState } from "react"
import { Pause, Play } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
  { id: "onboarding", title: "Onboarding", text: "A short tour for new teammates." },
  { id: "support", title: "Support portal", text: "Tickets, answers and status in one place." },
]

export function Example() {
  const [playing, setPlaying] = useState(true)

  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex items-center justify-between gap-3">
        <p className="text-sm font-medium">Featured projects</p>
        <Button variant="plain" size="sm" onClick={() => setPlaying(!playing)}>
          {playing ? <Pause /> : <Play />}
          {playing ? "Pause" : "Play"}
        </Button>
      </div>
      <Carousel label="Featured projects" autoPlay={playing ? 3000 : 0}>
        {PROJECTS.map((project) => (
          <Card key={project.id} className="w-48">
            <CardMedia className="h-24" />
            <CardHeader>
              <CardTitle>{project.title}</CardTitle>
              <CardDescription>{project.text}</CardDescription>
            </CardHeader>
          </Card>
        ))}
      </Carousel>
    </div>
  )
}
```

### Template gallery: thumbnails and a counter

One large slide at a time. The thumbnails and the counter follow the visible slide, and a thumbnail jumps to its slide.

```tsx
import { useState } from "react"
import { Image as ImageIcon } from "lucide-react"
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
  { id: "billing", title: "Billing portal", text: "Invoices, plans and payment methods." },
  { id: "analytics", title: "Analytics", text: "Traffic, conversion and retention." },
  { id: "onboarding", title: "Onboarding", text: "A short tour for new teammates." },
]

export function Example() {
  const [index, setIndex] = useState(0)

  return (
    <div className="flex w-[400px] max-w-full flex-col gap-3">
      <div className="flex items-center justify-between gap-3">
        <p className="text-sm font-medium">Template gallery</p>
        <p className="text-xs text-text-secondary">
          Slide {index + 1} of {PROJECTS.length}
        </p>
      </div>
      <Carousel label="Template gallery" slideSize="full" index={index} onIndexChange={setIndex}>
        {PROJECTS.map((project) => (
          <Card key={project.id}>
            <CardMedia ratio="16:9" />
            <CardHeader>
              <CardTitle>{project.title}</CardTitle>
              <CardDescription>{project.text}</CardDescription>
            </CardHeader>
          </Card>
        ))}
      </Carousel>
      <div role="group" aria-label="Choose a slide" className="flex flex-wrap justify-center gap-2">
        {PROJECTS.map((project, i) => (
          <button
            key={project.id}
            type="button"
            aria-label={"Show " + project.title}
            aria-current={i === index ? "true" : undefined}
            onClick={() => setIndex(i)}
            className={
              "grid h-10 w-14 place-items-center rounded-md border transition-colors duration-fast ease-move outline-none focus-ring motion-reduce:transition-none " +
              (i === index
                ? "border-tint-text-indigo bg-tint-indigo text-tint-text-indigo"
                : "border-border bg-card text-text-tertiary hover:bg-bg-page")
            }
          >
            <ImageIcon className="size-4" aria-hidden />
          </button>
        ))}
      </div>
    </div>
  )
}
```

### Product tour: buttons drive the row

The arrows are off. Back and Next set the index, and swiping or the arrow keys update the step count.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Carousel } from "@/components/ui/carousel"

const STEPS = [
  { id: "projects", title: "Create a project", text: "Start from a template or an empty board." },
  { id: "invite", title: "Invite your team", text: "Add teammates by email and set their role." },
  { id: "review", title: "Review together", text: "Comment on a card and resolve it when done." },
]

export function Example() {
  const [index, setIndex] = useState(0)
  const last = index === STEPS.length - 1

  return (
    <div className="flex w-[400px] max-w-full flex-col gap-4">
      <Carousel label="Product tour" slideSize="full" showArrows={false} index={index} onIndexChange={setIndex}>
        {STEPS.map((step) => (
          <div key={step.id} className="flex flex-col gap-1 py-2">
            <p className="text-base font-semibold">{step.title}</p>
            <p className="text-sm text-text-secondary">{step.text}</p>
          </div>
        ))}
      </Carousel>
      <div className="flex items-center justify-between gap-3">
        <p className="text-xs text-text-secondary">
          Step {index + 1} of {STEPS.length}
        </p>
        <div className="flex gap-2">
          <Button variant="plain" size="sm" disabled={index === 0} onClick={() => setIndex(index - 1)}>
            Back
          </Button>
          <Button variant="gradient" size="sm" disabled={last} onClick={() => setIndex(index + 1)}>
            Next
          </Button>
        </div>
      </div>
    </div>
  )
}
```

### Recent projects: arrows only when they are needed

When the cards fit the row, the arrows stay hidden but keep their place, so the row never changes width. With more cards they show and step one card at a time.

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"
import { Carousel } from "@/components/ui/carousel"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", text: "Cart, address and payment steps." },
  { id: "tokens", title: "Design tokens v2", text: "One source for colour, type and spacing." },
]

export function Example() {
  // With 2 cards that fit the row, the arrows stay out of sight and keep their place.
  return (
    <Carousel label="Recent projects">
      {PROJECTS.map((project) => (
        <Card key={project.id} className="w-48">
          <CardMedia className="h-24" />
          <CardHeader>
            <CardTitle>{project.title}</CardTitle>
            <CardDescription>{project.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </Carousel>
  )
}
```

## For AI agents

`get_component("carousel")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
