Product detail page
Compose a PDP hero, media, variant selection, price, and purchase-adjacent UI without moving cart or checkout side effects into presentational components.
Use this guide when the app needs the top of a product detail page: media, product identity, price display, options, purchase controls, and trust content.
This guide is about PDP composition and responsibility boundaries. Exact props, variant contracts, cart integration, checkout behavior, and API schemas belong to package reference, API references, and the application code that owns commerce state.
Start with ownership
A PDP has several owners:
- Product fetch and freshness belong to the app data layer or generated API/Search source.
- Media gallery behavior belongs to the
ProductImage/ProductMediafamily. - Price display belongs to
Price. - Option selection UI belongs to
VariantSelectoror a connected wrapper when the behavior is documented. - Variant resolution and inventory truth belong to app product logic or a backend data source.
- Add-to-cart, checkout, payment, and delivery effects belong to the app commerce integration.
- PDP composition belongs to
ProductHeroSectionor lower-level PDP families.
Do not let presentational components become the source of inventory, checkout, or cart truth.
Fast path: section-level hero
Use ProductHeroSection when the default PDP hero anatomy is close enough and the page needs a credible section quickly.
It gives you zones for:
- media
- buy-box header and options
- purchase controls
- trust or reassurance
- downstream body handoff
Replace one zone at a time when the product experience needs more control. Drop to lower-level families only when the hero anatomy stops fitting.
Media and variants
Use ProductImage or ProductMedia for PDP media behavior. Keep this boundary clear:
- The media component can own active image, thumbnails, lightbox handoff, and variant-aware image selection.
- The page owns the media list, alt text quality, selected variant state, and data freshness.
- Use backend variant identity when the product logic has already resolved it.
- Use simple selector values only while the page is still working at the axis level.
Use VariantSelector for controlled option-selection UI. It should not perform add-to-cart behavior. Resolve the concrete purchasable variant before purchase controls run.
Price and purchase-adjacent content
Use Price for localized numeric money display. Keep tax, shipping, financing, promotion rules, and jurisdiction-specific wording around the component, not inside it.
Use PurchaseActions and QuantityPicker as UI surfaces that call app-owned handlers. The app still owns:
- cart mutation
- stock and purchase eligibility checks
- checkout handoff
- payment and delivery state
- retry and error recovery
PDP checklist
- Product data and variant availability come from a current source, not from guide prose.
- Media entries include meaningful alt text.
- Variant axis keys are stable.
- Price display receives numeric money and locale/currency context where required by the package API.
- Purchase controls call app-owned side-effect handlers.
- Trust content is true for the current merchant, market, and fulfillment setup.
- Post-hero content moves to ProductDetails or app-owned sections instead of overloading the hero.