Skip to content
WunderUI

Carousel

Free

Browse a row of similar items, such as project cards or screenshots, one step at a time, with arrows beside the row.

npx wunderui-cli add carousel

Playground

Checkout redesign
Cart, address and payment steps.
Design tokens v2
One source for colour, type and spacing.
Billing portal
Invoices, plans and payment methods.
Analytics
Traffic, conversion and retention.
Onboarding
A short tour for new teammates.

Installation

bash
npx wunderui-cli add carousel

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Card for a grid of cards when every item matters or the numbers need comparing side by side
  • Tabs for a few different views that people switch between
  • Stepper for the steps of a process that someone moves through in order

Slide size

Every slide keeps its own width, or one slide fills the row. The arrows sit beside the row, never on top of a card.

Checkout redesign
Cart, address and payment steps.
Design tokens v2
One source for colour, type and spacing.
Billing portal
Invoices, plans and payment methods.
Analytics
Traffic, conversion and retention.
Onboarding
A short tour for new teammates.

Content

A slide is any element. Cards, images and quotes all snap to the start of the row the same way.

Checkout redesign
Cart, address and payment steps.
Design tokens v2
One source for colour, type and spacing.
Billing portal
Invoices, plans and payment methods.
Analytics
Traffic, conversion and retention.
Onboarding
A short tour for new teammates.

Position

At either end the arrow stays on screen but is disabled, so keyboard focus does not fall to the page. Set the index to scroll to a slide.

Checkout redesign
Cart, address and payment steps.
Design tokens v2
One source for colour, type and spacing.
Billing portal
Invoices, plans and payment methods.
Analytics
Traffic, conversion and retention.
Onboarding
A short tour for new teammates.
Support portal
Tickets, answers and status in one place.

Keyboard interactions

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

TaborShiftTab
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.
EnterorSpace
Presses the focused arrow and steps one slide. On a disabled arrow nothing happens.

Behavior and motion

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

The parts of the row, numbered in the figure. Dots, thumbnails and a counter are not part of the carousel, so build them from the index and its change handler.

Checkout redesign
Cart, address and payment steps.
Design tokens v2
One source for colour, type and spacing.
Billing portal
Invoices, plans and payment methods.
Analytics
Traffic, conversion and retention.
Onboarding
A short tour for new teammates.
  • 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.

  • Optional

    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.

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

  • Each child sits in a snap point. Slides keep their own width, or each fills the strip in full-width mode.

  • Optional

    The same icon button on the right. It steps one slide forward and is disabled, not hidden, on the last slide.

Best practices

  • Do

    Set the label to what the row holds, such as Recent projects. The default Carousel tells nobody what is inside.

  • Do

    Keep the arrows beside the row. They never sit on top of a card, so a slide can hold its own buttons and links.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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

    Don't autoplay in a dashboard or on a page people read. Moving content competes with the text.

API reference

Carousel is one component with the props below. It renders its own row, strip and arrow buttons.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("carousel")
Installnpx wunderui-cli add carousel

The full library index for assistants is at /llms.txt.