When to use it

Use ImageLightbox when product images or editorial photography need a fullscreen viewing experience with zoom, pan, and multi-image navigation. It is the standard viewer for PDP image galleries where visitors want to inspect details at full resolution.

The lightbox is controlled for visibility: the parent page manages open state and decides what triggers it, whether that is a dedicated button, a thumbnail click, or a product image tap.

Composition notes

ImageLightbox is a controlled fullscreen overlay:

• images is an array of ImageAsset objects with src, optional alt, and optional stable id values.
• open and onOpenChange manage visibility.
• activeIndex and onActiveIndexChange let the parent decide which image is currently visible. Use them with thumbnail grids or ProductImage to open directly to the clicked image and keep the inline gallery in sync.
• defaultActiveIndex is available when the parent wants the viewer to manage active-image state after the initial open.
• showThumbnails toggles a thumbnail rail at the bottom of the viewer for quick navigation between images.
• viewTransitions exposes a progressive-enhancement hook for shared-element continuity when the host app supports it.

Behavior and theming guidance

The viewer supports keyboard navigation with Left, Right, and Escape, touch swipe between images, and pinch-to-zoom on mobile. Zoom and pan are powered by react-zoom-pan-pinch.

The overlay covers the full viewport with a dark background. The thumbnail rail sits at the bottom and marks the current image clearly without overpowering the main media. Keep the image array manageable for smooth thumbnail rendering, and keep ImageAsset.id stable when you enable view transitions so the browser can treat the hero image and fullscreen image as the same asset.