Siteplane UI

Carousel

Show slides one at a time and move between them with arrows, dots, the arrow keys or a swipe.

Markdown
"use client";

import {
  Carousel,
  CarouselContent,
  CarouselIndicator,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/siteplane/components/carousel";

// Placeholder pictures; use your own screenshots or illustrations.
const picture = (hue: number) =>
  `data:image/svg+xml,${encodeURIComponent(
    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 750">` +
      `<defs><linearGradient id="g" x2="1" y2="1"><stop stop-color="hsl(${hue},65%,78%)"/><stop offset="1" stop-color="hsl(${hue + 70},50%,35%)"/></linearGradient></defs>` +
      `<path fill="url(#g)" d="M0 0h1200v750H0z"/>` +
      `<circle cx="265" cy="200" r="320" fill="white" opacity=".16"/>` +
      `<path d="M0 610Q300 260 600 540T1200 360V750H0Z" fill="white" opacity=".18"/></svg>`,
  )}`;

const slides = [
  { alt: "Dashboard overview", hue: 210 },
  { alt: "Team activity", hue: 260 },
  { alt: "Project timeline", hue: 170 },
];

export default function Example() {
  return (
    <div className="aspect-[1.6] w-full max-w-xl">
      <Carousel aria-label="Product tour">
        <CarouselPrevious />
        <CarouselNext />
        <CarouselIndicator framed />
        <CarouselContent>
          {slides.map((slide) => (
            <CarouselItem key={slide.alt}>
              <img alt={slide.alt} src={picture(slide.hue)} />
            </CarouselItem>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  );
}

Installation

pnpm dlx shadcn@4.18.0 add @siteplane/carousel

Complete the one-time setup first. Registry JSON lists source files and dependencies.

Usage

import {
  Carousel,
  CarouselContent,
  CarouselIndicator,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/siteplane/components/carousel";

<div className="aspect-[1.6] w-full max-w-xl">
  <Carousel aria-label="Product tour">
    <CarouselPrevious />
    <CarouselNext />
    <CarouselIndicator framed />
    <CarouselContent>
      <CarouselItem>
        <img alt="Dashboard overview" src="/tour/dashboard.png" />
      </CarouselItem>
      <CarouselItem>
        <img alt="Team activity" src="/tour/team.png" />
      </CarouselItem>
    </CarouselContent>
  </Carousel>
</div>;

Composition

Carousel
├── CarouselPrevious
├── CarouselNext
├── CarouselIndicator
└── CarouselContent
    └── CarouselItem (one per slide)

CarouselContent holds the slides, one CarouselItem each, in a row that shows one slide at a time. A slide is as wide as the carousel, the slides sit 8 px apart, and a slide clips its content to the corners of a surface; a picture placed directly in it covers it. The carousel fills the height of its container, so give the container a height or an aspect ratio, as aspect-[1.6] does in the examples.

CarouselPrevious and CarouselNext sit over the slide at its edges, in the middle of its height, and CarouselIndicator over the middle of its bottom, 16 px from it. The arrows are pill Buttons that are disabled on the first and the last slide, and the indicator is a Page Indicator with one dot for each slide.

Sizes

size="md", the default, has 36 px arrows 16 px from the edges and 8 px dots. size="lg" has 44 px arrows 20 px from the edges and 10 px dots.

"use client";

import {
  Carousel,
  CarouselContent,
  CarouselIndicator,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/siteplane/components/carousel";

// Placeholder pictures; use your own screenshots or illustrations.
const picture = (hue: number) =>
  `data:image/svg+xml,${encodeURIComponent(
    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 750">` +
      `<defs><linearGradient id="g" x2="1" y2="1"><stop stop-color="hsl(${hue},65%,78%)"/><stop offset="1" stop-color="hsl(${hue + 70},50%,35%)"/></linearGradient></defs>` +
      `<path fill="url(#g)" d="M0 0h1200v750H0z"/>` +
      `<circle cx="265" cy="200" r="320" fill="white" opacity=".16"/>` +
      `<path d="M0 610Q300 260 600 540T1200 360V750H0Z" fill="white" opacity=".18"/></svg>`,
  )}`;

const slides = [
  { alt: "Revenue report", hue: 20 },
  { alt: "Invoice list", hue: 300 },
  { alt: "Payout schedule", hue: 120 },
  { alt: "Billing settings", hue: 230 },
];

export default function Example() {
  return (
    <div className="aspect-[1.6] w-full max-w-xl">
      <Carousel aria-label="Billing features" size="lg">
        <CarouselPrevious />
        <CarouselNext />
        <CarouselIndicator framed />
        <CarouselContent>
          {slides.map((slide) => (
            <CarouselItem key={slide.alt}>
              <img alt={slide.alt} src={picture(slide.hue)} />
            </CarouselItem>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  );
}

Indicator

CarouselIndicator marks the current slide, and a click on a dot moves to its slide. framed sets the dots on a translucent pill with a blur, so they stay readable on a picture. Without it the dots stand on the slide itself, which suits slides of text, such as these customer stories. variant="line" draws a line of segments in place of the dots. The segments share the width of the indicator, which spans a third of the carousel and stays centred as the dots do; a width class on the indicator, such as w-1/2, gives it another width.

"use client";

import {
  Carousel,
  CarouselContent,
  CarouselIndicator,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/siteplane/components/carousel";

const stories = [
  {
    name: "Mara Ellis",
    quote:
      "Our weekly reports used to take a day. Now they are ready before the first meeting.",
    role: "Head of Operations, Halden Logistics",
  },
  {
    name: "Ben Carter",
    quote:
      "Every client sees the same numbers we do, so our review calls are short.",
    role: "Founder, Brightwave Studio",
  },
  {
    name: "Sofia Nguyen",
    quote: "Invoices, payouts and refunds finally live in one place.",
    role: "Finance Lead, Ortega Foods",
  },
];

export default function Example() {
  return (
    <div className="h-64 w-full max-w-xl">
      <Carousel aria-label="Customer stories">
        <CarouselPrevious />
        <CarouselNext />
        <CarouselIndicator />
        <CarouselContent>
          {stories.map((story) => (
            <CarouselItem key={story.name}>
              <figure className="flex h-full flex-col items-center justify-center gap-4 px-16 pb-10 text-center">
                <blockquote className="text-lg">“{story.quote}”</blockquote>
                <figcaption className="text-sm text-muted-foreground">
                  {story.name}, {story.role}
                </figcaption>
              </figure>
            </CarouselItem>
          ))}
        </CarouselContent>
      </Carousel>
    </div>
  );
}

Controlled slide

Keep the slide in state with index and onIndexChange, counted from 0, when other parts of the page follow it, such as a caption or a button that starts over. defaultIndex sets the first slide of a carousel that keeps its own state.

Step 1 of 3: Connect your data

"use client";

import { useState } from "react";
import { Button } from "@/siteplane/components/button";
import {
  Carousel,
  CarouselContent,
  CarouselIndicator,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/siteplane/components/carousel";

// Placeholder pictures; use your own screenshots or illustrations.
const picture = (hue: number) =>
  `data:image/svg+xml,${encodeURIComponent(
    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 750">` +
      `<defs><linearGradient id="g" x2="1" y2="1"><stop stop-color="hsl(${hue},65%,78%)"/><stop offset="1" stop-color="hsl(${hue + 70},50%,35%)"/></linearGradient></defs>` +
      `<path fill="url(#g)" d="M0 0h1200v750H0z"/>` +
      `<circle cx="265" cy="200" r="320" fill="white" opacity=".16"/>` +
      `<path d="M0 610Q300 260 600 540T1200 360V750H0Z" fill="white" opacity=".18"/></svg>`,
  )}`;

const steps = [
  { hue: 210, title: "Connect your data" },
  { hue: 260, title: "Invite your team" },
  { hue: 170, title: "Share a report" },
];

export default function Example() {
  const [index, setIndex] = useState(0);
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <div className="aspect-[1.6]">
        <Carousel
          aria-label="Getting started"
          index={index}
          onIndexChange={setIndex}
        >
          <CarouselPrevious />
          <CarouselNext />
          <CarouselIndicator framed />
          <CarouselContent>
            {steps.map((step) => (
              <CarouselItem key={step.title}>
                <img alt={step.title} src={picture(step.hue)} />
              </CarouselItem>
            ))}
          </CarouselContent>
        </Carousel>
      </div>
      <div className="flex items-center justify-between gap-4">
        <p className="text-sm text-muted-foreground">
          Step {index + 1} of {steps.length}: {steps[index]?.title}
        </p>
        <Button
          disabled={index === 0}
          onClick={() => setIndex(0)}
          size="xs"
          variant="outline"
        >
          Start over
        </Button>
      </div>
    </div>
  );
}

A part inside the carousel can read its state with useCarousel(): the current index, the count of slides, canScrollPrevious and canScrollNext, and scrollPrevious, scrollNext and scrollTo(index) to move it.

function SlideCount() {
  const { count, index } = useCarousel();
  return (
    <span>
      {index + 1} / {count}
    </span>
  );
}

Keyboard, pointer and motion

Tab moves to the arrows, the dots and the content of the current slide. While focus is inside the carousel, ArrowLeft and ArrowRight move to the previous and the next slide; a text field in a slide keeps its own arrow keys. A drag with the mouse or a swipe on a touch screen moves the slides with the pointer and turns the slide once it has gone a fifth of the way, or at a quick flick. Past the first and the last slide it gives only a third of the way and springs back. A drag does not click what lies under the pointer, a picture does not start the browser's own drag, and a vertical swipe still scrolls the page.

A slide settles over 800 ms on the carousel curve, --motion-duration-carousel and --motion-ease-carousel of the Motion settings, and follows a drag at once. With reduced motion the slides change at once. In a right-to-left page the slides run from right to left, the arrows point the other way, and ArrowRight moves back.

Accessibility

The carousel is a region with the role description “carousel”, so name it with aria-label, such as “Product tour”. Each slide is a group with the role description “slide”, named by its place, such as “2 of 3”. These words are the carousel messages of SiteplaneLocaleProvider, and an aria-label on a CarouselItem names one slide otherwise. The slides out of view are inert, so their links and buttons stay out of the focus order. The arrows are named “Previous slide” and “Next slide”, and an aria-label on them replaces the names. The indicator is a group named “Slides” whose dots are named “Go to slide 1” and so on, with aria-current="page" on the current one; labels replaces those names. The names of the arrows and of the indicator are carousel messages as well, so one translation covers every carousel.

API reference

Component properties
PropTypeDefaultDescription
Carousel.indexnumberunsetThe current slide, counted from 0, in a carousel that the application controls.
Carousel.defaultIndexnumber0The slide shown first, counted from 0, in a carousel that keeps its own state.
Carousel.onIndexChange(index: number) => voidunsetCalled with the slide a person moves to, counted from 0.
Carousel.sizemd | lgmdmd has 36 px arrows 16 px from the edges and 8 px dots, lg 44 px arrows 20 px from the edges and 10 px dots.
Carousel.aria-labelstringunsetThe name of the carousel region. Give every carousel one.
CarouselContentdiv props—The viewport that clips the slides and the track that carries them, 8 px apart. A drag or a swipe along it turns the slide.
CarouselItemdiv props—One slide, as wide as the carousel. Named by its place, such as 2 of 3, unless it has an aria-label; inert while it is out of view.
CarouselPrevious / CarouselNextButton props except profile, profileTone, shape, size and variant—The pill Button at icon-sm (md) or icon-lg (lg), named Previous slide or Next slide, disabled on the first or the last slide. An onClick runs first; preventDefault keeps the slide.
CarouselIndicator.framedbooleanfalseSets the dots on a translucent pill with a blur, for slides with pictures.
CarouselIndicator.variantdot | linedotDots, or a line of segments that shares the width of the indicator, a third of the carousel unless a width class sets another.
CarouselIndicator.labelsPartial<PageIndicatorLabels>Slides; Go to slide NReplaces the name of the group and the names of the dots, each on its own.
CarouselIndicator.classNamestringunsetClasses for the indicator's wrapper, such as a width for the line.
useCarousel()CarouselContextValue—Inside a Carousel: index, count, canScrollPrevious, canScrollNext, scrollPrevious, scrollNext, scrollTo and size.

Carousel renders a div with role="region", aria-roledescription="carousel", data-slot="carousel" and data-size, and accepts the props of a div except defaultValue and onChange. CarouselContent carries data-slot="carousel-content" and, while a pointer drags it, data-dragging; its track is carousel-track. The slides carry carousel-item, the arrows carousel-previous and carousel-next, and the indicator's wrapper carousel-indicator. Carousel, CarouselContent and CarouselItem accept a ref. CarouselIndicator passes the other props of Page Indicator through, except count, page, onPageChange and size, which the carousel sets. The parts and useCarousel() must be used inside a Carousel. The types CarouselProps, CarouselSize and CarouselContextValue are exported.

Read the installed source.

Usage notes

Use a carousel for a few related pictures or messages of which people need to see only one at a time, such as a product tour, the screenshots of a feature or customer stories. Content that everyone must read belongs on the page, where nothing hides it behind a slide, and pictures that people compare with each other belong side by side in a grid.

The carousel does not loop from the last slide to the first, has no vertical orientation and does not advance on its own. A slide changes only when a person moves it.