Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 61 ยท Layouts, Templates and Sections

Layouts and theme.liquid

Understand Shopify layouts: what theme.liquid must contain, content_for_header and content_for_layout, section groups, the password layout, extra layouts and layout none.

Every page of a Shopify store is a template wrapped in a layout. The layout is the frame that stays the same from page to page: the <html> and <head>, the header and footer, the scripts and styles. The template is what changes: a product, a collection, a cart. Think of the layout as a picture frame and the template as the picture.

In a theme the frame lives in the layout/ folder, and the main one is layout/theme.liquid. This lesson covers what that file must contain, the two objects Shopify fills in for you (content_for_header and content_for_layout), how headers and footers are added with section groups, and how to use other layouts for special pages such as the password page or a stripped-down landing page.

What this lesson targets: Online Store 2.0 themes on current Shopify. The Liquid and JSON in the plain code blocks is read-only, because the site has no Shopify. The editors are JavaScript stand-ins: a small function that glues a template into a layout, and another that picks a layout using the rules described below. They show the idea; the real rendering happens on Shopify's servers.

The shape of theme.liquid

Here is a small but realistic layout/theme.liquid. Every line that matters is annotated below it.

LIQUID
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ page_title }}</title>
    {%- if page_description %}
      <meta name="description" content="{{ page_description | escape }}">
    {%- endif %}
    <link rel="canonical" href="{{ canonical_url }}">

    {{ content_for_header }}

    {{ 'base.css' | asset_url | stylesheet_tag }}
  </head>

  <body class="template-{{ template.name }}">
    <a class="skip-link" href="#MainContent">Skip to content</a>

    {% sections 'header-group' %}

    <main id="MainContent" tabindex="-1">
      {{ content_for_layout }}
    </main>

    {% sections 'footer-group' %}

    <script src="{{ 'theme.js' | asset_url }}" defer></script>
  </body>
</html>

Read it from top to bottom:

  • request.locale.iso_code gives the language of the page for the lang attribute, which screen readers and search engines use.
  • page_title, page_description and canonical_url are global objects describing the current page (The Global Objects You Use Most). Always escape text that goes into an attribute.
  • content_for_header and content_for_layout are the two required objects; see the next sections.
  • {% sections 'header-group' %} and {% sections 'footer-group' %} render section groups.
  • template.name is the type of the current template (product, collection, ...), handy as a CSS hook.

content_for_header

{{ content_for_header }} must sit inside <head>. Shopify fills it with everything it needs on the page: its analytics and storefront scripts, the code of app embeds that merchants switched on, helpers the theme editor needs, and similar plumbing. As a theme developer you never write that content; you only provide the slot.

Three rules keep you out of trouble:

  1. Do not remove it. Without it, Shopify features and many apps break, and the theme editor cannot talk to your page.
  2. Do not try to parse, filter or capture its output. The markup inside changes over time and is not a stable interface.
  3. Put your own critical styles and meta tags near it, but keep the output itself untouched.

content_for_layout

{{ content_for_layout }} goes in the body, where the page content belongs. Shopify renders the chosen template (for a JSON template, that means all its sections in order) and drops the HTML there.

flowchart LR
  R["Request<br/>/products/canvas-cap"] --> T["Pick template<br/>templates/product.json"]
  T --> S["Render its sections<br/>in order"]
  S --> C["HTML becomes<br/>content_for_layout"]
  C --> L["layout/theme.liquid<br/>wraps it"]
  L --> P["Full page sent<br/>to the browser"]

The template is rendered first; its HTML is then placed into the layout.

One consequence: the layout is rendered after the template, but Liquid variables do not travel between them. If a template needs to tell the layout something (for example "hide the header"), use a template.name or template.suffix check in the layout, or give that template a different layout.

The old content_for_index

In themes from before Online Store 2.0 you may see {{ content_for_index }}. It lived in templates/index.liquid (not the layout) and printed the home page's sections. JSON templates replaced it, so a modern theme does not use it. If you migrate an old theme, delete it (Migrating Legacy Themes).

Headers and footers: section groups

A layout can render section groups. A group is a JSON file in sections/ that lists sections, and the layout prints them with the sections tag (plural):

