Carousel

A clipped viewport holds a flex track whose children are the slides. The root writes --carousel-item-size and --carousel-offset as inline styles: the first is the exact slide width for the current slidesPerView, the second multiplies that width plus one gap by the active index and adds any live drag distance. Percentages in both resolve against the track, whose main-axis size equals the viewport's, so the two expressions can never disagree about where a slide begins.

slidesPerView sets how many slides sit at one rest position. The maximum index becomes slideCount - slidesPerView, so a six-slide carousel three at a time has four rest positions rather than six, and the dots, the counter, and the progress bar all follow that number. Every slide inside the active window is marked data-active, so peeking layouts can style the visible group rather than a single slide.

orientation="vertical" turns the track into a column, translates on the block axis, stacks the dots, moves inside arrows to the top and bottom edges, and rebinds the keyboard to ArrowUp and ArrowDown. A column's percentage slide sizes resolve against height, which needs a definite value, so the vertical viewport ships a default height through --zui-carousel-vertical-height that a token or a className can replace.

Dragging uses pointer events on the viewport, so it works for mouse, touch, and pen without a motion library. dragThreshold is a fraction of one slide step and defaults to 0.2; travel beyond it commits, and a longer flick commits proportionally more steps. While a drag is in flight the track drops its CSS transition and carries data-dragging, and at a non-looping boundary the offset is damped so the end of the list is felt rather than crossed.

autoPlay advances on a timer set by autoPlayInterval, wrapping at the end so the rotation continues past the last slide. pauseOnHover and pauseOnFocus are on by default, a drag suspends the timer, and prefers-reduced-motion suppresses it entirely. Auto-play is a convenience, not a substitute for controls: the arrows, dots, and keyboard all stay live while it runs, which is what satisfies the pause requirement for moving content.

Use the shorthand and pass slides as children, or compose Carousel.Root, Carousel.Viewport, Carousel.Content, Carousel.Item, Carousel.Controls, Carousel.Previous, Carousel.Next, Carousel.Dots, Carousel.Counter, and Carousel.Progress. The root owns index state, geometry, keyboard handling, and the drag gesture; Carousel.Content counts its children and hands each one its position, so items never take an index prop. Pass slideCount on the root when slides live outside a Carousel.Content, or to keep the dots correct on the first server render.

The animated entry keeps placement in CSS and springs only the slide index, writing --carousel-motion-index and --carousel-motion-drag for the browser to fold into the shared calc(). That keeps static and animated tracks pixel-identical at rest while letting a spring overshoot on the way. animation selects the physics preset and reveal fades, scales, or blurs slides outside the active window; both collapse to no motion under prefers-reduced-motion.

Tab to the viewport, then use ArrowLeft and ArrowRight (ArrowUp and ArrowDown when vertical) to step, PageUp and PageDown to do the same, and Home and End to jump to the first and last rest position. The arrows and dots are ordinary buttons, so they are reachable in sequence, and focusing anything inside a clipped slide brings that slide into view first.

The root is a region with aria-roledescription="carousel" and a default accessible name that a caller-supplied aria-label or aria-labelledby replaces. Each slide is a group with aria-roledescription="slide" and an "n of total" label, and slides outside the active window are aria-hidden. The track announces user-driven moves politely and goes silent while auto-rotating. Arrows carry Previous slide and Next slide names and disable at the ends, dots expose aria-current, and the progress bar is a named progressbar with real min, max, and now values.