Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 61 ยท Layouts, Templates and Sections

Building a Section

Build a Shopify theme section from scratch: file anatomy, the schema tag, setting types, presets, limits, enabled_on, static versus dynamic sections and section.id.

A section is the main building block of a Shopify theme: a self-contained piece of a page, such as a hero banner, a product grid, a testimonial strip or a footer. A section is one file in sections/ that combines three things: the HTML and Liquid that draw it, a schema that describes what the merchant can customize, and, optionally, its own CSS and JavaScript. The theme editor reads the schema and builds the settings panel for you, so you never write form code.

This lesson takes a section apart, writes one from scratch, and explains the rules that decide where it can appear. The real section code is read-only here. The editors run stand-ins in JavaScript: one reads a schema and renders a section the way the editor and Shopify would, the other applies the placement rules when a merchant adds a section from a preset.

What this lesson targets: Online Store 2.0 and current Shopify themes (section files, {% schema %}, presets). The JavaScript in the editors imitates Shopify's behavior; it is not Shopify's code and it skips most details such as translations and every setting type.

Anatomy of a section file

LIQUID
{%- comment -%} sections/feature-banner.liquid {%- endcomment -%}
<div
  class="feature-banner feature-banner--{{ section.settings.align }}"
  style="--banner-bg: {{ section.settings.background }}; --banner-pad: {{ section.settings.padding }}px;"
>
  {%- if section.settings.image != blank -%}
    {{ section.settings.image | image_url: width: 1200 | image_tag: loading: 'lazy', alt: section.settings.image.alt }}
  {%- endif -%}

  {%- if section.settings.heading != blank -%}
    <h2>{{ section.settings.heading | escape }}</h2>
  {%- endif -%}

  {{ section.settings.text }}

  {%- if section.blocks.size > 0 -%}
    <ul>
      {%- for block in section.blocks -%}
        <li {{ block.shopify_attributes }}>{{ block.settings.label | escape }}</li>
      {%- endfor -%}
    </ul>
  {%- endif -%}
</div>

{% stylesheet %}
  .feature-banner { background: var(--banner-bg); padding: var(--banner-pad); }
  .feature-banner--center { text-align: center; }
{% endstylesheet %}

{% schema %}
{
  "name": "Feature banner",
  "tag": "section",
  "class": "section-feature-banner",
  "limit": 2,
  "enabled_on": { "templates": ["index", "page", "collection"] },
  "settings": [
    { "type": "header", "content": "Content" },
    { "type": "text", "id": "heading", "label": "Heading", "default": "Fresh arrivals" },
    { "type": "richtext", "id": "text", "label": "Text" },
    { "type": "image_picker", "id": "image", "label": "Image" },
    { "type": "header", "content": "Style" },
    {
      "type": "select", "id": "align", "label": "Alignment", "default": "left",
      "options": [
        { "value": "left", "label": "Left" },
        { "value": "center", "label": "Center" }
      ]
    },
    { "type": "color", "id": "background", "label": "Background", "default": "#f4efe6" },
    { "type": "range", "id": "padding", "label": "Padding", "min": 0, "max": 80, "step": 4, "unit": "px", "default": 32 }
  ],
  "blocks": [
    {
      "type": "point",
      "name": "Selling point",
      "settings": [
        { "type": "text", "id": "label", "label": "Label", "default": "Free returns" }
      ]
    }
  ],
  "max_blocks": 6,
  "presets": [
    { "name": "Feature banner", "blocks": [{ "type": "point" }, { "type": "point" }] }
  ]
}
{% endschema %}

There are four parts:

  1. Markup. Ordinary Liquid. Everything the merchant can change arrives through the section object: section.settings.<id>, section.blocks, and section.id.
  2. {% stylesheet %} (optional). CSS that belongs to this section. Shopify collects these and loads them together; the CSS lesson explains when to prefer asset files.
  3. {% javascript %} (optional). JavaScript for the section, collected the same way.
  4. {% schema %}. One block of JSON that tells the editor what this section is. It cannot contain Liquid, there can be only one per file, and it must be valid JSON; a trailing comma breaks it.

The file name is the section's type, so feature-banner.liquid is type feature-banner.

The wrapper Shopify adds

You do not write the outer element. Shopify wraps your markup in a tag that carries the section's id:

HTML
<section id="shopify-section-template--123__feature" class="shopify-section section-feature-banner">
  ...your markup...
</section>

The schema's tag chooses the element (div by default; section, article, aside, header and footer are allowed) and class adds your own class. The id is how the theme editor finds the section to reload it after a change. Do not put a second id of the same kind on your root element, and remember that when a merchant edits a setting, Shopify replaces the inside of this wrapper with fresh HTML, so your JavaScript has to cope with that (see JavaScript in Themes).

