Theme sections

The sections folder contains a theme's sections. Sections are reusable, customizable modules of a page that can be rendered in templates and layouts. Each section is a Liquid file that pairs markup with a schema, letting merchants configure the section's content and appearance directly from the theme editor without touching code.

Rendering a section

Include a section in a layout or template with the section tag. The tag takes the section's file name (without the .liquid extension) as a string. For example, layout/theme.liquid renders the shared header and footer sections:

{% section 'header' %}
{{ content_for_layout }}
{% section 'footer' %}

Templates render their own sections in the same way, for example templates/product.liquid renders the main-product section:

{% section 'main-product' %}

Section schema

Every section can define a schema inside a {% schema %} tag. The schema is a single JSON object that tells the theme editor how the section can be configured. The following top-level keys are used across this theme's sections:

name

The section title shown in the theme editor. Accepts a plain string or a localized label object.

settings

An array of input settings that let merchants configure the whole section (for example an image, a color, or a toggle). See Settings below.

blocks

An array of block types that merchants can add, remove, and reorder within the section. See Blocks and presets below.

presets

The default configuration applied when the section is first added, including which blocks appear by default. See Blocks and presets below.

max_blocks

The maximum number of blocks a merchant can add to the section, for example "max_blocks": 6.

limit

Limits how many times the section itself can be added to a template. Also used on an individual block type to cap how many of that block are allowed (for example "limit": 1).

class

Additional CSS class(es) applied to the section's wrapper element, for example "class": "spaced-section".

tag

The HTML tag used for the section's wrapper element, for example "tag": "section".

Settings

Each entry in the settings array is an input the merchant can edit. Common attributes are:

• type — the input type (see the list below).
• id — the unique key used to read the value in Liquid, for example section.settings.image.
• label — the field label shown in the editor.
• default — the initial value.
• info — an optional helper hint shown below the field.
• options — the list of choices for a select input.

The section schemas in this theme use the following input type values:

• text — a single-line text field.
• checkbox — a boolean toggle (its default is true or false).
• select — a dropdown; requires an options array of value/label pairs.
• color — a color picker.
• image — an image picker.
• range — a slider that takes min, max, step, and unit.
• header — a non-editable section header used to group related settings.

A range setting from this theme, showing its numeric attributes:

{
  "type": "range",
  "id": "image_overlay_opacity",
  "min": 0,
  "max": 100,
  "step": 10,
  "unit": "%",
  "label": "Image Overlay Opacity",
  "default": 0
}

A select setting supplies its choices through options:

{
  "type": "select",
  "id": "desktop_text_box_position",
  "options": [
    { "value": "flex-start", "label": "Top" },
    { "value": "center", "label": "Center" },
    { "value": "flex-end", "label": "Bottom" }
  ],
  "default": "center",
  "label": "Text Position"
}

Read a section setting in Liquid through the section.settings object using the setting's id:

{{ section.settings.image | img_url: '1500x' }}

Blocks and presets

Blocks are merchant-addable modules within a section. Each block type declares its own type, name, an optional limit, and its own settings. In Liquid, iterate a section's blocks with section.blocks_order and read each block's settings by its handle.

Presets make a section available in the theme editor's "Add section" menu and describe its default state, including which blocks are added by default. The presets array holds one or more named configurations.

A trimmed schema from sections/image-banner.liquid showing settings, blocks, and presets together:

{
  "name": "Image Banner",
  "settings": [
    { "type": "image", "id": "image", "label": "Background" },
    {
      "type": "checkbox",
      "id": "show_text_box",
      "default": true,
      "label": "Show Text Box"
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "name": "Heading",
      "limit": 1,
      "settings": [
        { "type": "text", "id": "heading", "default": "Image Banner", "label": "Title" }
      ]
    },
    {
      "type": "text",
      "name": "Text",
      "limit": 1,
      "settings": [
        { "type": "text", "id": "text", "label": "Text" }
      ]
    },
    {
      "type": "buttons",
      "name": "Button",
      "limit": 1,
      "settings": [
        { "type": "text", "id": "button_label_1", "default": "Button label", "label": "Button Label" }
      ]
    }
  ],
  "presets": [
    {
      "name": "Image Banner",
      "blocks": [
        { "type": "heading" },
        { "type": "text" },
        { "type": "buttons" }
      ]
    }
  ]
}

The matching Liquid loops over the section's blocks and renders each one by its type:

{% for block_handle in section.blocks_order %}
  {% assign blocks = section.blocks %}
  {% case blocks[block_handle].type %}
    {% when 'heading' %}
      <h2>{{ blocks[block_handle].settings.heading | escape }}</h2>
    {% when 'text' %}
      <div>{{ blocks[block_handle].settings.text | escape }}</div>
  {% endcase %}
{% endfor %}

Localized labels

The name, label, and default values accept an inline multi-language object instead of a plain string. Each key is a locale code and its value is the translated text, so the theme editor displays the right language for the merchant. The available locales are en_US, zh_TW, zh_CN, and ms_MY.

{
  "name": {
    "en_US": "Image Banner",
    "zh_TW": "圖面橫幅",
    "zh_CN": "图面横幅",
    "ms_MY": "Sepanduk imej"
  }
}

The same object form is used for a setting's label and default:

{
  "type": "text",
  "id": "heading",
  "default": {
    "en_US": "Image Banner",
    "zh_TW": "輪播圖面",
    "zh_CN": "轮播图面",
    "ms_MY": "Sepanduk imej"
  },
  "label": {
    "en_US": "Title",
    "zh_TW": "標題",
    "zh_CN": "标题",
    "ms_MY": "tajuk"
  }
}

Related

Theme-wide settings that apply outside of any single section are defined in settings_schema.json.