Carousel

Embla-backed carousel that shares scroll state and controls with its parts (CarouselContent, CarouselPrevious/Next, CarouselDots) via context - they must render inside it.

Terracotta

Sage

Sand

Slate

Usage

import { Carousel, CarouselApi, CarouselContent, CarouselContentProps, CarouselDots, CarouselDotsProps, CarouselItem, CarouselItemProps, CarouselNext, CarouselNextProps, CarouselPrevious, CarouselPreviousProps, CarouselProps, useCarousel } from "@instruments/materia-ui/components/carousel";

Best practices

Render CarouselContent/CarouselItem/CarouselPrevious/CarouselNext/CarouselDots only inside Carousel - they read scroll state from context and throw ("must be used within a Carousel") outside it.
Set slidesToShow to show multiple items at once (it drives each item's flex-basis); don't fake a multi-item view with CSS widths on CarouselItem.
Tune scroll behaviour via opts (Embla options like loop/align) and enable wheelScroll/freeScroll deliberately - free-scroll drops snap points, so pass slideCount if the dots miscount.
Give a descriptive aria-label when the region isn't self-evidently "Carousel" (e.g. "Product images").

Props

Prop	Type	Default	Description
aria-label	`string`	`"Carousel"`	Accessible name for the carousel region.
children	`import("react").ReactNode`
className	`string`
freeScroll	`boolean`		Enable free-scroll mode without snap points (useful for mobile galleries)
opts	`Partial<import("embla-carousel/esm/components/Options").OptionsType> \| undefined`		Embla options passed through to the underlying carousel.
orientation	`Orientation`	`"horizontal"`	Scroll axis.
plugins	`import("embla-carousel").CreatePluginType<import("embla-carousel/esm/components/Plugins").LoosePluginType, {}>[] \| undefined`		Embla plugins passed through to the underlying carousel.
slideCount	`number`		Explicit slide count for dots - use when Embla miscounts due to custom slide sizing
slidesToShow	`number`	`1`	Slides visible at once; drives each item's flex-basis.
wheelScroll	`boolean`		Enable mousewheel/trackpad scroll navigation (default: false)

Also exports

typeCarouselApi
componentCarouselContent
typeCarouselContentProps
componentCarouselDots
typeCarouselDotsProps
componentCarouselItem
typeCarouselItemProps
componentCarouselNext
typeCarouselNextProps
componentCarouselPrevious
typeCarouselPreviousProps
interfaceCarouselProps
constuseCarousel

Composition

Builds on

Button, Flex