Spiral Media Gallery
A 3D vertical helix of media cards. The helix spins forever by drag, wheel, or arrow keys, with depth-based scale, opacity, and z-index written straight to the DOM from one requestAnimationFrame loop.
Installation#
pnpm dlx shadcn@latest add @davinciui/spiral-media-galleryUsage#
Wrap the gallery in a positioned container with height, or place it directly in a full-viewport page. Images repeat automatically, so five photographs are enough to fill the whole helix.
API Reference#
| Prop | Type | Default |
|---|---|---|
imagesImage sources arranged around the helix. Cards repeat the list automatically; five images fill the default 25-card spiral. | string[] | — |
cardCountNumber of cards in the helix. The angle step is 360 divided by this value. | number | 25 |
cardWidthCard width in pixels. | number | 220 |
cardHeightCard height in pixels. | number | 140 |
borderRadiusCard corner radius in pixels. | number | 16 |
cylinderRadiusHorizontal radius of the helix cylinder in pixels. | number | 230 |
verticalSpacingVertical distance between neighbouring cards. The full revolution pitch is verticalSpacing × cardCount. | number | 40 |
perspectiveCSS perspective applied to the stage in pixels. | number | 1000 |
minScaleScale applied to the card at the back of the cylinder. | number | 0.45 |
minOpacityOpacity applied to the card at the back of the cylinder. | number | 0.12 |
autoRotateAdvances the helix while idle. Automatically disabled under prefers-reduced-motion. | boolean | true |
autoRotateSpeedAutomatic movement in degrees per frame at 60fps. | number | 0.08 |
dragFrictionPer-frame velocity decay after a drag or wheel spin. | number | 0.94 |
wheelSpeedMultiplier applied to wheel input. | number | 0.08 |
showNumbersShows a small index label in each card corner. | boolean | false |
backgroundOverrides the theme-aware stage background. Leave unset to follow light and dark mode. | string | theme surface |
ariaLabelAccessible name for the gallery region. | string | "Spiral media gallery" |
imageAltsOptional alternative text announced through a screen-reader-only list. The visual stage itself is hidden from assistive technology. | string[] | — |
classNameAdditional classes for the root stage. | string | — |
Accessibility#
The root is a labelled region with aria-roledescription gallery. The 3D card stage is aria-hidden, and passing imageAlts adds a screen-reader-only list describing the source images. The region is focusable: ArrowUp and ArrowDown step one card, PageUp and PageDown step four, and Home resets. Drag and wheel are pointer-only, so the arrow keys provide an equivalent rotation path.
Motion#
One requestAnimationFrame loop writes transform, opacity, and z-index to the cards and nothing else. Drag and wheel feed a degrees-per-frame velocity that decays by dragFriction, while autoRotate adds autoRotateSpeed once the helix is idle. The loop pauses offscreen and on hidden tabs. prefers-reduced-motion is watched live and disables auto-rotation, though user-initiated drag, wheel, and arrow steps still rotate the helix.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

