Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 61 ยท Layouts, Templates and Sections

Product, Collection, Cart and Page Templates

A tour of every Shopify page template: which sections each one needs, the main section pattern, and special cases like gift cards and the password page.

A store has far more page types than most people notice. Beyond the home page and product page there are collections, a list of all collections, blog and article pages, search results, the cart, a 404 page, customer account pages, a password page for stores that are not open yet, and even a gift card page. Each type has its own template in the templates folder, and each template expects different data to be available.

This lesson is a map. You will learn the template types, what object each one provides, the "main section" idea that holds a page together, and the two special cases that cannot be JSON. After it you will be ready to build real pages, starting with the product page.

Templates and sections run on Shopify's servers, so real theme code here is read-only and targets current Online Store 2.0 themes. Section names such as main-product follow the Dawn reference theme's naming convention; they are conventions, not fixed names. The two live examples are JavaScript stand-ins that check a template folder and validate a template, so you can practice the rules without a store.

One template per page type

Shopify decides the template type from the URL (you saw the routing idea in What Is a Shopify Theme?). Each type exposes a main object in Liquid:

Template Typical URL Main object Notes
index / none specific the home page: a stack of sections
collection /collections/shoes collection product grid, filters, pagination
list-collections /collections collections all collections
product /products/blue-mug product gallery, price, variants, form
page /pages/about page a merchant-written page
blog /blogs/news blog list of articles, paginated
article /blogs/news/spring article, blog one post, optional comments
search /search?q=mug search results for a query
cart /cart cart line items and the checkout button
404 any unknown URL none specific friendly "not found" page
password storefront locked shop.password_message uses its own layout
gift_card.liquid gift card link gift_card Liquid only, never JSON

Customer templates (customers/login, customers/account and others) form their own family, which Customer Accounts and Account Pages covers.

Templates can also have alternates. A file called product.limited.json is an alternate product template with the suffix limited. The merchant chooses it for individual products in the admin, which is how one store gets different layouts for different products. See JSON Templates and Online Store 2.0 for the full mechanics.

What a JSON template looks like

Almost all templates are JSON files that list sections. Here is a product template, trimmed to the essentials:

JSON
{
  "sections": {
    "main": {
      "type": "main-product",
      "blocks": {
        "title": { "type": "title", "settings": {} },
        "price": { "type": "price", "settings": {} },
        "buy": { "type": "buy_buttons", "settings": {} }
      },
      "block_order": ["title", "price", "buy"],
      "settings": {}
    },
    "recommendations": {
      "type": "product-recommendations",
      "settings": { "heading": "You may also like" }
    }
  },
  "order": ["main", "recommendations"]
}

Three pieces matter. sections is a map from a unique key (the instance) to a section type, which is the file name in sections/ without the extension. blocks and block_order configure blocks inside that section. order is the sequence the page renders in. The merchant's drag-and-drop in the editor rewrites exactly these keys.

flowchart TB
  T["templates/product.json"] --> M["main<br/>type: main-product"]
  T --> R["recommendations<br/>type: product-recommendations"]
  M --> B1["title block"]
  M --> B2["price block"]
  M --> B3["buy_buttons block"]
  L["layout/theme.liquid<br/>header, footer"] -. wraps .-> T

A template names section instances and their order; sections contain blocks; the layout wraps everything.

The "main" section pattern

Every content template needs one section that does the page's real work: print the product, loop over the collection's products, render the article body. By convention that section is registered under the key main, and Dawn names the files after their job:

Template Main section in Dawn What it must do
product main-product gallery, title, price, variant picker, form
collection main-collection-product-grid loop and paginate collection.products, show filters
list-collections main-list-collections loop over collections
page main-page print page.title and page.content
blog main-blog paginate and list blog.articles
article main-article print article.content, author, date
search main-search show search.results or a no-results state
cart main-cart-items and main-cart-footer line items, totals, checkout button
404 main-404 message and a link home

Why a main section? Because the other sections are decoration around it. A merchant can add a banner above the product or a testimonial below the cart, but if they delete the main section, the page has no product at all. Good themes make main sections hard to delete or clearly labeled, and keep optional extras in separate sections.

What each main section does with its object

A few snippets show how different the work is.

Product. The product object is already loaded, so the section prints it. The next two lessons cover this in depth.

LIQUID
<h1>{{ product.title }}</h1>
<p>{{ product.selected_or_first_available_variant.price | money }}</p>

Collection. A collection can hold thousands of products, so you paginate inside the section:

