Carousel

Carousel: scroll snap, swipe, autoplay, thumbnails. Free, MIT · Data and metrics › Cards

Scroll-snap carousel: swipe or drag, arrows, dots or thumbnails, several slides per view and optional autoplay with a rotation control (WAI-ARIA APG carousel pattern).

Installation

npx valyro-cli@latest add carousel

npx shadcn@latest add https://valyro.xyz/r/carousel.json

npm install valyro-ui

import 'valyro-ui/styles.css';
import { Carousel } from 'valyro-ui';

Props

Prop	Type	Default
`children` *	`ReactNode`		One child per slide: any element, or `Carousel.Slide` for a slide with its own thumbnail or name.
`slidesPerView`	`SlidesPerView`	`1`	Slides visible at once: a number (fractions peek at the next slide) or `{ minWidth: count }` by carousel width.
`gap`	`number`	`16`	Space between slides in px (default 16).
`index`	`number`		Index of the first visible slide (controlled).
`defaultIndex`	`number`	`0`	Initial `index` when uncontrolled.
`onIndexChange`	`(index: number) => void`		Called with the new `index` when it changes.
`loop`	`boolean`	`false`	Previous/next wrap around at the ends.
`autoplay`	`boolean \| number`	`false`	Advance automatically: `true` (every 5 s) or an interval in ms. Pauses on hover and focus, and stays off when the user prefers reduced motion until they press play.
`showArrows`	`boolean \| 'always'`	`true`	Previous / next buttons over the slides (default true). With a mouse they appear on hover or keyboard focus (touch screens always show them); `'always'` keeps them visible at rest too.
`align`	`'start' \| 'center'`	`'start'`	Where the current slide rests: `start` (default) or `center`, with the neighbours peeking on both sides and fading out at the edges. With `center` every slide is a snap position.
`indicators`	`'dots' \| 'thumbnails' \| 'none'`	`'dots'`	Dots, a thumbnail strip (with `renderThumbnail` or each `Carousel.Slide`'s `thumbnail`), or nothing (default dots).
`renderThumbnail`	`(index: number) => ReactNode`		Content of the thumbnail button for the slide at `index`; required for `indicators="thumbnails"` without `Carousel.Slide` thumbnails.
`animation`	`'default' \| 'spring'`	`'default'`	`spring`: the current slide stands out — the others shrink, dim and stay inert on a spring — and the active dot stretches into a pill with a bounce. Pairs well with a fractional `slidesPerView` (1.3) that shows the neighbours. `default`: plain slides.
`labels`	`Partial<CarouselLabels>`		Overrides for the built-in English text; keys left out keep their defaults.

Compound parts

Carousel.Slide (CarouselSlide)

Related components

Card — All-purpose cards
Item Card — Row card: icon, title, description and a control on the right
Record Card — Record card: status, context, key fields and actions
Empty State — No-data screen
Data Table — Tables with search and sorting
Data Grid — Grid for 100,000 rows: grouping, filters, inline editing
Virtual List — Virtual list for 100,000 rows
Bulk Action Bar — Actions for selected rows, with keyboard shortcuts
List Block — List with images or icons, descriptions and values
Description List — Key–value list: stacked, inline or a grid with icons
Tree View — Tree structures
Accordion — Collapsible sections

Previous: Record Card · Next: Empty State · All Data and metrics