DocsDocsSDKs

ProductImage

React SDK guidance for ProductImage.

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

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.

Compatibility note

showZoom has been removed. Use the default interaction="lightbox" behavior for fullscreen inspection, or set interaction="none" when the gallery should stay inline only.

View-transition-ready usage

If your app wants shared-element continuity between the inline hero and the fullscreen viewer, give each ImageAsset a stable id and enable viewTransitions. The component exposes consistent image identity, while the host app decides how far to take the transition choreography.

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.

Review notes

These notes define scoped usage boundaries without claiming exact prop or runtime truth beyond SDK package reference.

ProductImage stays focused on PDP media behavior. It can own active media, thumbnails, lightbox handoff, and variant-aware image selection; the host page still owns the media list, variant state, and product-data freshness.

  • Provide meaningful alt text and stable image identities, especially when using variant switching or view-transition continuity.
  • Use activeVariantId when backend variant resolution is already known, and activeVariant when the page is still working with simple selector values.
  • Do not move PDP gallery, lightbox, or thumbnail responsibilities into generic card copy; keep those behaviors on the media component that owns them.

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=ProductImage.
  • Copy/paste scope: guidance-only. Treat examples as guidance until checked against SDK package reference.

Implementation notes

  • ProductImage owns PDP media, lightbox, and thumbnail behavior; do not move those responsibilities into generic product-card display copy.

ProductImage

# ProductImage > 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/storefront/product-image](https://sdk.enad.io/components/storefront/product-image). ## 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. > **Compatibility note** > > `showZoom` has been removed. Use the default `interaction="lightbox"` behavior for fullscreen > inspection, or set `interaction="none"` when the gallery should stay inline only. > **View-transition-ready usage** > > If your app wants shared-element continuity between the inline hero and the fullscreen viewer, > give each `ImageAsset` a stable `id` and enable `viewTransitions`. The component exposes > consistent image identity, while the host app decides how far to take the transition choreography. ## 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. ## Review notes These notes define scoped usage boundaries without claiming exact prop or runtime truth beyond SDK package reference. `ProductImage` stays focused on PDP media behavior. It can own active media, thumbnails, lightbox handoff, and variant-aware image selection; the host page still owns the media list, variant state, and product-data freshness. - Provide meaningful alt text and stable image identities, especially when using variant switching or view-transition continuity. - Use `activeVariantId` when backend variant resolution is already known, and `activeVariant` when the page is still working with simple selector values. - Do not move PDP gallery, lightbox, or thumbnail responsibilities into generic card copy; keep those behaviors on the media component that owns them. ## 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=ProductImage. - Copy/paste scope: guidance-only. Treat examples as guidance until checked against SDK package reference. ### Implementation notes - `ProductImage` owns PDP media, lightbox, and thumbnail behavior; do not move those responsibilities into generic product-card display copy.