- Schema
- Content
Sections support the {% schema %} Liquid tag. This tag allows you to define various attributes of a section, such as the section name, any section blocks, and settings to allow for theme editor customization options.
Schema
Anchor link to section titled "Schema"
Each section can have only a single {% schema %} tag, which must contain only valid JSON using the attributes listed in Content. The tag can be placed anywhere within the section file, but it can’t be nested inside another Liquid tag.
The following is an example of a valid section schema. For details on each attribute, refer to Content.
Content
Anchor link to section titled "Content"
The content of {% schema %} can include the following attributes:
- name
- tag
- class
- limit
- settings
- blocks
- max_blocks
- presets
- default
- locales
In addition, you can use one of the following attributes to specify where a section can be used:
- enabled_on: Limit a section to specific templates and section groups.
- disabled_on: Prevent a section from being used in specific templates and section groups.
You should also consider making your section compatible with app blocks. App blocks allow app developers to create blocks for merchants to add app content to their theme without having to directly edit their theme code.
name
Anchor link to section titled "name"
The name attribute determines the section title that is shown in the theme editor. For example, the following schema returns the following output:
tag
Anchor link to section titled "tag"
By default, when Shopify renders a section, it’s wrapped in a <div> element with a unique id attribute:
If you don’t want to use a <div>, then you can specify which kind of HTML element to use with the tag attribute. The following are the accepted values:
articleasidedivfooterheadersection
For example, the following schema returns the following output:
class
Anchor link to section titled "class"
When Shopify renders a section, it’s wrapped in an HTML element with a class of shopify-section. You can add to that class with the class attribute:
limit
Anchor link to section titled "limit"
By default, there's no limit to how many times a section can be added to a template or section group. You can specify a limit of 1 or 2 with the limit attribute:
settings
Anchor link to section titled "settings"
You can create section specific settings to allow merchants to customize the section with the settings object:
Access section settings
Anchor link to section titled "Access section settings"
Section settings can be accessed through the section object. Refer to Access settings to learn more.
blocks
Anchor link to section titled "blocks"
You can create blocks for a section. Blocks are reusable modules of content that can be added, removed, and reordered within a section.
Blocks have the following attributes:
| Attribute | Description | >Required |
|---|---|---|
type | The block type. This is a free-form string that you can use as an identifier. You can access this value through the type attribute of the block object. | Yes |
name | The block name, which will show as the block title in the theme editor. | Yes |
limit | The number of blocks of this type that can be used. | No |
settings | Any input or sidebar settings that you want for the block. Certain settings might be used as the title of the block in the theme editor. | No |
The following is an example of including blocks in a section:
Access block settings
Anchor link to section titled "Access block settings"
Block settings can be accessed through the block object. Refer to Access settings to learn more.
Render blocks
Anchor link to section titled "Render blocks"
You can render a section's blocks by looping over the blocks attribute of the section object:
... {% endcase %}{% endfor %}
In the example above, each block's content is included inside a parent container, and that container has {{ block.shopify_attributes }} added as an attribute. Shopify's theme editor uses that attribute to identify blocks in its JavaScript API.
If your block is a single element, then ensure that the element has this attribute.
Show dynamic block titles in the theme editor
Anchor link to section titled "Show dynamic block titles in the theme editor"
In certain cases, the theme editor can display an input setting value as the title of a block in the theme editor sidebar. This can help merchants to identify and rearrange blocks in a section.
The theme editor checks the id values of the settings in a block to determine the best one to use for the block title.
The theme editor uses settings with the following id values, in order of precedence:
headingtitletext
If a setting with a matching id value doesn't exist, then the block name is used as the title.
For example, this block with a setting id of heading displays in the sidebar with the title Welcome to our store.
max_blocks
Anchor link to section titled "max_blocks"
There’s a limit of 50 blocks per section. You can specify a lower limit with the max_blocks attribute:
presets
Anchor link to section titled "presets"
Presets are default configurations of sections that enable users to easily add a section to a JSON template through the theme editor. Presets aren't related to theme styles that are defined in settings_data.json.
Presets have the following attributes:
| Attribute | Description | >Required |
|---|---|---|
name | The preset name, which will show in the Add section picker of the theme editor. | Yes |
settings | A list of default values for any settings you might want to populate. Each entry should include the setting name and the value. | No |
blocks | A list of default blocks that you might want to include. Each entry should be an object with attributes of type and settings. The type attribute value should reflect the type of the block that you want to include, and the settings object should be in the same format as the settings attribute above. | No |
The following is an example of including presets in a section:
default
Anchor link to section titled "default"
If you statically render a section, then you can define a default configuration with the default object, which has the same attributes as the preset object.
The following is an example of including a default in a section:
locales
Anchor link to section titled "locales"
Sections can provide their own set of translated strings through the locales object. This is separate from the locales directory of the theme, which makes it a useful feature for sections that are meant to be installed on multiple themes or shops.
The locales object has the following general format:
For example:
Any translations will show up under the Sections tab of the language editor for merchants to edit. When edits are made, the changes are saved directly to the applicable locale file, and the section schema is unchanged.
These translations can be accessed through the Liquid translation filter (t filter) where the key will be in the following format:
For example, if you want to reference the title translation from the example above, then use the following:
enabled_on
Anchor link to section titled "enabled_on"
You can restrict a section to certain template page types and section group types by specifying them through the enabled_on attribute.
enabled_on, along with disabled_on, replaces the templates attribute.
enabled_on must have at least one of the following attributes:
| Attribute | Description |
|---|---|
templates | A list of the template page types where the section can be used. Accepted values:
|
groups | A list of the section groups where the section can be used. Accepted values:
|
In the following example, the section is available to all templates, and to the footer section group:
disabled_on
Anchor link to section titled "disabled_on"
You can prevent a section from being used on certain template page types and section group types by setting them in the disabled_on attribute. When you use disabled_on, the section is available to all templates and section groups except the ones that you specified.
disabled_on, along with enabled_on, replaces the templates attribute.
disabled_on must have at least one of the following attributes:
| Attribute | Description |
|---|---|
templates | A list of the template page types where the section can't be used. Accepted values:
|
groups | A list of the section groups where the section can't be used. Accepted values:
|
In the following example, the section is available to all templates other than password templates, and to all section groups other than footer section groups.
App blocks
Anchor link to section titled "App blocks"
If your section is part of a JSON template or section group, then you should support blocks of type @app. App blocks allow app developers to create blocks for merchants to add app content to their theme without having to directly edit theme code.
