Carousel

Build swipeable galleries on Embla. Compose the slides, then place previous and next controls beside the track or in a row below it.

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselItem,6  CarouselNext,7  CarouselPrevious,8} from "@/components/ui/carousel"910export function Example() {11  return (12    <Carousel className="w-full max-w-xs">13      <CarouselContent>14        {Array.from({ length: 5 }).map((_, index) => (15          <CarouselItem key={index}>16            <Card>17              <CardContent className="flex aspect-square items-center justify-center p-6">18                <span className="text-4xl font-normal tracking-wide">19                  {index + 1}20                </span>21              </CardContent>22            </Card>23          </CarouselItem>24        ))}25      </CarouselContent>26      <CarouselPrevious className="absolute -left-12 top-1/2 -translate-y-1/2" />27      <CarouselNext className="absolute -right-12 top-1/2 -translate-y-1/2" />28    </Carousel>29  )30}

Installation

npx @arctis-sh/@arctis-sh/ui@latest add carousel

Installs with Button and requires the embla-carousel-react peer dependency. The plugins example also uses embla-carousel-autoplay.

Usage

1import {2  Carousel,3  CarouselContent,4  CarouselItem,5  CarouselNext,6  CarouselPrevious,7} from "@/components/ui/carousel"

1<Carousel>2  <CarouselContent>3    <CarouselItem>...</CarouselItem>4    <CarouselItem>...</CarouselItem>5    <CarouselItem>...</CarouselItem>6  </CarouselContent>7  <CarouselPrevious className="absolute -left-12 top-1/2 -translate-y-1/2" />8  <CarouselNext className="absolute -right-12 top-1/2 -translate-y-1/2" />9</Carousel>

Composition

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

Controls

CarouselControls places previous and next controls below the track.

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselControls,6  CarouselItem,7} from "@/components/ui/carousel"89export function Example() {10  return (11    <Carousel className="w-full max-w-xs">12      <CarouselContent>13        {Array.from({ length: 5 }).map((_, index) => (14          <CarouselItem key={index}>15            <Card>16              <CardContent className="flex aspect-square items-center justify-center p-6">17                <span className="text-4xl font-normal tracking-wide">18                  {index + 1}19                </span>20              </CardContent>21            </Card>22          </CarouselItem>23        ))}24      </CarouselContent>25      <CarouselControls />26    </Carousel>27  )28}

Pass showStatus to display Slide N of M between them with CarouselStatus.

Slide 0 of 0

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselControls,6  CarouselItem,7} from "@/components/ui/carousel"89export function Example() {10  return (11    <Carousel className="w-full max-w-xs">12      <CarouselContent>13        {Array.from({ length: 5 }).map((_, index) => (14          <CarouselItem key={index}>15            <Card>16              <CardContent className="flex aspect-square items-center justify-center p-6">17                <span className="text-4xl font-normal tracking-wide">18                  {index + 1}19                </span>20              </CardContent>21            </Card>22          </CarouselItem>23        ))}24      </CarouselContent>25      <CarouselControls showStatus />26    </Carousel>27  )28}

Loop

Set opts.loop to continue smoothly from the last slide to the first.

Slide 0 of 0

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselControls,6  CarouselItem,7} from "@/components/ui/carousel"89export function Example() {10  return (11    <Carousel opts={{ loop: true }} className="w-full max-w-xs">12      <CarouselContent>13        {Array.from({ length: 5 }).map((_, index) => (14          <CarouselItem key={index}>15            <Card>16              <CardContent className="flex aspect-square items-center justify-center p-6">17                <span className="text-4xl font-normal tracking-wide">18                  {index + 1}19                </span>20              </CardContent>21            </Card>22          </CarouselItem>23        ))}24      </CarouselContent>25      <CarouselControls showStatus />26    </Carousel>27  )28}

Sizes

