Carousel

Carousel presents a sequence of related items in a limited area. It uses Embla Carousel for movement and adds argv-styled controls, slide semantics, and keyboard navigation.

Use it when users can browse items in sequence without needing to compare every item at once. Avoid hiding essential information in a carousel when it could be shown clearly in a list or grid.

Installation

pnpm dlx shadcn@latest add http://ui.argv-tech.dev/r/carousel.json

Usage

import {
    Carousel,
    CarouselContent,
    CarouselItem,
    CarouselNext,
    CarouselPrevious
} from "@/components/ui/argv/carousel"

<Carousel aria-label="Release notes">
    <CarouselContent>
        <CarouselItem>Release 24</CarouselItem>
        <CarouselItem>Release 23</CarouselItem>
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
</Carousel>

Composition

Carousel
├── CarouselContent
│   └── CarouselItem
├── CarouselPrevious
└── CarouselNext

CarouselContent provides the viewport and track. Each direct CarouselItem is one slide and fills the viewport by default. Change an item's basis through className to show more than one slide at a time.

Orientation

Set orientation="vertical" to move along the y-axis. Give the carousel content a fixed height so the viewport has a visible boundary.

<Carousel orientation="vertical" className="h-80">
    <CarouselContent className="h-80">
        <CarouselItem>First event</CarouselItem>
        <CarouselItem>Second event</CarouselItem>
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
</Carousel>

API Reference

Carousel

Set orientation="horizontal" for left and right movement or orientation="vertical" for up and down movement. Pass Embla behavior options through opts and optional extensions through plugins.

Use setApi when another component needs access to the Embla API, such as an external counter or navigation control. Most basic carousels do not need it.

CarouselContent

Forwards native div props to the track. Use className to control the track layout and spacing.

CarouselItem

Forwards native div props and renders role="group" with aria-roledescription="slide".

CarouselPrevious and CarouselNext

Accept Button props. Both default to variant="outline" and size="icon", and are disabled automatically when the carousel cannot move in their direction.

Accessibility

The root exposes role="region" and aria-roledescription="carousel". Give it an accessible label that describes the collection rather than repeating the word “carousel.”

Items expose slide semantics, but they still need a useful position or name when context matters. Horizontal carousels respond to Left and Right, while vertical carousels respond to Up and Down.

Do not rely on automatic movement. If autoplay is added through a plugin, provide a way to pause it.