Carousel

Overview

Carousel is helm-native: it has no Navius primitive underneath, implementing its own drag/snap/loop behavior via a dedicated createCarousel JS engine (Navius.Primitives.Interop). ZitsCarousel owns the viewport ElementReference, the engine handle, keyboard navigation, and autoplay; the engine owns the DOM transform/transition and pointer handlers, calling back OnSelect / OnSettle / OnCanScrollChange. The root composes ZitsCarouselContent (viewport + track), ZitsCarouselItem (a slide), and ZitsCarouselPrevious / ZitsCarouselNext (which each compose ZitsButton).

Install

navius add carousel --to ./src/MyApp --namespace MyApp.Ui

Usage

@using Zits.Ui.Components

<ZitsCarousel Loop="true">
    <ZitsCarouselContent>
        <ZitsCarouselItem>Slide 1</ZitsCarouselItem>
        <ZitsCarouselItem>Slide 2</ZitsCarouselItem>
        <ZitsCarouselItem>Slide 3</ZitsCarouselItem>
    </ZitsCarouselContent>
    <ZitsCarouselPrevious />
    <ZitsCarouselNext />
</ZitsCarousel>

Parts and props

ChildContent and Attributes pass through unchanged on every part.

ZitsCarousel adds:

Prop	Type	Default	Description
Orientation	string	"horizontal"	horizontal or vertical; flips the track axis, drag direction, and arrow keys.
Loop	bool	false	When true, Previous/Next wrap instead of clamping.
Align	string	"start"	Snap alignment of the lead slide: start, center, end.
SlidesToScroll	int	1	How many slides advance per scroll, for multi-item viewports.
Autoplay	bool	false	Auto-advance on a timer, paused on hover/focus.
AutoplayInterval	int	4000	Autoplay cadence in milliseconds.

ZitsCarouselItem adds:

Prop	Type	Default	Description
Basis	string?	null	Optional flex-basis override (e.g. "md:basis-1/2") for multi-slide viewports; layers on top of the default basis-full.

ZitsCarouselContent, ZitsCarouselPrevious, and ZitsCarouselNext take no variant/size params of their own; Previous/Next forward their own Attributes merged with fixed positioning classes onto the composed ZitsButton.

Styling surface

Attributes on each part is merged with that part’s base class set via Cn.Class (Cn.Merge on Previous/Next, since they splat onto ZitsButton), with the caller’s classes applied last.

Parameter	Values
Orientation	horizontal · vertical
Align	start · center · end

Data attribute hooks

Carousel emits no data-* state hooks; scroll-availability state (CanScrollPrev / CanScrollNext) drives the composed ZitsButton’s Disabled prop directly rather than a data attribute.

Accessibility mechanism

The root carries role="region" and aria-roledescription="carousel", is tabindex="0", and handles ArrowLeft/ArrowRight (or ArrowUp/ArrowDown when vertical) to scroll. Each ZitsCarouselItem carries role="group" and aria-roledescription="slide". ZitsCarouselPrevious/ZitsCarouselNext set aria-label on the composed ZitsButton and disable it when the engine reports no more scroll room in that direction; autoplay pauses while the pointer is inside the viewport or the carousel has focus.