Set a basis on CarouselItem to change slide width. Use opts.align: "start" when the frame shows more than one slide.

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselControls,6  CarouselItem,7} from "@/components/ui/carousel"89export function Example() {10  return (11    <Carousel opts={{ align: "start" }} className="w-full max-w-sm">12      <CarouselContent>13        {Array.from({ length: 5 }).map((_, index) => (14          <CarouselItem key={index} className="basis-1/3">15            <Card>16              <CardContent className="flex aspect-square items-center justify-center p-4">17                <span className="text-2xl font-normal tracking-wide">18                  {index + 1}19                </span>20              </CardContent>21            </Card>22          </CarouselItem>23        ))}24      </CarouselContent>25      <CarouselControls />26    </Carousel>27  )28}

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

Spacing

Create space between slides with matching -ml-[VALUE] on CarouselContent and pl-[VALUE] on each CarouselItem.

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselControls,6  CarouselItem,7} from "@/components/ui/carousel"89export function Example() {10  return (11    <Carousel opts={{ align: "start" }} className="w-full max-w-sm">12      <CarouselContent className="-ml-8">13        {Array.from({ length: 5 }).map((_, index) => (14          <CarouselItem key={index} className="basis-1/2 pl-8">15            <Card>16              <CardContent className="flex aspect-square items-center justify-center p-4">17                <span className="text-2xl font-normal tracking-wide">18                  {index + 1}19                </span>20              </CardContent>21            </Card>22          </CarouselItem>23        ))}24      </CarouselContent>25      <CarouselControls />26    </Carousel>27  )28}

1<CarouselContent className="-ml-8">2  <CarouselItem className="basis-1/2 pl-8">...</CarouselItem>3</CarouselContent>

Orientation

Set orientation="vertical" for a vertical track. Give CarouselContent a fixed height and use basis-full to fill the frame with one slide.

tsx

1import { Card, CardContent } from "@/components/ui/card"2import {3  Carousel,4  CarouselContent,5  CarouselControls,6  CarouselItem,7} from "@/components/ui/carousel"89export function Example() {10  return (11    <Carousel12      opts={{ align: "start" }}13      orientation="vertical"14      className="w-full"15    >16      <CarouselContent className="h-[220px]">17        {Array.from({ length: 5 }).map((_, index) => (18          <CarouselItem key={index} className="basis-full pt-0">19            <Card className="h-full">20              <CardContent className="flex h-full items-center justify-center p-6">21                <span className="text-3xl font-normal tracking-wide">22                  {index + 1}23                </span>24              </CardContent>25            </Card>26          </CarouselItem>27        ))}28      </CarouselContent>29      <CarouselControls />30    </Carousel>31  )32}

Options

Pass Embla options directly through opts.

1<Carousel2  opts={{3    align: "start",4    loop: true,5  }}6>7  <CarouselContent>8    <CarouselItem>...</CarouselItem>9  </CarouselContent>10</Carousel>

API

Use setApi to keep the Embla API in state for slide indexes, counts, and custom controls.

Slide 0 of 0

tsx

1import { useEffect, useState } from "react"2import { Card, CardContent } from "@/components/ui/card"3import {4  Carousel,5  CarouselContent,6  CarouselControls,7  CarouselItem,8  type CarouselApi,9} from "@/components/ui/carousel"1011export function Example() {12  const [api, setApi] = useState<CarouselApi>()13  const [current, setCurrent] = useState(0)14  const [count, setCount] = useState(0)1516  useEffect(() => {17    if (!api) return1819    setCount(api.scrollSnapList().length)20    setCurrent(api.selectedScrollSnap() + 1)2122    api.on("select", () => {23      setCurrent(api.selectedScrollSnap() + 1)24    })25  }, [api])2627  return (28    <div className="w-full max-w-xs">29      <Carousel setApi={setApi}>30        <CarouselContent>31          {Array.from({ length: 5 }).map((_, index) => (32            <CarouselItem key={index}>33              <Card>34                <CardContent className="flex aspect-square items-center justify-center p-6">35                  <span className="text-4xl font-normal tracking-wide">36                    {index + 1}37                  </span>38                </CardContent>39              </Card>40            </CarouselItem>41          ))}42        </CarouselContent>43        <CarouselControls />44      </Carousel>45      <p className="mt-2 text-center text-sm text-muted-foreground">46        Slide {current} of {count}47      </p>48    </div>49  )50}

