Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 61 ยท Products, Collections and Variants

Building the Product Page

Build a Shopify product page step by step: the product object, price and compare-at price, media gallery, the product form and the selected variant.

The product page is where a store earns its money. A shopper arrives with a question: what is it, what does it cost, can I see it, can I buy it? Your section has to answer all four quickly, and it has to keep working when the merchant edits the product, adds a sale price or runs out of stock. Everything you need arrives in one Liquid object called product.

In this lesson you will meet the properties used on almost every product page, learn how to choose the variant to show first, render a price correctly (with a sale price when there is one), loop over media, and build the product form that adds the item to the cart. Variants, media and the cart each get their own deeper lessons; here you assemble the whole page so you can see how the pieces fit.

Liquid and the real product object exist only on Shopify's servers, so the theme code in this lesson is read-only and written for current Online Store 2.0 themes (Liquid has no API version number; objects change slowly and additions are documented in Shopify's changelog). The live examples use a hand-made mock product and small JavaScript functions that mimic what your Liquid does, so you can experiment with the logic.

What the product page is made of

On a modern theme the templates/product.json file lists a main-product section plus optional extras. Inside main-product, a merchant-friendly layout uses blocks: title, price, variant picker, quantity, buy buttons, description. The merchant reorders blocks; your Liquid renders each one by type. (Blocks are explained fully in Blocks and Theme Blocks.)

flowchart LR
  P["product object"] --> G["Media gallery"]
  P --> T["Title and vendor"]
  P --> V["selected_or_first_available_variant"]
  V --> PR["Price and compare-at price"]
  V --> A["Availability"]
  P --> D["Description"]
  V --> F["Product form<br/>variant id, quantity, add button"]

Most of the page comes from the product itself; price, availability and the form all depend on one chosen variant.

The product object

These properties cover most pages:

Property What it gives you
product.title the product name
product.handle the URL-safe name, e.g. blue-mug
product.url the product's URL, relative
product.vendor, product.type brand and product type text
product.description the description as HTML
product.featured_media the main media item
product.media all media, in the merchant's order
product.variants all variants
product.options_with_values option names with their values
product.has_only_default_variant true when there are no real options
product.available true if at least one variant can be bought
product.selected_or_first_available_variant the variant to show right now
product.tags tags added by the merchant

Two cautions. product.description is already HTML, so print it as {{ product.description }} without escaping, and never wrap it in a paragraph tag yourself. And product.price is the lowest variant price, which is correct for a collection card ("From $12") but wrong for the product page, where the price must follow the chosen variant.

Choosing the variant to show

A product with one color and three sizes has three variants. Which price do you print before the shopper chooses? Shopify gives you product.selected_or_first_available_variant:

  • if the URL has ?variant=123, that variant is used (when it exists);
  • otherwise the first variant that is available to buy;
  • otherwise the first variant, even if sold out.

Assign it once at the top of your section and use the variable everywhere:

LIQUID
{%- assign current_variant = product.selected_or_first_available_variant -%}

Related, product.selected_variant returns nil unless the URL named a variant. That is useful when you want to know whether the shopper made a choice, and risky if you treat it as always present. When a shopper changes the option picker, your JavaScript updates the URL and the page; Variants and Option Pickers shows how.

Printing prices correctly

All Shopify money values are integers in the smallest currency unit, such as cents. 1400 means $14.00. The money filter formats them using the shop's currency settings:

LIQUID
{%- assign price = current_variant.price -%}
{%- assign compare_at = current_variant.compare_at_price -%}

<div class="price">
  {%- if compare_at > price -%}
    <s>{{ compare_at | money }}</s>
    <strong>{{ price | money }}</strong>
    <span class="badge">Sale</span>
  {%- else -%}
    <strong>{{ price | money }}</strong>
  {%- endif -%}
</div>

The test compare_at > price is important. Merchants sometimes enter a compare-at price that is equal to or lower than the price; a strikethrough in that case looks wrong. A blank compare-at price makes the comparison false, so the sale branch does not run. Never do arithmetic on these numbers with floats; integers keep totals exact, an idea explained in Money as Integers. If you need a percentage off, calculate it with integers and round:

LIQUID
{%- assign percent_off = compare_at | minus: price | times: 100 | divided_by: compare_at -%}

Because both inputs are integers, divided_by performs integer division and gives a whole-number percentage.

The gallery loops over product.media. Each entry has a media_type (image, video, external_video or model), a preview_image and an alt text:

LIQUID
<ul class="gallery">
  {%- for media in product.media -%}
    <li data-media-id="{{ media.id }}">
      {%- if media.media_type == 'image' -%}
        {{ media.preview_image | image_url: width: 1200 | image_tag: widths: '600, 900, 1200', sizes: '(min-width: 750px) 50vw, 100vw', loading: 'lazy' }}
      {%- else -%}
        {{ media.preview_image | image_url: width: 600 | image_tag }}
      {%- endif -%}
    </li>
  {%- endfor -%}