section.id, static and dynamic

section.id is unique for the instance. For a section in a JSON template it is built from the template and the instance key (it looks like template--123__feature), so never hard-code it; use section.id to build element ids, CSS custom properties or data attributes that must be unique when the same section appears twice.

There are two ways a section reaches the page:

  • Dynamic: referenced from a JSON template or a section group. The merchant can add, reorder and delete it. It needs presets to appear in the editor's "Add section" list.
  • Static: rendered with {% section 'feature-banner' %} in a Liquid file. It is there for everyone, in a fixed place, and cannot be moved or deleted in the editor. Its saved settings live in the theme's data files rather than in a template. Add a default object to the schema to give it initial settings and blocks, because it has no preset to start from:
JSON
"default": {
  "settings": { "heading": "Welcome" },
  "blocks": [{ "type": "point" }]
}

Use static sections for parts of a layout that must always exist; use dynamic ones for everything merchants should control.

flowchart LR
  P["Preset in the schema"] -->|"merchant clicks Add section"| D["New instance in a JSON template<br/>with its own id and settings"]
  F["section tag in a Liquid file"] -->|"always rendered, fixed place"| S["Static instance<br/>initial values from default"]
  D --> R["Rendered with section.settings"]
  S --> R

Presets create dynamic instances; the section tag creates a static one.

Schema keys worth knowing

Key What it does
name The label in the editor (required)
tag, class The wrapper element and extra CSS class
settings The array of settings; each has type, usually id, and label
blocks, max_blocks The block types a section accepts, and how many at most (50 unless you lower it)
presets Makes the section addable in the editor; can pre-fill settings and blocks
default Initial settings for a static section
limit Max number of this section per template (Shopify only allows small values such as 1 or 2)
enabled_on / disabled_on Restrict to templates or groups, for example { "templates": ["product"] }; use one, not both

The most used setting types are text, textarea, richtext, image_picker, color, range, select and checkbox. Each setting's id must be unique in the section and is the name you use in Liquid. Types, and what Liquid receives for each, are covered in Schema Settings in Depth.

Habits that keep sections robust

  • Expect empty. Merchants clear fields. Guard optional output with != blank and never assume an image exists.
  • Escape text settings. A text setting is plain text: output it with | escape. A richtext setting already comes back as safe HTML, so do not escape it.
  • Give defaults. A section with good defaults looks right the moment it is added.
  • Keep markup self-contained. A section should not depend on another section being on the page.
  • Name for the merchant. Feature banner in the editor beats feature-banner-v2.

Stand-in 1: rendering a section from its schema

This editor does in miniature what Shopify does for the editor and the storefront. It validates a schema (unknown types, duplicate ids, missing defaults on ranges), merges the merchant's saved values with the schema defaults, clamps values the way the range control would, and renders the wrapper and markup. The markup is a JavaScript function standing in for Liquid.

JS Render a section from its schema

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

No output.

Stand-in 2: where may this section go?

When a merchant opens "Add section", Shopify lists only the sections allowed in the current place and creates instances from the preset. The second editor applies the placement rules from this lesson: a preset must exist, enabled_on or disabled_on must allow the template, limit caps the number of instances, and max_blocks caps the blocks. Error messages here are our wording.

JS Add a section from a preset

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is required before a section can be added from the editor's "Add section" list?

    Sections appear in the Add section list when their schema has at least one preset. Without presets they can still be rendered as static sections.
  2. 2. What does section.id help you do?

    section.id is unique per instance, so it is the safe way to make ids and CSS hooks unique. Never hard-code it.
  3. 3. Which output rule is correct for settings?

    A text setting is plain text, so you escape it. A richtext setting is already sanitized HTML; escaping it would show the tags.
  4. 4. How is a static section rendered?

    The section tag renders one fixed instance. Merchants can edit its settings but cannot move or delete it.

Summary

  • A section is one file in sections/ with Liquid markup, optional {% stylesheet %} and {% javascript %}, and a {% schema %} JSON block.
  • Shopify wraps the markup in an element with id="shopify-section-{{ section.id }}"; tag and class in the schema shape that wrapper.
  • Settings live in section.settings, blocks in section.blocks. Guard against empty values and escape plain-text settings.
  • Presets make a section addable; limit, max_blocks, enabled_on and disabled_on control where and how often.
  • Dynamic sections come from JSON templates and groups; static sections come from {% section %} and use default for initial values.
  • Never hard-code section.id.

Next lesson: Blocks and Theme Blocks.