Infinite Image Gallery
A continuously rotating cylinder of images built entirely with CSS 3D transforms. Rows of rounded tiles share one curved surface, with adjustable speed, direction, radius, and density — and a static arrangement when reduced motion is requested.
Installation#
pnpm dlx shadcn@latest add @davinciui/infinite-image-galleryUsage#
The gallery repeats your images around the cylinder automatically, so the loop never resets. Use portrait sources for the intended rhythm; wide images are cropped by the default imageFit="cover" treatment.
API Reference#
| Prop | Type | Default |
|---|---|---|
imagesImages repeated around the cylinder. Each item has a src and optional alt. | InfiniteImageGalleryImage[] | — |
speedRotation speed in degrees per second. The default completes one revolution in 40 seconds. | number | 9 |
directionDirection the tiles travel across the front of the cylinder. | "left" | "right" | "left" |
radiusCylinder radius in pixels. Defaults to half the stage width so the curved surface fills the frame. | number | auto |
perspectiveCSS perspective distance in pixels. Defaults to 3.5 × radius for a pronounced but controlled curve. | number | auto |
gapBase gap between tiles in pixels. Defaults to 14% of the computed tile width. | number | auto |
borderRadiusBase corner radius applied to every tile. | number | 18 |
imageFitObject-fit treatment for the images. Cover preserves the tile rhythm; contain letterboxes them. | React.CSSProperties["objectFit"] | "cover" |
autoplayStart the rotation automatically. Reduced motion, keyboard pause, and offscreen visibility still stop it. | boolean | true |
showControlsRender the keyboard pause/play control. Disable it for decorative card previews or nested interactive surfaces. | boolean | true |
rowsNumber of rows wrapped around the cylinder, from 1 to 6. Tall portrait stages default to 5 rows to keep the wall dense. | number | 3 or 5 |
columnsNumber of columns around the cylinder. Derived from radius and tile width by default. | number | auto |
tiltCamera tilt in degrees. Negative values raise the far edge of the cylinder. | number | -8 |
aria-labelAccessible name for the gallery region. | string | "Infinite 3D image gallery" |
classNameAdditional classes for the root. Give the gallery a height context or use the built-in minimum. | string | — |
Accessibility#
The root is a labelled region with a visually hidden description of the loop. The rotating cylinder is aria-hidden because the same images repeat around the surface, so image alt text is not announced dozens of times. A Pause/Play button becomes visible on keyboard focus, and motion stops automatically when reduced motion is requested.
Motion#
One requestAnimationFrame loop advances a single rotor rotation by speed degrees per second; React never re-renders per frame. Only the rotor transform changes, with backface-hidden tiles on a preserve-3d cylinder. The loop stops offscreen, while paused, and whenever prefers-reduced-motion matches, leaving the static arrangement intact.
Known constraints#
- The root fills its parent and falls back to a 480px minimum height, so the stage needs an explicit height context when embedding it in a compact card.
- Tile size, radius, and column count are recomputed from the container size; the reference composition is 1440×900.
- Columns are derived from radius and tile width by default, so a very small radius widens the gaps instead of shrinking the tiles.
- Tiles use object-fit cover by default, so non-portrait sources crop rather than letterbox.
- The default density renders roughly 60–90 image nodes, and tall portrait stages add rows automatically. Pass rows or columns to control the count when mounting several galleries on one page.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

