Carousel

A row of slides that scrolls by swipe, drag, arrow keys or buttons.

1
2
3
4
5
import * as stylex from "@stylexjs/stylex"
import { Card, CardContent } from "@/components/ui/card"
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"
import { leading, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  carousel: { width: "100%", maxWidth: width.narrow },
  slide: {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    aspectRatio: "1",
    fontSize: text.xl4,
    lineHeight: leading.xl4,
    fontWeight: 600,
  },
})

export default function CarouselDemo() {
  return (
    <Carousel xstyle={styles.carousel}>
      <CarouselContent>
        {[1, 2, 3, 4, 5].map((slide) => (
          <CarouselItem key={slide}>
            <Card>
              <CardContent xstyle={styles.slide}>{slide}</CardContent>
            </Card>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/carousel

Needs the arene setup first. Also adds Button.

Usage

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

Carousel is Embla Carousel with arene's parts around it. Embla handles dragging, swiping, snapping and looping. With focus inside the carousel, the arrow keys move between slides.

Composition

Carousel                  region; context, keyboard arrows
├── CarouselContent       viewport that clips, and the track inside it
│   └── CarouselItem      one slide
├── CarouselPrevious
└── CarouselNext

The arrows sit outside the slides, 3rem past the start and end edges, so leave room for them or place them yourself through xstyle.

Sizes

A slide is the full width of the carousel. Give CarouselItem a flexBasis through xstyle to show several at once. These are half width, and a third from the lg breakpoint. opts={{ align: "start" }} snaps each slide to the start edge.

1
2
3
4
5
6
7
8
import * as stylex from "@stylexjs/stylex"
import { Card, CardContent } from "@/components/ui/card"
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"
import { breakpoints } from "@/theme/breakpoints.stylex"
import { leading, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  carousel: { width: "100%", maxWidth: width.sm },
  item: { flexBasis: { default: "50%", [breakpoints.lg]: "33.333%" } },
  slide: {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    aspectRatio: "1",
    fontSize: text.xl2,
    lineHeight: leading.xl2,
    fontWeight: 600,
  },
})

export default function CarouselSize() {
  return (
    <Carousel opts={{ align: "start" }} xstyle={styles.carousel}>
      <CarouselContent>
        {[1, 2, 3, 4, 5, 6, 7, 8].map((slide) => (
          <CarouselItem key={slide} xstyle={styles.item}>
            <Card>
              <CardContent xstyle={styles.slide}>{slide}</CardContent>
            </Card>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}

Spacing

The gap between slides is --arene-carousel-gap, 1rem by default. Set it on the carousel through xstyle.

1
2
3
4
5
6
import * as stylex from "@stylexjs/stylex"
import { Card, CardContent } from "@/components/ui/card"
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"
import { leading, space, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  carousel: { width: "100%", maxWidth: width.sm, "--arene-carousel-gap": space.s1 },
  item: { flexBasis: "33.333%" },
  slide: {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    aspectRatio: "1",
    fontSize: text.xl2,
    lineHeight: leading.xl2,
    fontWeight: 600,
  },
})

export default function CarouselSpacing() {
  return (
    <Carousel opts={{ align: "start" }} xstyle={styles.carousel}>
      <CarouselContent>
        {[1, 2, 3, 4, 5, 6].map((slide) => (
          <CarouselItem key={slide} xstyle={styles.item}>
            <Card>
              <CardContent xstyle={styles.slide}>{slide}</CardContent>
            </Card>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}

Orientation

orientation="vertical" stacks the slides and scrolls them up and down. The track needs a height, and the arrows move above and below.

1
2
3
4
5
import * as stylex from "@stylexjs/stylex"
import { Card, CardContent } from "@/components/ui/card"
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"
import { leading, space, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  carousel: {
    width: "100%",
    maxWidth: width.narrow,
    marginBlock: space.s12,
  },
  content: { height: "12.5rem" },
  item: { flexBasis: "50%" },
  slide: {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    height: "100%",
    fontSize: text.xl2,
    lineHeight: leading.xl2,
    fontWeight: 600,
  },
  card: { height: "100%" },
})

export default function CarouselOrientation() {
  return (
    <Carousel orientation="vertical" opts={{ align: "start" }} xstyle={styles.carousel}>
      <CarouselContent xstyle={styles.content}>
        {[1, 2, 3, 4, 5].map((slide) => (
          <CarouselItem key={slide} xstyle={styles.item}>
            <Card xstyle={styles.card}>
              <CardContent xstyle={styles.slide}>{slide}</CardContent>
            </Card>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  )
}

API

setApi hands you the Embla instance once it exists. Subscribe to its events to show the current slide, or call scrollTo to jump to one.

1
2
3
4
5
Slide 1 of 5
"use client"

import { useEffect, useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Card, CardContent } from "@/components/ui/card"
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
  type CarouselApi,
} from "@/components/ui/carousel"
import { VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { leading, text, width } from "@/theme/tokens.stylex"

const slides = [1, 2, 3, 4, 5]

const styles = stylex.create({
  carousel: { width: "100%", maxWidth: width.narrow },
  slide: {
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
    aspectRatio: "1",
    fontSize: text.xl4,
    lineHeight: leading.xl4,
    fontWeight: 600,
  },
})

export default function CarouselApiDemo() {
  const [api, setApi] = useState<CarouselApi>()
  const [current, setCurrent] = useState(0)

  useEffect(() => {
    if (!api) return
    const update = () => setCurrent(api.selectedScrollSnap())
    update()
    api.on("select", update)
    return () => {
      api.off("select", update)
    }
  }, [api])

  return (
    <VStack gap={3} align="center" width="100%">
      <Carousel setApi={setApi} xstyle={styles.carousel}>
        <CarouselContent>
          {slides.map((slide) => (
            <CarouselItem key={slide}>
              <Card>
                <CardContent xstyle={styles.slide}>{slide}</CardContent>
              </Card>
            </CarouselItem>
          ))}
        </CarouselContent>
        <CarouselPrevious />
        <CarouselNext />
      </Carousel>
      <Text size="sm" tone="muted" aria-live="polite">
        Slide {current + 1} of {slides.length}
      </Text>
    </VStack>
  )
}

Options and plugins

opts takes Embla's options, except axis, which orientation sets. plugins takes Embla plugins, such as autoplay:

pnpm add embla-carousel-autoplay
import Autoplay from "embla-carousel-autoplay"

const autoplay = [Autoplay({ delay: 4000 })]

function Gallery() {
  return (
    <Carousel opts={{ loop: true }} plugins={autoplay}>
      …
    </Carousel>
  )
}

Keep plugins at module scope or in a useMemo. Embla compares them by their options, but creating a plugin on every render starts it again each time.

With reduced motion turned on, the buttons and arrow keys jump to the next slide instead of scrolling to it. Dragging still follows the pointer.

API reference

Pass render to replace Carousel, CarouselContent or CarouselItem with another element. Each part takes xstyle and className.

PropTypeDefault
orientation"horizontal" | "vertical""horizontal"
optsCarouselOptions—
pluginsReadonlyArray<CarouselPlugin>—
setApi(api: CarouselApi) => void—

It renders a role="region" with aria-roledescription="carousel". Give it an aria-label that says what the slides are.

CarouselContent

PropTypeDefault
viewportPropsComponentProps<"div"> & { xstyle?: StyleXStyles; className?: string }—

xstyle styles the track. viewportProps reaches the clipping viewport around it.

CarouselItem

A role="group" with aria-roledescription="slide". Its flexBasis sets how much of the carousel one slide fills.

CarouselPrevious, CarouselNext

Buttons, outline and icon-sm by default, with aria-label set. They disable themselves at the first and last slide unless opts.loop is on. Pass children to replace the arrow.

useCarousel

Returns api, orientation, canScrollPrev, canScrollNext, scrollPrev and scrollNext inside a Carousel, for building your own controls.

Data attributes

AttributeOnEffect
data-slot="carousel"the rootCarousel root
data-orientationthe rootWhich way it scrolls
data-slot="carousel-viewport"the viewportThe clipping viewport
data-slot="carousel-content"the trackThe track of slides
data-slot="carousel-item"a slideOne slide
data-slot="carousel-previous"a buttonPrevious button
data-slot="carousel-next"a buttonNext button