Skip to content

Now in the official shadcn registry directory.

Start free

Carousel

A swipeable slider on embla-carousel-react - horizontal or vertical, keyboard and drag support, basis-driven multi-slide views and prev/next controls from the ai2 Button.

displaylayout
A free styled version is available
1
2
3
4
5

Installation

Run the following command

npx shadcn@latest add @ai2/carousel

Dependencies including embla-carousel-react, the @ai2/tokens theme and the component file install together. The @ai2/button component installs alongside - the prev/next controls reuse it.

Usage

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

<Carousel className="w-full max-w-xs">
  <CarouselContent>
    {items.map((item) => (
      <CarouselItem key={item.id}>{item.label}</CarouselItem>
    ))}
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Wrap each slide in a CarouselItem inside CarouselContent, then drop in CarouselPrevious and CarouselNext. Set a basis on the item to show more than one slide at a time.

Examples

Basic

1
2
3
4
5

Multiple slides per view

Set a basis on each item to fit several slides at once.

1
2
3
4
5
6

Vertical

1
2
3
4
5

Props

The controls also forward the ai2 Button props, and CarouselContent and CarouselItem forward the standard div props - set the slide count with the basis utility on CarouselItem.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""horizontal"Scroll axis. Sets the embla axis and switches the prev/next controls between left/right and up/down placement.
optsCarouselOptionsundefinedOptions passed straight to embla, for example { align: "start" } or { loop: true }.
pluginsCarouselPluginundefinedEmbla plugins such as autoplay. Accepts the array embla-carousel-react expects.
setApi(api: CarouselApi) => voidundefinedReceives the embla api once ready, so you can read the selected index or drive the carousel from outside.
PropTypeDefaultDescription
classNamestringundefinedSet the basis here to show more than one slide at a time (for example basis-1/3 for three across). Defaults to basis-full, one slide per view.

ai2 Carousel: swipeable slider for React, embla under the hood

The ai2 Carousel is a shadcn-compatible slider for React, built on embla-carousel-react and styled with Tailwind CSS v4. It scrolls through a row or column of slides with drag, arrow keys and prev/next buttons, and shows one slide or several at a time depending on the basis you set.

Because it ships through the shadcn registry format, you install it with one CLI command, an MCP agent, or a copy-paste, and the source lands in your own project. You own the file; there is no runtime dependency on ai2 itself. The live example above is the exact component you get.

What is the ai2 Carousel?

It is a five-part composition: Carousel, CarouselContent, CarouselItem, CarouselPrevious and CarouselNext. The anatomy matches shadcn/ui exactly, so existing snippets and AI agents keep working without changes.

Each CarouselItem is basis-full by default, so one slide fills the view; set a basis such as basis-1/3 to show several at once. Orientation flips the axis to vertical, opts forwards embla options like align and loop, and plugins accepts embla plugins such as autoplay. The prev and next controls are built from the ai2 Button and disable themselves at the ends.

Why use it

  • Real embla engine: embla-carousel-react handles drag physics, snapping and momentum, so slides feel natural on touch and mouse without custom scroll math.
  • One or many slides: CarouselItem is basis-full by default; set basis-1/2, basis-1/3 and so on to show multiple slides per view from the same markup.
  • Keyboard and buttons: Arrow keys move the carousel while it is focused, and the prev/next buttons scroll and disable themselves at the first and last slide.
  • Horizontal or vertical: Flip orientation to vertical and the axis, content stacking and control placement all follow, no other changes needed.
  • Agent-readable metadata: The registry item describes its parts and intended use in plain words, so an MCP agent can find, inspect and install it without guessing.

Features

  • shadcn registry install: One command adds the component, embla-carousel-react, the @ai2/button dependency and the @ai2/tokens theme to your project.
  • Basis-driven layout: Slide count per view is pure CSS: set the basis on CarouselItem and the carousel snaps to match, so multi-item views need no config.
  • Embla options and plugins: opts forwards align, loop, dragFree and the rest of embla's options, and plugins accepts autoplay or any other embla plugin.
  • External api access: setApi hands you the embla api once mounted, so you can read the selected index, build dot indicators or scroll programmatically.
  • Buttons from ai2 Button: CarouselPrevious and CarouselNext render the ai2 Button as icon buttons, so they inherit your variants, focus ring and tokens.
  • Data attributes for styling: Every part exposes data-slot, so you can restyle the track, slides or controls from CSS without forking the component.

Production tips

  • Set basis for multi-slide views: Leave CarouselItem at basis-full for a one-at-a-time slider, or set basis-1/2 or basis-1/3 to fit two or three slides per view.
  • Use align: start with multi-item: When showing several slides, pass opts={{ align: "start" }} so the row lines up on the left edge instead of centering the active slide.
  • Give vertical carousels a height: A vertical carousel needs a fixed height on CarouselContent (for example h-64) so embla knows how far it can scroll.
  • Leave room for the controls: Prev and next sit just outside the track, so keep some horizontal (or vertical) padding around the carousel or the buttons get clipped.
  • Reach for autoplay via plugins: Do not roll your own timer. Add the embla autoplay plugin through the plugins prop so it pauses on interaction and stays in sync.

Works with the rest of ai2

Carousels frame collections across the registry. Wrap each slide in a ai2 Card for framed content, and the prev/next controls are the ai2 Button under the hood, so they inherit your variants and tokens.

Pair it with a ai2 Badge to tag slides, or an ai2 Avatar row inside a testimonial slide. Everything shares one token source, so combinations stay visually consistent in both modes.

FAQs

Get new components in your inbox

Component drops, new themes and release notes. No spam, and you can unsubscribe from any email.

© 2026 ai2 design system · MIT licensed · Built with its own components