1import { useEffect, useState } from "react"2import { type CarouselApi } from "@/components/ui/carousel"34const [api, setApi] = useState<CarouselApi>()5const [current, setCurrent] = useState(0)6const [count, setCount] = useState(0)78useEffect(() => {9  if (!api) return1011  setCount(api.scrollSnapList().length)12  setCurrent(api.selectedScrollSnap() + 1)1314  api.on("select", () => {15    setCurrent(api.selectedScrollSnap() + 1)16  })17}, [api])1819return <Carousel setApi={setApi}>...</Carousel>

Events

Subscribe to events on the API returned through setApi. Embla documents the full event list.

1useEffect(() => {2  if (!api) return34  api.on("select", () => {5    // Do something on select.6  })7}, [api])

Plugins

Pass Embla plugins through the plugins prop.

tsx

1import Autoplay from "embla-carousel-autoplay"2import { Card, CardContent } from "@/components/ui/card"3import {4  Carousel,5  CarouselContent,6  CarouselControls,7  CarouselItem,8} from "@/components/ui/carousel"910export function Example() {11  return (12    <Carousel13      plugins={[14        Autoplay({15          delay: 2000,16        }),17      ]}18      className="w-full max-w-xs"19    >20      <CarouselContent>21        {Array.from({ length: 5 }).map((_, index) => (22          <CarouselItem key={index}>23            <Card>24              <CardContent className="flex aspect-square items-center justify-center p-6">25                <span className="text-4xl font-normal tracking-wide">26                  {index + 1}27                </span>28              </CardContent>29            </Card>30          </CarouselItem>31        ))}32      </CarouselContent>33      <CarouselControls />34    </Carousel>35  )36}

1import Autoplay from "embla-carousel-autoplay"23<Carousel4  plugins={[5    Autoplay({6      delay: 2000,7    }),8  ]}9>10  ...11</Carousel>

API Reference

The root container that provides carousel context to its children.

Prop	Type	Default
orientation	"horizontal" \| "vertical"	"horizontal"
opts	CarouselOptions	—
plugins	CarouselPlugin	—
setApi	(api: CarouselApi) => void	—
className	string	—

opts and plugins are Embla types from embla-carousel-react.

1<Carousel>2  <CarouselContent>3    <CarouselItem>Slide 1</CarouselItem>4  </CarouselContent>5  <CarouselPrevious />6  <CarouselNext />7</Carousel>

CarouselContent

Contains the viewport and slide track. Put horizontal spacing classes such as -ml-* here, or height classes for a vertical carousel.

Prop	Type	Default
className	string	—

1<CarouselContent>2  <CarouselItem>Slide 1</CarouselItem>3</CarouselContent>

CarouselItem

A single slide, full width by default with basis-full. Use another basis-* value for multi-slide layouts.

Prop	Type	Default
className	string	—

1<CarouselItem>Slide 1</CarouselItem>

CarouselPrevious

The previous control, built on Button. It disables when there is nowhere to scroll back.

Prop	Type	Default
variant	ButtonVariant	"outline"
size	ButtonSize	"icon-sm"
className	string	—

1<CarouselPrevious />

CarouselNext

The next control, built on Button. It disables when there is nowhere to scroll forward.

Prop	Type	Default
variant	ButtonVariant	"outline"
size	ButtonSize	"icon-sm"
className	string	—

1<CarouselNext />

CarouselControls

A bottom row for previous and next controls, with an optional status in the center.

Prop	Type	Default
showStatus	boolean	false
className	string	—

1<CarouselControls>2  <CarouselPrevious />3  <CarouselNext />4</CarouselControls>

CarouselStatus

Renders Slide N of M from the Embla API. It is usually enabled with CarouselControls showStatus.

Prop	Type	Default
className	string	—

1<CarouselStatus />

CarouselApi

Type alias for the Embla API returned by setApi. Use it for methods such as selectedScrollSnap, scrollSnapList, scrollNext, and scrollPrev, plus events such as select.

1const [api, setApi] = useState<CarouselApi>()23<Carousel setApi={setApi}>4  ...5</Carousel>