Carousel

A carousel with motion and swipe, built on Embla. Supports horizontal and vertical orientation, keyboard navigation, and autoplay plugins.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/carousel.json

Usage

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

Examples

Default

One slide at a time, with arrows, swipe, and keyboard. opts={{ loop: true }} makes it cycle; leave it off and the arrows disable at each end instead.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Arrows in a title row

CarouselControls puts both arrows in a row, in normal flow, for a heading's action slot. Carousel must wrap the heading too, since the arrows read its context.

Collection

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Cards as slides

ringRoom keeps each card's ring and shadow clear of the clip, so the first and last cards keep their side edges. Slide widths and snap positions do not change.

Noun #301
From the collection.
Doodle #5064
From the collection.
CrypToadz #6500
From the collection.
CrypToadz #2391
From the collection.
Checks #122
From the collection.
DeadFellaz #9870
From the collection.

Multiple items

How many slides show at once is a basis-* class on CarouselItem, so it can change per breakpoint. The carousel itself needs no other change.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Dots

CarouselDots draws one dot per scroll position, each a named button that jumps there. It reads the carousel's context, so it renders inside Carousel; here it shares a row with CarouselControls under the slides.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Thumbnails

A synced filmstrip. The strip is its own bare Embla instance rather than a second Carousel: it needs no arrows, no keyboard capture and no region role of its own. dragFree lets it coast instead of snapping, which is what a row of small targets wants.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Coverflow scale

useCarouselTween (shipped with this component as carousel-tween.ts) scales and dims each slide by its live distance from centre, so it tracks a drag 1:1. edgeFade dissolves the peeking neighbours at the clip edge. Over long slides pair with opts.duration 18-25: the default 14 overshoots and double-bounces.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Vertical

orientation="vertical" stacks the slides and moves the arrows above and below. Give CarouselContent a bounded height through viewportClassName, not className: className lands on the track inside the viewport, where a height leaves every slide stacked.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Auto height

autoHeight sizes the viewport to the slide in view, so slides of different heights each get their own instead of all being stretched to the tallest. Horizontal only; a vertical carousel needs its height from CSS instead.

Checks #122
Doodle #5064
Noun #301
Not every slide is a picture
This one is text, so its height comes from how much of it there is. The viewport follows it rather than the other way round, which is the whole point of autoHeight: the carousel does not need to know what you are going to put in it.

Autoplay

Needs npm i embla-carousel-autoplay. The ring fills over the delay, so it answers how long until the next slide, not just whether you can stop it. It pauses on hover and focus, is reachable by keyboard and touch, and never starts under prefers-reduced-motion.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

Fade

Needs npm i embla-carousel-fade. Slides crossfade in place instead of moving, which suits a hero or a single-image showcase where travel would be noise. The gutter has to come off: fade stacks the slides, so the kit's 16px inset would offset every crossfade by 16px.

Noun #301
Doodle #5064
CrypToadz #6500
CrypToadz #2391
Checks #122
DeadFellaz #9870
DeadFellaz #8181
DeadFellaz #2948
DeadFellaz #3848
DeadFellaz #7136

API Reference

