DomeGallery
dome-galleryArranges images across a draggable CSS 3D dome with inertial rotation, click-to-zoom viewing, and reduced-motion behavior.
Usage
Basic usage
When not transmitting images, the built-in placeholder gradient tiles can be used to rotate the spherical surface by dragging it and click to open it for a larger view.
<div className="relative h-80 overflow-hidden rounded-xl bg-bg">
<DomeGallery />
</div>Automatic rotation
autoRotate allows the sphere to rotate slowly without dragging, suitable for wallpaper/display scenes.
<DomeGallery autoRotate />Colored tiles
grayscale={false} Turn off the grayscale filter, and the tiles directly display the original color.
<DomeGallery grayscale={false} segments={20} />High Density Spherical Surface
segments increases the number of meridional segments, making the tiles denser and the cells smaller; fit adjusts the spherical curvature.
<DomeGallery segments={32} fit={0.55} />When to use
Use DomeGallery for an immersive gallery that maps images to the inside of a 3D hemisphere, rotates by dragging, and opens images for closer viewing—for example, a brand mood wall or portfolio hero. For a curved horizontal track with wheel scrolling and seamless looping, use CircularGallery. For a card wall revealed by a cursor spotlight, use ChromaGrid. For structured tabular data, use Table. The component uses CSS 3D and native Pointer Events with no external runtime dependency.
Import
import { DomeGallery } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| images | DomeGalleryImage[] | Built-in gradient placeholder tiles | Images mapped to the dome, provided as strings or { src, alt } objects. A short list repeats to fill the available tiles; surplus images are not displayed. |
| segments | number | 24 | Number of longitudinal dome segments. Larger values produce denser, smaller tiles. |
| fit | number | 0.5 | Dome radius relative to the container. Smaller values increase curvature, subject to minRadius and maxRadius. |
| minRadius | number | 380 | Minimum radius in pixels, preventing the dome from collapsing in small containers. |
| maxRadius | number | 1600 | Maximum radius in pixels, preventing the dome from appearing too flat on large screens. |
| maxVerticalRotationDeg | number | 6 | Maximum vertical rotateX angle, limiting vertical rotation so the poles do not come into view. |
| dragSensitivity | number | 18 | Drag sensitivity: pixel movement divided by this value becomes the rotation angle. Larger values feel less sensitive. |
| dragDampening | number | 0.55 | Post-release inertial dampening from 0 to 1. Larger values glide longer. |
| grayscale | boolean | true | Whether tiles use a grayscale filter. Enlarged images return to full color. |
| imageBorderRadius | string | "16px" | Tile border radius as a CSS length. |
| openedImageBorderRadius | string | "24px" | Image border radius in the enlarged view. |
| overlayColor | string | "var(--color-background)" | Base color for the edge fade and center mask. Pass a token matching the host background. |
| enlargeTransitionMs | number | 320 | Duration in milliseconds for enlarged-view and auto-rotation transitions. |
| autoRotate | boolean | false | Slowly rotates the dome when it is not being dragged, suitable for displays and ambient backgrounds. |
| className | string | — | Class name forwarded to the root element. |
| style | CSSProperties | — | Inline styles forwarded to the root element. |
DomeGalleryImage is either a string or { src: string; alt?: string }.
Usage notes
- Place DomeGallery in a host with an explicit height and
overflow-hidden.minRadiusprevents the dome from collapsing in small containers. - Match
overlayColorto the host background. The default isvar(--color-background); a mismatch exposes a visible seam around the edge fade. - A short
imageslist repeats to fill all tiles, while items beyond the available tile count are ignored. Estimate the tile count fromsegmentsbefore preparing assets. - Inertial movement and auto-rotation are reduced when the user prefers reduced motion.
Related
Table · Book3D · ProTable · PricingTable · JsonViewer · EditableTable
Playground
<div className="relative h-80 overflow-hidden rounded-xl bg-bg">
<DomeGallery
segments={24}
fit={0.5}
grayscale={true}
autoRotate={false}
/>
</div>