Docs
Components
Carousel

Carousel

A carousel with motion and swipe built using Embla.

Docs API Reference

Preview

Code

About

The carousel component is built using the Embla Carousel library.

Installation

CLI

Manual

npx shadcn@latest add @kanpeki/carousel

Anatomy

import { Carousel } from "~/components/ui/carousel";

<Carousel.Root>
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
  <Carousel.Previous />
  <Carousel.Next />
</Carousel.Root>;

Examples

Sizes

To set the size of the items, you can use the basis utility class on the <Carousel.Item>.

Preview

Code

// 33% of the carousel width.
<Carousel.Root>
  <Carousel.Content>
    <Carousel.Item className="basis-1/3">...</Carousel.Item>
    <Carousel.Item className="basis-1/3">...</Carousel.Item>
    <Carousel.Item className="basis-1/3">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

// 50% on small screens and 33% on larger screens.
<Carousel.Root>
  <Carousel.Content>
    <Carousel.Item className="md:basis-1/2 lg:basis-1/3">...</Carousel.Item>
    <Carousel.Item className="md:basis-1/2 lg:basis-1/3">...</Carousel.Item>
    <Carousel.Item className="md:basis-1/2 lg:basis-1/3">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Spacing

To set the spacing between the items, we use a pl-[VALUE] utility on the <Carousel.Item> and a negative -ml-[VALUE] on the <Carousel.Content>.

Why: I tried to use the gap property or a grid layout on the <Carousel.Content> but it required a lot of math and mental effort to get the spacing right. I found pl-[VALUE] and -ml-[VALUE] utilities much easier to use.

You can always adjust this in your own project if you need to.

Preview

Code

<Carousel.Root>
  <Carousel.Content className="-ml-4">
    <Carousel.Item className="pl-4">...</Carousel.Item>
    <Carousel.Item className="pl-4">...</Carousel.Item>
    <Carousel.Item className="pl-4">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

<Carousel.Root>
  <Carousel.Content className="-ml-2 md:-ml-4">
    <Carousel.Item className="pl-2 md:pl-4">...</Carousel.Item>
    <Carousel.Item className="pl-2 md:pl-4">...</Carousel.Item>
    <Carousel.Item className="pl-2 md:pl-4">...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Orientation

Use the orientation prop to set the orientation of the carousel.

Preview

Code

<Carousel.Root orientation="vertical | horizontal">
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

Options

You can pass options to the carousel using the opts prop. See the Embla Carousel docs for more information.

<Carousel.Root
  opts={{
    align: "start",
    loop: true,
  }}
>
  <Carousel.Content>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
    <Carousel.Item>...</Carousel.Item>
  </Carousel.Content>
</Carousel.Root>

API

Use a state and the setApi prop to get an instance of the carousel API.

Preview

Code

Slide 0 of 0

import { useEffect, useState } from "react";
import { Carousel, type CarouselApi } from "~/registry/ui/carousel"; 

export function Example() {
  const [api, setApi] = useState<CarouselApi>(); 
  const [current, setCurrent] = useState(0);
  const [count, setCount] = useState(0);

  useEffect(() => {
    if (!api) {
      return;
    }

    setCount(api.scrollSnapList().length);
    setCurrent(api.selectedScrollSnap() + 1);

    api.on("select", () => {
      setCurrent(api.selectedScrollSnap() + 1);
    });
  }, [api]);

  return (
    <Carousel.Root setApi={setApi}>
      <Carousel.Content>
        <Carousel.Item>...</Carousel.Item>
        <Carousel.Item>...</Carousel.Item>
        <Carousel.Item>...</Carousel.Item>
      </Carousel.Content>
    </Carousel.Root>
  );
}

Events

You can listen to events using the api instance from setApi.

import type { CarouselApi } from "~/components/ui/carousel"; 

export function Example() {
  const [api, setApi] = useState<CarouselApi>();

  useEffect(() => {
    if (!api) {
      return;
    }

    api.on("select", () => {
      // Do something on select.
    });
  }, [api]);

  return (
    <Carousel.Root setApi={setApi}>
      <Carousel.Content>
        <Carousel.Item>...</Carousel.Item>
        <Carousel.Item>...</Carousel.Item>
        <Carousel.Item>...</Carousel.Item>
      </Carousel.Content>
    </Carousel.Root>
  );
}

See the Embla Carousel docs for more information on using events.

Plugins

You can use the plugins prop to add plugins to the carousel.

import Autoplay from "embla-carousel-autoplay"; 

export function Example() {
  return (
    <Carousel.Root
      plugins={[
        Autoplay({
          delay: 2000,
        }),
      ]}
    >
      // ...
    </Carousel.Root>
  );
}

Preview

Code

See the Embla Carousel docs for more information on using plugins.

API Reference

Carousel.Root

Prop	Type	Default
`orientation`	`enum`	`"horizontal"`
`opts`	`CarouselOptions`
`plugins`	`CarouselPlugin[]`
`setApi`	`function`
`className`	`string`

Carousel.Content

Prop	Type	Default
`children`	`ReactNode`
`className`	`string`

Carousel.Item

Prop	Type	Default
`children`	`ReactNode`
`className`	`string`

Carousel.Previous

Prop	Type	Default
`variant`	`enum`	`"outline"`
`size`	`enum`	`"icon"`
`className`	`string`

Carousel.Next

Prop	Type	Default
`variant`	`enum`	`"outline"`
`size`	`enum`	`"icon"`
`className`	`string`

Card Checkbox