Section schema
Every section can include a single {% schema %} tag containing a JSON object. This schema tells the theme editor the section's name, what settings and blocks it exposes, and which templates it can be added to.
{% schema %}
{
"name": "Featured products",
"settings": [],
"blocks": []
}
{% endschema %}Note: The schema must be valid JSON. Only one
{% schema %}tag is allowed per section, and it can't contain Liquid.
Attributes
| Attribute | Type | Description |
|---|---|---|
name | string | Required. The section name shown in the theme editor. Can be a t: locale key. label is accepted as a deprecated alias. |
tag | string | The HTML element the section is wrapped in. One of article, aside, div, footer, header, or section. Defaults to section. |
class | string | A class added to the section wrapper element. |
limit | integer | The maximum number of times the section can be added to a single template. Defaults to 25, and can't exceed 25. |
max_blocks | integer | The maximum number of blocks the section can hold. Defaults to 25, and can't exceed 25. |
settings | array | Setting definitions for the section, read through section.settings. |
blocks | array | The block types the section accepts. |
presets | array | The ready-made versions of the section that sellers can pick. See presets. |
enabled_on | object | The templates and section groups the section can be added to. See enabled_on and disabled_on. |
disabled_on | object | The templates and section groups the section cannot be added to. See enabled_on and disabled_on. |
templates | array | The template types the section can be added to from the editor. When omitted, the section is available on all templates. |
settings
An array of setting schema objects. Each entry renders an input (or a display element) in the theme editor.
"settings": [
{ "type": "header", "content": "Layout" },
{
"type": "select",
"id": "layout",
"label": "Layout",
"options": [
{ "value": "grid", "label": "Grid" },
{ "value": "carousel", "label": "Carousel" }
],
"default": "grid"
},
{
"type": "range",
"id": "products_per_row",
"label": "Products per row",
"min": 2,
"max": 5,
"step": 1,
"default": 4
}
]Values are read in Liquid through section.settings:
{% if section.settings.layout == 'carousel' %}
...
{% endif %}See Input settings and Display settings for the available types.
blocks
An array of the block types a section accepts. Each block has its own settings array.
"blocks": [
{
"type": "product",
"name": "Product",
"limit": 12,
"settings": [
{ "type": "product", "id": "product", "label": "Product" }
]
}
]| Property | Type | Description |
|---|---|---|
type | string | Required. Identifier for the block type, referenced as block.type in Liquid. |
name | string | Required, except for the @app type. The block name shown in the editor. Can be a t: locale key. label is accepted as a deprecated alias. |
limit | integer | The maximum number of blocks of this type allowed in the section. Defaults to 50, and can't exceed 50. |
settings | array | Setting definitions for the block, read through block.settings. |
Iterate blocks in the section markup, branching on block.type:
{% for block in section.blocks %}
{% case block.type %}
{% when 'product' %}
<div {{ block.youcan_attributes }}>
{{ block.settings.product.title }}
</div>
{% endcase %}
{% endfor %}See Blocks for the full rendering and theme-editor details.
To accept theme blocks, use entries with only a type: @theme for all public theme blocks, the type of a theme block, or @app for app blocks. A section schema cannot have both theme block entries and its own block types.
"blocks": [
{ "type": "@theme" },
{ "type": "@app" }
]presets
A preset is a ready-made version of the section. Sellers pick a preset in the theme editor to add the section, and each preset is listed as its own entry.
"presets": [
{
"name": "Image banner",
"category": "Banners",
"settings": { "height": "large" },
"blocks": [
{ "type": "heading", "settings": { "heading": "Browse our latest products" } },
{ "type": "button", "settings": { "label": "Shop all" } }
]
}
]| Property | Type | Description |
|---|---|---|
name | string | Required. The preset name shown in the theme editor. Can be a t: locale key. label is accepted as a deprecated alias. |
category | string | The group the preset is listed under in the theme editor. Can be a t: locale key. |
settings | object | Setting values for the section, keyed by setting id. Settings that are not in the preset get their default value. |
blocks | array | object | The blocks added with the preset. Each block has a type, and can have settings. A theme block can also have blocks, static and id. |
block_order | array | The order of the blocks, when blocks is an object. |
enabled_on and disabled_on
Use enabled_on to list the templates and section groups a section can be added to, or disabled_on to list the ones it cannot be added to. Only one of the two can be used in a section. Use "*" for all templates or all groups.
"enabled_on": {
"templates": ["index", "product"],
"groups": ["header"]
}"disabled_on": {
"templates": ["cart"]
}| Property | Type | Description |
|---|---|---|
templates | array | Template types, or "*". |
groups | array | Group types (header, footer, aside, custom.<name>), or "*". |
With enabled_on, the section is not offered on a template or a group that is not listed. When templates is not set in enabled_on, the section is not offered on any template. When groups is not set in enabled_on, the section is not offered in any group.
templates
Lists the template types a section can be added to from the theme editor. Omit it to make the section available everywhere.
"templates": ["index", "product", "page"]Example
{% schema %}
{
"name": "Featured collection",
"tag": "section",
"class": "featured-collection",
"limit": 2,
"max_blocks": 4,
"templates": ["index", "collection"],
"settings": [
{ "type": "text", "id": "heading", "label": "Heading", "default": "Featured collection" },
{ "type": "collection", "id": "collection", "label": "Collection" },
{ "type": "range", "id": "products_to_show", "label": "Products to show", "min": 2, "max": 12, "step": 1, "default": 6 }
],
"blocks": [
{
"type": "cta",
"name": "Call to action",
"limit": 1,
"settings": [
{ "type": "text", "id": "label", "label": "Button label" },
{ "type": "url", "id": "link", "label": "Button link" }
]
}
]
}
{% endschema %}