iconiq
—Open GitHub

Carousel

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

Installation

Props

Carousel

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

orientation"horizontal" | "vertical"

Default horizontal

Sets the Embla scroll axis and the spacing applied between slides.
aspectRatio"square" | "video" | "4/3" | "3/2" | "portrait" | string

Default video

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.

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

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

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

classNamestring
Optional class names merged onto each slide group.

CarouselPrevious / CarouselNext

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

variantButton variant

Default outline

Forwarded to the underlying `Button` component.
sizeButton size

Default icon

Forwarded to the underlying `Button` component.
classNamestring
Optional class names merged onto the control for local offsets or sizing.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: embla-carousel-react, lucide-react.