When to use it

Use ProductHeroSection when the storefront wants the fast path for the top of a product detail page.

It is the right starting point when the page needs:

• a credible PDP hero quickly
• explicit media, buy-box, actions, and trust zones
• benchmark-style variation through content and one-zone overrides
• a clear upgrade path down into the lower-level PDP family surfaces

Family ownership map

ProductHeroSection is a section-first wrapper built on the public PDP family layer.

• media zone → ProductMedia (with ProductImage still owning the gallery mechanics beneath it)
• buy-box header and options zone → BuyBox
• purchase action zone → PurchaseActions
• trust zone → ProductTrust
• post-hero body → pair with ProductDetails when the page needs structured long-form sections after the hero

That ownership map is the point of the component. It is a useful section, not a closed product-page template.

Easy path and open path

The easy path is the structured prop API:

• media
• header
• options
• actions
• trust

Inside that easy path, options.helper is the intended extension seam for size-guide or fit-support content, while actions.helper, actions.secondary, and actions.footer cover stock-state copy, notify-me flows, and other purchase-adjacent behavior without turning those flows into SDK-owned vendor assumptions.

Inside media, the gallery behavior fields stay top-level on the section prop (images, aspectRatio, showThumbnails, and friends) while the lower-level ProductMedia family is what owns the optional shell framing like heading, caption, and footer.

The open path is selective replacement.

Each major zone accepts either structured content for the common path or a direct content override for the advanced path. That lets the app replace one region at a time instead of throwing away the whole section. The media zone now covers short-form heading, caption, and footer framing through ProductMedia, the options zone can host helper extensions such as size guides through options.helper, and the action zone can surface stock-state or notify-me extensions through actions.helper, actions.secondary, and actions.footer before the page ever needs to drop down into the lower-level families.

Behavior and theming guidance

ProductHeroSection should be the first answer for most “I need a full PDP hero quickly” questions because it keeps the public family ownership visible while staying fast to adopt.

Use it to prove different PDP rhythms through content and component-set shifts:

• commerce-dense product pages with a strong buy-box and reassurance cluster
• quieter editorial PDPs that give the gallery and product story more visual control
• bounded trust or action overrides without rewriting the whole hero

If the page grows beyond the section contract — for example, several post-hero information sections, custom downloads/specs blocks, or a different hero anatomy entirely — keep the top of the page on ProductHeroSection, keep immediate reassurance in ProductTrust, move the body to ProductDetails, and only drop fully into ProductMedia, BuyBox, PurchaseActions, and ProductTrust when the hero anatomy itself stops fitting.