Carousel

A carousel with motion and swipe built using Embla.

<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Installation

pnpm dlx cubix@latest add carousel --base aria

About

The carousel is built with the Embla Carousel library.

Usage

Import

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

Example

<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Composition

Use the following composition to build a Carousel:

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

Examples

Sizes

Set slide width with basis on CarouselItem.

<Carousel>
  <CarouselContent>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
    <CarouselItem className="md:basis-1/2 lg:basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>

Spacing

Space slides with a negative margin on CarouselContent and matching padding on each item.

<Carousel>
  <CarouselContent className="-ml-1">
    <CarouselItem className="pl-1 md:basis-1/2">...</CarouselItem>
    <CarouselItem className="pl-1 md:basis-1/2">...</CarouselItem>
    <CarouselItem className="pl-1 md:basis-1/2">...</CarouselItem>
  </CarouselContent>
</Carousel>

Orientation

Use the orientation prop to set the scroll axis.

<Carousel
  orientation="vertical"
  opts={{ align: "start" }}
  className="w-full max-w-xs"
>
  <CarouselContent className="-mt-1 h-[200px]">
    <CarouselItem className="pt-1 md:basis-1/2">...</CarouselItem>
    <CarouselItem className="pt-1 md:basis-1/2">...</CarouselItem>
    <CarouselItem className="pt-1 md:basis-1/2">...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Options

Pass Embla options through the opts prop.

<Carousel
  opts={{
    align: "start",
    loop: true,
  }}
>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
</Carousel>

API

Use setApi to keep an Embla instance and read the current slide.

Slide 0 of 0

const [api, setApi] = React.useState<CarouselApi>()
const [current, setCurrent] = React.useState(0)
const [count, setCount] = React.useState(0)

React.useEffect(() => {
  if (!api) {
    return
  }

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

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

return (
  <Carousel setApi={setApi}>
    <CarouselContent>
      <CarouselItem>...</CarouselItem>
      <CarouselItem>...</CarouselItem>
      <CarouselItem>...</CarouselItem>
    </CarouselContent>
  </Carousel>
)

Plugins

Add Embla plugins with the plugins prop. Autoplay needs the extra embla-carousel-autoplay package.

import Autoplay from "embla-carousel-autoplay"

<Carousel
  plugins={[
    Autoplay({
      delay: 2000,
    }),
  ]}
>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
</Carousel>

API Reference

Note: See the Embla Carousel docs for the full list of options, events, and plugins.

Carousel

The root that provides the Embla instance to content and controls.

Prop	Type	Default	Description
orientation	"horizontal" \| "vertical"	"horizontal"	Scroll axis of the carousel.
opts	EmblaOptions	-	Embla options such as loop, align, and direction. See the Embla Carousel docs.
plugins	EmblaPlugin[]	-	Embla plugins such as Autoplay.
setApi	(api: CarouselApi) => void	-	Receive the Embla API instance for events and programmatic scroll.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

CarouselItem

A single slide. Use basis classes to show more than one item.

Prop	Type	Default	Description
className	string	-	Use basis utilities such as basis-1/2 or md:basis-1/3 to set slide width.

CarouselPrevious / CarouselNext

Previous and next buttons. They disable at the ends unless loop is on.

Prop	Type	Default	Description
variant	"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"	"outline"	Visual style of the previous or next button.
size	"default" \| "sm" \| "lg" \| "icon" \| "icon-sm" \| "icon-lg"	"icon-sm"	Size of the previous or next button.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).