When to use it

Use Carousel when content should scroll horizontally with swipe and arrow controls. It fits product image galleries, recommendation rails, testimonial sliders, editorial highlights, and any horizontal browsing pattern where showing one or a few items at a time is more engaging than a full grid.

If the content should all be visible at once (like a responsive product grid), do not wrap it in a carousel. Carousels work best when the hidden content builds anticipation or when horizontal space is limited.

Slot strategy

Carousel is built on Embla Carousel with four visible pieces:

• Carousel is the root container. It accepts opts for Embla configuration (alignment, loop, drag behavior), orientation for horizontal or vertical scrolling, and wheelAxis to control scroll/trackpad behavior.
• CarouselContent is the scrollable track that holds the slides.
• CarouselItem wraps each slide. Control how many slides are visible at once with basis-* classes (e.g. basis-1/2 for two-up, basis-1/3 for three-up).
• CarouselPrevious and CarouselNext are arrow buttons positioned at the edges of the carousel.

Behavior and theming guidance

The carousel supports touch swipe, mouse drag, and keyboard navigation out of the box. Arrow buttons disable automatically when the carousel reaches the first or last slide (unless loop: true is set in opts).

Use wheelAxis to control scroll behavior. The default "vertical" lets the page scroll normally on vertical swipes. Set "horizontal" to enable horizontal trackpad swiping, or "both" to capture vertical scroll for the carousel (use sparingly, as it can interfere with page scrolling).

Pass Embla options through the opts prop for advanced behavior like align: "start" (left-align slides instead of centering), loop: true (infinite cycling), or dragFree: true (momentum-based scrolling without snap points).

For product galleries where you need programmatic control (jump to a specific slide, listen to scroll events), use the setApi callback to capture the Embla API instance.