LIQUID
{%- paginate collection.products by 24 -%}
  <ul>
    {%- for product in collection.products -%}
      <li>{{ product.title }}</li>
    {%- endfor -%}
  </ul>
  {{- paginate | default_pagination -}}
{%- endpaginate -%}

The paginate tag controls how many items load and creates the page links. Filters, sorting and URL parameters are the subject of Collection Pages.

Search. The template always renders, even before a search is made, so the section checks search.performed and handles empty results:

LIQUID
{%- if search.performed -%}
  {%- paginate search.results by 24 -%}
    {%- for item in search.results -%}
      <a href="{{ item.url }}">{{ item.title }}</a>
    {%- else -%}
      <p>No results for "{{ search.terms | escape }}".</p>
    {%- endfor -%}
  {%- endpaginate -%}
{%- endif -%}

Notice escape on the search terms: shoppers control that text, so it must be escaped. Security in Themes explains why.

Cart. The cart page needs cart.items, totals and a form that posts to /cart with a checkout button. The deeper cart lessons start with The Product Form and Add to Cart.

Blog and article. Blog pages paginate blog.articles. Article pages print article.content and, if the blog allows comments, include a comment form. Both are straightforward once you know paginate and loops.

Special cases

The password page. When a store is not open to the public, Shopify shows the password template and wraps it in layout/password.liquid instead of theme.liquid. That page typically shows a message from shop.password_message, a newsletter form, and a login form for people with the password. It must stay light, because shoppers land on it before the store is ready.

The gift card page. templates/gift_card.liquid is a Liquid template, not a JSON one. It is the page a customer sees after receiving a gift card by email. It reads a gift_card object (code, balance, expiry) and usually outputs its own full HTML document, because it does not use the normal layout. Keep it simple and print-friendly.

Robots and sitemaps. robots.txt.liquid is another Liquid-only template, used for search engine rules; you will meet it in SEO in Themes.

Customer templates. Their behavior depends on whether the store uses the newer customer accounts (hosted by Shopify) or classic accounts (rendered by your theme). More on that later.

Choosing what each template should include

Beyond the main section, think about what a shopper expects on each page.

  • Home: a hero, featured collection, a short trust or about block, newsletter.
  • Collection: a banner with the title, the grid, filters and pagination.
  • Product: main section, recommendations, optional reviews or FAQ sections.
  • Cart: items, order notes if needed, shipping messaging, and recommendations.
  • 404: a search box and links back to popular collections.

Put each of these in its own section so a merchant can reorder or remove optional parts. That is the Online Store 2.0 promise.

Stand-in: does a theme cover every template?

This first stand-in checks a list of files in a made-up theme and reports which template types are missing. In a real project, shopify theme check and the Shopify CLI do this kind of checking for you.

JS Stand-in: audit a theme's templates

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

No output.

What is real: the template type names and the rule that gift_card must be Liquid. What is imitation: the audit script. It does not look inside the files.

Stand-in: validating a template

The second stand-in validates a product template the way a careful reviewer would: every instance in order must exist, each type must have a section file, there must be a main section, and block order must match defined blocks. The limits in the script are the documented ones at the time of writing; check Shopify's current documentation before relying on exact numbers.

JS Stand-in: validate a JSON template

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

No output.

Real Shopify rejects some of these on upload and ignores others, so the exact behavior differs. The takeaway is the checklist: names must line up between sections, order, type and the files on disk.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which template cannot be a JSON template?

    gift_card.liquid is a Liquid template and usually outputs its own complete HTML. Most other page templates can be JSON.
  2. 2. In a JSON template, what does the order array contain?

    order lists instance keys from the sections map, such as main and recommendations. The type inside each entry names the section file.
  3. 3. Where should a collection page paginate its products?

    The collection main section wraps its product loop in the paginate tag, which limits items per page and builds page links.
  4. 4. Why escape search.terms when printing it?

    search.terms is user input. Escaping prevents injected markup from running on your page.

Summary

  • Every page type has a template; most are JSON files listing section instances, their blocks and their order.
  • Each content template needs a main section that renders the page's object (product, collection, article, cart items and so on).
  • Optional extras belong in separate sections so merchants can move or remove them.
  • gift_card.liquid and robots.txt.liquid are Liquid-only; the password page has its own layout.
  • Collection, blog and search pages paginate inside their main section, and any shopper-controlled text must be escaped.

Next, build the most important page in the store in Building the Product Page.