Image Viewer
ImageViewer isolates the image presentation layer for product showcases, galleries, and e-commerce catalogs with built-in fullscreen lightbox expansion and colorway synchronization.Inner Lens Magnifier Zoom Viewer
- Use
variant"inner-zoom" - magnifies the product image directly within the hero frame upon cursor hover (260% optical scale).
HD Side Portal Lens Zoom Viewer
- Use
variant"side-zoom" - floats a 3x zoom loupe just above the hovered or touched point, with a reticle marking exactly the area it shows — it flips below when there is no room above and always stays inside the screen.
- Tune
zoomLevel{6} - raises the magnification; 3–10 is the usual e-commerce range.
Floating Arrow Slider & Dots Viewer
- Use
variant"slider" - features floating left and right chevron navigation buttons with backdrop blur, bottom dot indicators, and expandable lightbox.
Interactive Thumbnail Strip Gallery Viewer
- Use
variant"thumbnails" - displays an active thumbnail preview gallery alongside the main hero image with expandable lightbox.
- Placement
thumbnailPosition"left" | "right" | "bottom" - controls the thumbnail strip position ("left" displayed in preview; also supports "right" and "bottom").
Installation
New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.
Install Image Viewer
components/ is written into your project. Copy any snippet from a Usage tab above and it runs.
Install dependencies
Nothing beyond the shared setup — Image Viewer needs only the cn helper and lucide-react, which the installation guide already put in place.
Features
ImageViewer component:4 Dedicated Viewer Architectures
Includes Inner Lens Zoom, Side Portal Zoom Projection, Floating Arrow Slider, and Active Thumbnail Strip Gallery.
Integrated Lightbox Modal
Theme-adaptive frosted glass overlay matching Light and Dark mode with keyboard controls, chevron navigation, and thumbnail strip.
High-Definition Optical Zoom
Experience smooth 2.6x inner frame magnification or a 3–10x floating zoom loupe on cursor hover and touch drag.
100% Mobile Responsive
Fluid aspect ratio framing and touch-friendly controls tested across mobile phones, tablets, and desktop displays.
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "inner-zoom" | "side-zoom" | "slider" | "thumbnails" | "inner-zoom" | Selects the image viewing architecture. |
thumbnailPosition | "left" | "right" | "bottom" | "left" | Position of the thumbnail preview strip when using variant="thumbnails". Supports vertical "left", vertical "right", and horizontal "bottom". |
defaultImage | number | 3 (side-zoom) / 1 (slider) / 2 (thumbnails) / 0 (others) | Initial active image index (0-indexed). Defaults to index 3 (4th image) for side-zoom, index 1 (2nd image) for slider, and index 2 (3rd image) for thumbnails. |
images | string[] | DEFAULT_IMAGES | Array of product or gallery image URLs to display. |
colors | ImageViewerColor[] | DEFAULT_COLORS | Optional colorways, one per image. Colorway i's bgClass tints the frame and thumbnail behind image i. |
badge | string | "20% OFF" | Text displayed inside the top-left floating promo chip badge. |
showWishlist | boolean | true | Toggles the floating top-right heart wishlist button. |
enableLightbox | boolean | true | Whether clicking the hero image triggers the fullscreen modal lightbox (active in slider and thumbnails). |
zoomLevel | number | 3 | Magnification of the side-zoom loupe over the image as it appears in the frame; 3–10 is the usual e-commerce range. The reticle shrinks to match. Serve images large enough to stay sharp at it — roughly the frame width × 1.4 × zoomLevel. |
onImageChange | (index: number) => void | undefined | Callback triggered whenever the user switches the active image. |
className | string | undefined | Additional Tailwind CSS classes applied to the root container. |