Carousel

Embla-powered carousel with aspect-ratio presets and horizontal or vertical slides.

Ship interfaces that feel polished from the first slide.

Motion, spacing, and type that stay in sync.

Drop in components—skip the layout guesswork.

Scroll stories without losing your rhythm.

Build faster. Keep the craft.

Installation

npx shadcn@latest add @iconiq/carousel

Props

Carousel

6 props

Root carousel region wired to Embla. Provides context for content, items, and navigation controls plus ArrowLeft and ArrowRight keyboard handling.

orientation"horizontal" | "vertical"

Defaulthorizontal

Sets the Embla scroll axis and the spacing applied between slides.

Defaultvideo

Sets the slide viewport shape on `CarouselContent`. Use presets like `video` (16:9) and `square`, or pass a custom ratio string such as `21/9`.

optsEmblaCarouselOptions

Forwarded Embla options such as `align`, `loop`, or `slidesToScroll`. The root merges `axis` from `orientation`.

pluginsEmblaCarouselPluginType[]

Optional Embla plugins passed to `useEmblaCarousel`.

setApi(api: CarouselApi) => void

Optional callback that receives the Embla API instance after mount for external index or dot indicators.

classNamestring

Optional class names merged onto the root `role="region"` wrapper.

Notes

Install path is `components/ui/carousel.tsx`. Exports include `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `useCarousel`, and `CarouselApi`.

Previous and next buttons are absolutely positioned outside the track (`-left-12` / `-right-12` horizontally). Leave horizontal padding in your preview or page layout so controls stay visible.

Requires the Iconiq `button` primitive (or your own `Button` at `@/components/ui/button`) for the navigation controls.

CarouselContent

1 prop

Overflow-hidden viewport that hosts the Embla ref and the flex track of slides.

classNamestring

Optional class names merged onto the inner flex container that holds slides.

CarouselItem

1 prop

Single slide wrapper sized to `basis-full` with directional padding between siblings.

classNamestring

Optional class names merged onto each slide group.

CarouselPrevious / CarouselNext

3 props

Outline icon buttons that call `scrollPrev` and `scrollNext` and disable when Embla cannot scroll further.

variantButton variant

Defaultoutline

Forwarded to the underlying `Button` component.

sizeButton size

Defaulticon

Forwarded to the underlying `Button` component.

classNamestring

Optional class names merged onto the control for local offsets or sizing.