Carousel
FreeBrowse 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 carouselPlayground
Installation
npx wunderui-cli add carouselWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Carousel } from "@/components/wunderui/carousel"
import type {
CarouselNavigationShape,
CarouselProps,
} from "@/components/wunderui/carousel"Then use it:
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
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.
Content
A slide is any element. Cards, images and quotes all snap to the start of the row the same way.
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.
Keyboard interactions
The slide strip is a focusable region, so the browser scrolls it with arrow keys. The two arrows are buttons.
- TaborShift+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.
- 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.
- 1
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.
- 2Optional
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.
- 3
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.
- 4
Each child sits in a snap point. Slides keep their own width, or each fills the strip in full-width mode.
- 5Optional
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.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | React.ReactNode | — | The slides. Each child becomes one slide in its own snap point, so pass one element per slide, such as a card. |
| label | string | "Carousel" | The accessible name of the slide strip, such as . The default is . |
| slideSize | "auto" | "full" | "auto" | keeps every slide at its own width, so part of the next slide shows. makes each slide as wide as the strip, one slide at a time. |
| 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. |
| navigationShape | "circle" | "rounded" | "rounded" | The shape of the two arrow buttons: is a rounded square, is a circle. |
| 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. |
| onIndexChange | (index) => 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. |
| 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. or leaving it out turns it off. |
| 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. |
| className | string | — | Extra classes for the row, merged with its own . Use it for a width such as or a margin. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("carousel")npx wunderui-cli add carouselThe full library index for assistants is at /llms.txt.