Exact exports, props, slots, hooks, and runtime behavior belong to SDK package reference. Examples are guidance unless explicitly marked copy-paste-safe.

Review component intent and composition guidance before wiring this component into an app. Then use the live playground to confirm the rendered behavior.

Playground

• Import path: @enadhq/enad-react-sdk/client/storefront.
• Live playground: /components/commerce/image-lightbox.

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.

Compatibility note

startIndex has been removed. Use activeIndex for controlled state or defaultActiveIndex for uncontrolled initial positioning.

Pair with ProductImage on PDPs

On product detail pages, wire the ProductImage gallery to open the lightbox on click, passing the active image index through shared state. This keeps the inline gallery and the fullscreen viewer feeling like the same object going deeper.

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.

Contract scope

• Use SDK package reference for exact props, exports, slots, hooks, and runtime behavior.
• Public import: @enadhq/enad-react-sdk/client/storefront.
• Playground route: /sandbox?component=ImageLightbox.
• Copy/paste scope: guidance-only. Treat examples as guidance until checked against SDK package reference.

Implementation notes