</ul>

The first image is the one shoppers (and Google) see first, so it should not be lazy-loaded; use loading: 'eager' and a high fetch priority for it, as covered in Theme Performance and Core Web Vitals. Videos, 3D models, srcset and per-variant images are the topic of Product Media.

product.featured_media is the first item (or the one the merchant marked as featured). current_variant.featured_media is the media linked to that variant, if any; fall back to product.featured_media when it is blank.

The product form

The buy button is a real HTML form that posts to /cart/add. Liquid's form tag builds it with the hidden fields Shopify needs:

LIQUID
{%- form 'product', product, id: 'product-form', class: 'product-form' -%}
  <input type="hidden" name="id" value="{{ current_variant.id }}">

  <label for="quantity">Quantity</label>
  <input id="quantity" type="number" name="quantity" value="1" min="1">

  <button type="submit" name="add" {% unless current_variant.available %}disabled{% endunless %}>
    {%- if current_variant.available -%}
      Add to cart
    {%- else -%}
      Sold out
    {%- endif -%}
  </button>

  {{ form | payment_button }}
{%- endform -%}
  • The hidden id input carries the variant id. The cart works with variants, not products, so this is the field that decides what is added. JavaScript that changes the selected variant must update it.
  • quantity defaults to 1. Set a sensible min and respect current_variant.quantity_rule if your theme supports quantity rules.
  • The disabled button prevents a doomed request when the variant is unavailable.
  • {{ form | payment_button }} prints Shopify's dynamic checkout buttons (the "Buy it now" row with wallet options). It appears only when the store has them enabled.

Without any JavaScript this form works: the browser posts it and Shopify redirects to the cart. A JavaScript enhancement can intercept the submit and add the item with fetch instead; that comes in The Product Form and Add to Cart and The Ajax Cart API. Keep the plain form working underneath.

Description, tags and structure

Print the description inside a container with a class, so your CSS can style headings and lists within it:

LIQUID
<div class="rte">{{ product.description }}</div>

Use one <h1> on the page (the product title) and keep other headings in sensible order. Reviews, FAQs and extra metafield content usually belong in their own blocks or sections, covered in Metafields in Themes.

Stand-in: price, sale and availability

The first stand-in uses a mock product to run the same price logic as the Liquid above. The money filter here is an imitation that formats integer cents as dollars. The real filter reads the shop's currency format settings.

JS Stand-in: price display for a mock product

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Read the output for the case ?variant=103: the variant exists, so it is selected even though it is sold out, and its equal compare-at price correctly shows no sale. With ?variant=999 the id does not exist, so the page falls back to the first available variant. What is real here is the selection rule and the sale test; the money function and the data are imitations.

Stand-in: assembling a page from blocks

The second stand-in renders a page from an ordered list of blocks, just as main-product does with block_order. It uses the same mock product and a plain function per block type.

JS Stand-in: render product blocks in the merchant's order

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The reordering is the whole point: the merchant changes block_order in the editor, your renderers stay the same. The missing alt text on the third image is a nudge toward the accessibility habits in Accessibility in Themes.

Common mistakes

  • Using product.price on the product page. It does not follow the selected variant. Use the variant's price.
  • Not handling sold-out and unavailable variants. Disable the button and say "Sold out" instead of letting the shopper click.
  • Forgetting the id input. Without the variant id the form adds nothing useful.
  • Printing the description in a <p>. The description already contains block tags.
  • Floating-point money. Keep amounts as integers until you display them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which value should the product page price follow?

    Price depends on the chosen variant, so use product.selected_or_first_available_variant (or the variant JavaScript has selected) and its price.
  2. 2. What does the hidden input named id carry in the product form?

    Carts hold variants, so the form must send the variant id. JavaScript that changes the selected variant must update this input.
  3. 3. How should you decide to show a strikethrough compare-at price?

    A compare-at price is only meaningful if it is higher than the current price; equal or lower values would show a misleading discount.
  4. 4. Why should you avoid wrapping product.description in your own paragraph tag?

    The description is stored as HTML. Wrapping it in a p tag produces invalid nested block elements; use a div instead.

Summary

  • The product object holds everything for the page; the price, availability and form depend on the selected variant.
  • Use product.selected_or_first_available_variant once at the top, then use it everywhere.
  • Money values are integer cents; format them with money, and show a sale price only when compare_at_price is greater than price.
  • Loop over product.media for the gallery, and build the page from blocks so merchants can reorder it.
  • The product form must send the variant id and should work without JavaScript.

Next, make the variant choices interactive in Variants and Option Pickers.