npm i @velkin/react
import { VuCarousel } from "@velkin/react/carousel";Tables match the member selected under Import.
| Prop | Type | Default | Description |
|---|---|---|---|
| index | number | 0 | Active slide index (zero-based). Reflected so consumers can drive it from outside via `index` attribute. |
| slidesPerView | number | 1 | How many slides are visible at once. |
| slidesToScroll | number | 1 | How many slides advance per `next()` / `prev()` / dot click. |
| loop | boolean | false | Wraps around at the end / start instead of stopping. When `false` (default), navigation stops at the edges and arrow buttons get `disabled`. |
| autoplay | boolean | false | Auto-rotates through slides. Off by default — auto-rotation is hostile UX without an explicit ask. Respects `prefers-reduced-motion: reduce` (treated as off). |
| interval | number | 5000 | Milliseconds between autoplay advances. |
| pauseOnHover | boolean | true | Pause autoplay while the pointer is over the carousel. Focus-within always pauses regardless of this flag (a11y requirement). |
| controls | VuCarouselControls | "dots" | Which navigation affordances render. |
| gap | VuCarouselGap | "none" | Gap between slides. |
| orientation | VuCarouselOrientation | "horizontal" | Layout axis. `vertical` requires a host `block-size` so the viewport has something to clip against. |
| label | string | "" | Accessible name for the carousel — required by the WAI-ARIA carousel pattern (the screen reader needs to know the *purpose* of the carousel). |
| prevLabel | string | "" | Previous control name; empty uses the locale catalog. |
| nextLabel | string | "" | Next control name; empty uses the locale catalog. |
| dotsLabel | string | "" | Dot tablist name; empty uses the locale catalog. |
| loading | boolean | false | Show a loading overlay (spinner + dimmed surface) and mark the host `aria-busy`. |
| Event | Detail | Description |
|---|---|---|
| vu-change | VuCarouselChangeDetail | Active slide index changed (API, click, drag, keyboard, or autoplay). |
| Slot | Description |
|---|---|
| — | - Default slot for `<vu-carousel-item>` slides. The parent relays slide ARIA (`role="group"`, roledescription, "N of M" / item `label`, `inert` / `aria-hidden` when offscreen). |
| prev-icon | Optional override for the previous-arrow icon. Defaults to a chevron. |
| next-icon | Optional override for the next-arrow icon. Defaults to a chevron. |
| Part | Description |
|---|---|
| base | Outer wrapper containing viewport and controls. |
| viewport | The clipping container; slides translate within this. |
| track | The flex container that translates by `--carousel-index`. |
| prev | The previous-slide button. |
| next | The next-slide button. |
| dots | The container for dot indicators. |
| dot | Each dot indicator (a real `<button>`). |
| dot-active | Added to the active dot (for `::part(dot-active)` styling). |
| live | The visually-hidden live region announcing the current slide. |
| loading | The loading overlay shown when `loading` is true. |
| spinner | The spinner inside the loading overlay. |
| Name | Definition |
|---|---|
| VuCarouselChangeDetail | |
| VuCarouselControls | |
| VuCarouselGap | |
| VuCarouselOrientation | |