Wavy Flow Carousel
An infinite horizontal ribbon of portrait media that follows your theme background. Slides rise and grow taller on the crests, sink and shrink on the troughs, auto-scroll, drag with momentum, and loop seamlessly.
Installation#
pnpm dlx shadcn@latest add @davinciui/wavy-flow-carouselUsage#
API Reference#
| Prop | Type | Default |
|---|---|---|
slidesMedia rows in play order. Each slide takes a src and an optional type — an image, or a muted looping video. Defaults to the built-in six-portrait composition. | WavyFlowCarouselSlide[] | — |
slideWidthSlide width as a fraction of the container height. | number | 0.407 |
slideHeightSlide height at the wave midline, as a fraction of the container height. | number | 0.5 |
spacingGap between slides in px (pitch is slideWidth + spacing). | number | 0 |
waveStretchVertical scale swing applied by the wave at crest and trough. | number | 0.25 |
waveHeightVertical centre swing of the ribbon as a fraction of the container height. | number | 0.15 |
waveFrequencyWave frequency per container height — λ = H / waveFrequency. | number | 1 / 3.86 |
wavePhaseWave phase in radians at offset 0. | number | 1.2 |
autoRotateAuto-advance the strip at constant speed. | boolean | true |
speedAuto-scroll speed in container heights per second. | number | 0.149 |
directionDirection the strip travels. | "left" | "right" | "left" |
pauseOnHoverEase auto-scroll to a stop while the pointer is over the canvas. | boolean | false |
dragEnabledDrag the strip 1:1 with the pointer. | boolean | true |
momentumKeep release velocity with ~0.95 per-frame friction at 60fps. | boolean | true |
wheelEnabledWheel and horizontal trackpad deltas move the strip. | boolean | true |
backgroundStage background. Defaults to your theme's background token. | string | "var(--background, #ffffff)" |
fitTexture fit inside each slide. | "cover" | "contain" | "cover" |
Accessibility#
A decorative, canvas-rendered stage: the ribbon and its imagery are not exposed as interactive content and add no focusable elements. The wheel moves the ribbon only while the pointer is over it, prefers-reduced-motion stops the auto-scroll, and the stage stays in place while the page scrolls normally. Videos, when used, are muted and play inline without controls.
Motion#
A single requestAnimationFrame loop advances the offset at a constant speed; the wave phase is a spring follower of that offset, so the ribbon trails the auto-scroll softly. Dragging maps 1:1, release keeps momentum with per-frame friction, and wheel input is smoothed. prefers-reduced-motion stops the auto-scroll; the loop and videos pause off-screen or when the tab is hidden.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

