--- title: Product Detail Page (PDP) description: A single product page with variants, media, and add-to-cart. type: guide --- # Product Detail Page (PDP) The Product Detail Page (PDP) is a single product page — title, price, media, variant selection, and add-to-cart. It's the smallest unit of commerce in the storefront. ## How it works **Static-first rendering.** Product data is awaited at the top of the page and baked into the static shell, so the title, price, gallery, and description ship as one coherent copy. Freshness comes from cache invalidation — a Shopify webhook calling `revalidateTag`, plus the `cacheLife` window — not a per-request fetch, so the body never re-renders at request time. **Variant selection through URL searchParams.** Each option change is a navigation (`/products/tee?color=Blue&size=XS`), not client state. That gives you shareable URLs, working browser back/forward, and a fully server-rendered page with zero layout shift. The selected variant resolves from a second, per-selection Shopify query kept off the critical path, so the picker highlights at URL speed rather than waiting on the network. ## Out of the box * **Variant picker** — color, size, and other options rendered as links, with swatch availability decoded from Shopify's encoded variant data. * **Color-aware image gallery** — a desktop grid with lightbox and a mobile snap carousel, leading with the selected color's image when color options have distinct media. * **Add to cart** — optimistic add of the selected variant. * **Quantity picker** — a 1–99 picker beside the cart action. * **Buy with Shop** — Shopify's official lock-up that creates a checkout and redirects to it. * **Bundles** — "includes" and "available in" bundle relationships below the buy buttons. * **Complementary products** — merchant-curated "Pairs Well With" add-ons. * **Related products** — algorithmic "you might also like" set below the product details. * **Structured data** — Product and Breadcrumb JSON-LD for search and social. The quantity picker, Buy with Shop, bundles, complementary products, and related products are on by default and toggled under `pdp` in `shop.config.ts`. ## Common customizations The PDP doesn't ship these, but they're common additions teams layer on top. Each is your own data source and component, wired in alongside the other sections in `product-detail-section.tsx`. * **Reviews** — a ratings summary near the price and a review list below the details, usually backed by a reviews app or Shopify metafields. * **Virtual try-on** — an AR or camera overlay launched from the gallery, typically a modal wrapping a partner SDK. * **Metafield accordion** — an accordion below the description surfacing metafields (materials, care, sizing) that aren't part of the default fields. * **Waitlist** — a restock signup that replaces Add to Cart when the selected variant is unavailable. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)