When to use it

Use ProductImage as the main media gallery on a product detail page. It handles the high-importance browsing behavior around product imagery, including thumbnails, lightbox viewing, a consistent hero image frame, synced active-image state, and variant-aware image handoff.

If the page only needs a single static image, a simpler image block is usually enough.

Composition notes

The gallery is prop-driven:

• images is the required media array.
• each image can include variant metadata so the gallery knows which simple selector value it belongs to.
• each image can include variantId metadata so the gallery can also match a resolved backend variant id.
• activeVariantId takes priority and activates the first image whose variantId matches the selected value.
• activeVariant activates the first image whose variant matches when no activeVariantId is provided.
• aspectRatio controls whether the frame reads square or portrait.
• interaction controls whether the gallery opens the fullscreen lightbox on click or tap. The default is "lightbox".
• activeIndex, defaultActiveIndex, and onActiveIndexChange control the inline carousel, thumbnail rail, and the lightbox handoff.
• lightboxOpen, defaultLightboxOpen, and onLightboxOpenChange let a parent own the fullscreen viewer state when needed.
• showThumbnails, thumbnailPosition, and maxThumbnails shape the secondary navigation rail.
• arrows chooses whether navigation sits inside or outside the frame.
• showDots is useful when the layout is tighter and thumbnails would be too heavy.
• viewTransitions is a progressive-enhancement hook for shared-element continuity between the PDP hero and the fullscreen viewer.

Start with the content and device needs, then choose the navigation affordances that match.

Behavior and theming guidance

Use 4:5 when the product is fashion- or portrait-led. Use 1:1 when the assortment benefits from a more catalog-like square rhythm.

Thumbnail rails add clarity but also visual weight. On compact surfaces, dots plus arrows often give a cleaner result. When the image set is longer than the visible thumbnail count, the rail fades at the edge to hint at overflow without feeling heavy.

classNames now exposes stable hooks for the thumbnail rail, thumbnail buttons, active-thumbnail state, thumbnail images, and overflow indicator. That lets one PDP keep a soft, editorial thumbnail treatment while another uses harder technical framing without reaching into aria labels or private DOM structure.

For variant-heavy PDPs, decide whether your page state is still axis-level or already resolved:

• use activeVariant when the selector state is still a simple value like "oak" or "black"
• use activeVariantId when your product logic has already resolved a concrete purchasable variant like "sku-oak-001"

If both are present, ProductImage prioritizes activeVariantId. If several images belong to the same variant or variant id, the gallery activates the first matching image and the visitor can continue browsing from there.

Always keep alt text meaningful because the gallery is a primary part of the PDP experience. If you opt into shared-element continuity, keep image identities stable across variant switches so the transition still feels like the same object going deeper.