Section schema

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.

Content

The content of {% schema %} can include the following attributes:

• name
• tag
• class
• limit
• settings
• blocks
• max_blocks
• presets
• default
• locales
• templates

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

The name attribute determines the section title that is shown in the theme editor. For example, the following schema returns the following output:

Output

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:

• article
• aside
• div
• footer
• header
• section

For example, the following schema returns the following output:

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

By default, there's no limit to how many times a section can be added to a template. You can specify a limit of 1 or 2 with the limit attribute:

settings

You can create section specific settings to allow merchants to customize the section with the settings object:

Access section settings

Section settings can be accessed through the section Liquid object. Refer to Access settings to learn more.

Section title

The theme editor creates section titles based on the setting input types. If you want to explicitly set which input will control this title, then you can set that input’s id attribute to title:

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:

The following is an example of including blocks in a section:

Access block settings

Block settings can be accessed through the block Liquid object. Refer to Access settings to learn more.

Render blocks

You can render a section's blocks by looping over the blocks attribute of the section object:

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

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:

1. heading
2. title
3. text

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

There’s a limit of 16 blocks per section. You can specify a lower limit with the max_blocks attribute:

Example

presets

Section presets are default configurations of sections that allow merchants to easily add a section to a JSON template through the theme editor. They aren't related to theme styles that are defined in settings_data.json.

The presets object has the following attributes:

The following is an example of including presets in a section:

Example

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

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:

templates

You can restrict a section to certain templates by specifying those templates through the templates attribute. This attribute accepts a list of strings that represent the page type.

For example:

App blocks

If your section is part of a JSON template, then you should support blocks of type @app. These blocks allow app developers to create blocks for merchants to add app content to their theme without having to directly edit theme code.

To support app blocks, you need to do three things:

• Add the necessary schema
• Render the block content
• Ensure you have valid section settings

Additionally, you can create an app block wrapper section.

App block schema

Blocks of type @app need to be included in the section schema. For example:

Render app blocks

To render an app block, you need to check for the appropriate type, and use the following code:

For example:

App blocks and section settings

To prevent ambiguity with autofill settings, sections that will support app blocks can only include one resource setting of each type as a section setting. For example, you can only have one product setting, one collection setting, etc.

App block wrapper

App blocks can be added to a page in two ways:

• As a block within the confines of the section that's rendering the block
• In a similar manner to sections, giving them the full width of the page to render content

As app blocks aren't sections themselves, Shopify wraps these full-width app blocks in a platform-generated section by default. However, you can override this default section by creating your own section called apps.liquid.

The apps.liquid section schema needs to include a block of type @app, as well as a preset. If either of these is missing, then an Apps not supported or Apps section is invalid error is returned in the theme editor and merchants aren't able to use the section.

For example:

To allow merchants to control how the app looks inside of an app section, you can add a setting that lets merchants add margins around the app blocks. This helps make the app section margins consistent with your theme's layout.