PropTypeDefaultDescription
optsCarouselOptionsNoneEmbla options object (loop, align, duration, ...). The kit defaults duration to 14, an Embla physics value (~10 to 60), not milliseconds.
pluginsCarouselPluginNoneEmbla plugins array, e.g. autoplay from embla-carousel-autoplay.
orientation"horizontal" | "vertical""horizontal"Scroll axis. Vertical stacks slides and moves the arrows above and below the viewport.
setApi(api: CarouselApi) => voidNoneReceives the Embla API instance for programmatic control (scrollTo, selectedScrollSnap, event listeners).
viewportClassNameCarouselContentstringNoneClasses for the clipping viewport rather than the flex track inside it. This is where a vertical carousel's height goes: className lands on the track, and a height there does not bound the element that clips, so every slide renders stacked. aspect-square derives the bound from the carousel's own width.
toneCarouselPrevious / CarouselNext"default" | "accent""default"Arrows are one style, a round button with a ring edge. default fills it with the card colour. accent uses Button's accent fill and hover, so it matches an accent button beside it.
placementCarouselPrevious / CarouselNext"overlay" | "inline""overlay"overlay floats the arrows on the track's edges, inside the slide while the carousel is narrower than 42rem and outside from there. inline puts them in normal flow, for a toolbar or a title row.
variant / toneCarouselControlsas on the arrowsNoneBoth arrows, inline, in a row at the bind rung (8px). Passes variant and tone to each arrow. Render it inside Carousel, most often as PageHeader's action.
classNameCarouselDotsstringNoneMerged onto the row of dots. -ms-2 lines the first dot up with the content edge.
ringRoomCarouselContentbooleanfalseRoom for slides whose edge paints outside their box, like a Card's ring and shadow, which the carousel otherwise clips. Grows the clip 12px on every side and takes it back with a negative margin, so slide widths, the first slide's edge and every snap position stay the same, and the next slide still does not peek. Turn it on whenever the slides are Cards.
edgeFadeCarouselContentboolean | numberfalseDissolves the slides at the viewport's edges instead of clipping them on a hard line. For peeking layouts (a fractional basis-*, a basis-auto strip, the coverflow tween), where the neighbour slide is otherwise guillotined at the clip edge. A mask rather than an overlay, so it works over any page background, and it follows orientation. A number sets the fade's width in pixels (true = 64); keep it comfortably inside the neighbour's visible peek or the whole neighbour smears. Each edge fades only while content extends past it, so at rest on the first slide the leading edge stays a hard line. A loop carousel keeps both edges faded.
autoHeightbooleanfalseSizes the viewport to the slide currently in view, so slides of different heights each get their own rather than all being stretched to the tallest. **Horizontal only**, and ignored when vertical: Embla measures its scroll bounds once at init, and on the y-axis the viewport height is itself the scroll axis, so sizing it afterwards leaves Embla thinking nothing can scroll. Give a vertical carousel a bounded height in CSS instead (aspect-square on CarouselContent). Costs a ResizeObserver over the slides, so it is opt-in.
optsCarouselOptionsEmbla options object (loop, align, duration, ...). The kit defaults duration to 14, an Embla physics value (~10 to 60), not milliseconds.
pluginsCarouselPluginEmbla plugins array, e.g. autoplay from embla-carousel-autoplay.
orientation"horizontal" | "vertical" = "horizontal"Scroll axis. Vertical stacks slides and moves the arrows above and below the viewport.
setApi(api: CarouselApi) => voidReceives the Embla API instance for programmatic control (scrollTo, selectedScrollSnap, event listeners).
viewportClassNameCarouselContentstringClasses for the clipping viewport rather than the flex track inside it. This is where a vertical carousel's height goes: className lands on the track, and a height there does not bound the element that clips, so every slide renders stacked. aspect-square derives the bound from the carousel's own width.
toneCarouselPrevious / CarouselNext"default" | "accent" = "default"Arrows are one style, a round button with a ring edge. default fills it with the card colour. accent uses Button's accent fill and hover, so it matches an accent button beside it.
placementCarouselPrevious / CarouselNext"overlay" | "inline" = "overlay"overlay floats the arrows on the track's edges, inside the slide while the carousel is narrower than 42rem and outside from there. inline puts them in normal flow, for a toolbar or a title row.
variant / toneCarouselControlsas on the arrowsBoth arrows, inline, in a row at the bind rung (8px). Passes variant and tone to each arrow. Render it inside Carousel, most often as PageHeader's action.
classNameCarouselDotsstringMerged onto the row of dots. -ms-2 lines the first dot up with the content edge.
ringRoomCarouselContentboolean = falseRoom for slides whose edge paints outside their box, like a Card's ring and shadow, which the carousel otherwise clips. Grows the clip 12px on every side and takes it back with a negative margin, so slide widths, the first slide's edge and every snap position stay the same, and the next slide still does not peek. Turn it on whenever the slides are Cards.
edgeFadeCarouselContentboolean | number = falseDissolves the slides at the viewport's edges instead of clipping them on a hard line. For peeking layouts (a fractional basis-*, a basis-auto strip, the coverflow tween), where the neighbour slide is otherwise guillotined at the clip edge. A mask rather than an overlay, so it works over any page background, and it follows orientation. A number sets the fade's width in pixels (true = 64); keep it comfortably inside the neighbour's visible peek or the whole neighbour smears. Each edge fades only while content extends past it, so at rest on the first slide the leading edge stays a hard line. A loop carousel keeps both edges faded.
autoHeightboolean = falseSizes the viewport to the slide currently in view, so slides of different heights each get their own rather than all being stretched to the tallest. **Horizontal only**, and ignored when vertical: Embla measures its scroll bounds once at init, and on the y-axis the viewport height is itself the scroll axis, so sizing it afterwards leaves Embla thinking nothing can scroll. Give a vertical carousel a bounded height in CSS instead (aspect-square on CarouselContent). Costs a ResizeObserver over the slides, so it is opt-in.