Carousel

A horizontally or vertically scrolling set of slides with swipe, keyboard and button navigation, built on Embla.

TokensOne source of truth

ComponentsAccessible by default

PatternsProven compositions

ThemesBring your own brand

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

const slides = [
  {
    title: "Tokens",
    body: "One source of truth",
  },
  {
    title: "Components",
    body: "Accessible by default",
  },
  {
    title: "Patterns",
    body: "Proven compositions",
  },
  {
    title: "Themes",
    body: "Bring your own brand",
  },
]

export default function CarouselDemo() {
  return (
    <Carousel className="w-full max-w-44" aria-label="prfct highlights">
      <CarouselContent>
        {slides.map((slide, index) => (
          <CarouselItem
            key={slide.title}
            aria-label={`${index + 1} of ${slides.length}`}
          >
            <div className="flex aspect-square flex-col justify-between rounded-xl bg-muted p-4">
              <span className="font-mono text-xs text-muted-foreground numeric">
                {String(index + 1).padStart(2, "0")}
              </span>
              <div className="flex flex-col">
                <span className="text-heading-md text-foreground">
                  {slide.title}
                </span>
                <span className="text-sm text-muted-foreground">
                  {slide.body}
                </span>
              </div>
            </div>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}

Anatomy

1ContentThe viewport. It clips the slides that are off screen and follows a drag or a swipe.
2PreviousMoves one slide back. Disabled on the first slide unless the carousel loops.
3ItemOne slide, a group announced as a slide. Label it by its position.
4NextMoves one slide forward. Disabled on the last slide unless the carousel loops.

Installation

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/carousel.json

Usage

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

<Carousel aria-label="Product screenshots">
  <CarouselContent>
    <CarouselItem>…</CarouselItem>
    <CarouselItem>…</CarouselItem>
    <CarouselItem>…</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

The previous and next buttons sit outside the slides, 48px to the left and right. Leave room for them — or position them yourself with className.

Set the slide width with a basis-* class on CarouselItem. Combine it with responsive prefixes to show more slides on wider screens, and opts={{ align: "start" }} to snap slides to the leading edge.

InvoiceLine items, tax and totals

ChangelogDated entries with tags

Pricing pageThree tiers and an FAQ

Onboarding emailA five-step welcome series

Status pageUptime and incident history

Release notesHighlights, fixes, upgrades

Team wikiNested pages with search

import {
  ActivityIcon,
  BookOpenIcon,
  MailIcon,
  ReceiptIcon,
  RocketIcon,
  ScrollTextIcon,
  TagIcon,
  type LucideIcon,
} from "lucide-react"

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

const templates: { name: string; description: string; icon: LucideIcon }[] = [
  {
    name: "Invoice",
    description: "Line items, tax and totals",
    icon: ReceiptIcon,
  },
  {
    name: "Changelog",
    description: "Dated entries with tags",
    icon: ScrollTextIcon,
  },
  {
    name: "Pricing page",
    description: "Three tiers and an FAQ",
    icon: TagIcon,
  },
  {
    name: "Onboarding email",
    description: "A five-step welcome series",
    icon: MailIcon,
  },
  {
    name: "Status page",
    description: "Uptime and incident history",
    icon: ActivityIcon,
  },
  {
    name: "Release notes",
    description: "Highlights, fixes, upgrades",
    icon: RocketIcon,
  },
  {
    name: "Team wiki",
    description: "Nested pages with search",
    icon: BookOpenIcon,
  },
]

export default function CarouselSizes() {
  return (
    // px-12 leaves room for the previous and next buttons, which sit outside the slides.
    <div className="w-full max-w-lg px-12">
      <Carousel opts={{ align: "start" }} aria-label="Templates">
        <CarouselContent>
          {templates.map((template, index) => (
            <CarouselItem
              key={template.name}
              className="basis-1/2 sm:basis-1/3"
              aria-label={`${index + 1} of ${templates.length}`}
            >
              <Card size="sm" className="h-full">
                <CardContent className="flex h-full flex-col gap-6">
                  <div
                    className="flex size-9 items-center justify-center rounded-lg border bg-surface text-muted-foreground"
                    aria-hidden="true"
                  >
                    <template.icon className="size-4" />
                  </div>
                  <div className="mt-auto flex flex-col gap-0.5">
                    <span className="text-sm font-medium">{template.name}</span>
                    <span className="text-xs text-muted-foreground">
                      {template.description}
                    </span>
                  </div>
                </CardContent>
              </Card>
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
      </Carousel>
    </div>
  )
}

<Carousel opts={{ align: "start" }}>
  <CarouselContent>
    <CarouselItem className="basis-1/2 sm:basis-1/3">…</CarouselItem>
  </CarouselContent>
</Carousel>

Spacing

Slides are separated by padding on CarouselItem and a matching negative margin on CarouselContent (16px by default). To change the gap, change both: -ml-2 on the content and pl-2 on each item.

Vertical

orientation="vertical" scrolls on the y-axis. Give CarouselContent a fixed height; the buttons move above and below.