JSON
{
  "name": "Header",
  "type": "header",
  "sections": {
    "announcement": { "type": "announcement-bar", "settings": { "text": "Free shipping over $50" } },
    "header": { "type": "header", "settings": {} }
  },
  "order": ["announcement", "header"]
}

This is saved as sections/header-group.json. Inside the group the merchant can add, remove and reorder sections in the theme editor, exactly as on a template, and the choice applies to every page that uses the layout. The older way, a single {% section 'header' %}, renders one static section with fixed position; that still works but gives merchants less freedom (Building a Section explains static versus dynamic). Section groups can only be rendered from layout files, not from templates.

Other layouts

theme.liquid is the default, not the only layout. Any file in layout/ can be chosen by a template.

Layout file Typical use
theme.liquid Every normal page
password.liquid The storefront password page; Shopify uses it for the password template
landing.liquid (your own name) A stripped-down page without header and footer
checkout.liquid Legacy checkout customization. Deprecated: checkout is now extended through Checkout Extensibility, not a layout file

Two tags and one JSON key control the choice:

LIQUID
{% layout 'landing' %}

placed at the top of a Liquid template, selects layout/landing.liquid instead of theme.liquid. And

LIQUID
{% layout none %}

renders the template with no layout at all: only the template's own output is sent. That is useful for a printable gift card or a response that is not a normal HTML page. A JSON template cannot hold Liquid tags, so it states its layout as a top-level key instead:

JSON
{
  "layout": "landing",
  "sections": { "main": { "type": "main-page" } },
  "order": ["main"]
}

(Check the JSON template reference for the exact set of top-level keys your Shopify version accepts; at the time of writing layout and wrapper are among them.) The {% layout %} tag is not allowed inside sections or snippets: the layout is decided before sections render.

Why have more than one layout?

A landing page for an ad campaign usually should not offer the whole site menu. A password page should not load the cart. Instead of hiding things with CSS and conditionals in theme.liquid, give those pages their own layout file. It is cleaner and faster, because each layout only loads what it needs.

Stand-in 1: gluing a template into a layout

The first editor imitates the two required slots. It checks that a layout contains content_for_header in the head and content_for_layout, then renders a page by filling the slots and the section groups. The real Shopify does far more, but the contract is the same.

JS Filling the layout slots

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

No output.

Stand-in 2: which layout wins?

Shopify decides the layout from the template. The second editor models the rules from this lesson: the password page uses its own layout, a Liquid template can name a layout with {% layout %}, a JSON template can use a layout key, and everything else uses theme.

JS Choosing a layout

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

No output.

Practical advice

  • Keep theme.liquid short. Move big chunks into snippets or sections (render 'head-meta'), so the file stays readable.
  • Load scripts with defer and put them at the end of <body>, or use type="module", so they do not block rendering (Theme Performance).
  • Use request.design_mode to switch off things such as a sticky header animation while the merchant edits in the theme editor.
  • Use a separate layout when a page type needs a truly different frame, instead of piling conditions into theme.liquid.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where must {{ content_for_header }} appear in a layout?

    Shopify injects analytics, app embed code and editor helpers there. It is required, and it belongs in the head.
  2. 2. What does {{ content_for_layout }} contain?

    Shopify renders the template (for a JSON template, all of its sections) and places that HTML where content_for_layout appears.
  3. 3. How do you render a page with no layout at all, for example a printable gift card?

    The layout tag with the keyword none sends only the template's output.
  4. 4. Where are the sections of a header that merchants can add to, remove and reorder defined?

    A section group is a JSON file of sections, rendered from a layout with {% sections 'header-group' %}.

Summary

  • A layout in layout/ wraps every template; theme.liquid is the default.
  • A layout needs {{ content_for_header }} in the head and {{ content_for_layout }} in the body. Never remove, parse or filter the header content.
  • {{ content_for_layout }} receives the rendered template. content_for_index is a legacy object from pre-2.0 home page templates.
  • Headers and footers are best done as section groups (sections/header-group.json) rendered with {% sections 'name' %}.
  • Use {% layout 'name' %} in Liquid templates, a layout key in JSON templates, and {% layout none %} for no wrapper. The password page has its own layout.
  • Prefer a separate layout file over piling conditions into theme.liquid.

Next lesson: JSON Templates and Online Store 2.0.