Block schema
Theme blocks support the {% schema %} Liquid tag. This tag is used to define the following block attributes and settings:
These attributes and settings enable different customization options and preconfigurations of the block inside the theme editor.
The following is an example of a block schema that opts-in to supporting nested blocks with its block attribute, defines some background-related settings, and assembles different variations of those settings with its presets attribute:
Each block can have only a single {% schema %} tag, which must contain only valid JSON and can only use the attributes listed below. The schema tag can be placed anywhere within the block file, but it can’t be nested inside another Liquid tag. It doesn’t output its contents, or render any Liquid included inside it.
The name attribute determines the block title that's shown in the theme editor. For example, the following schema returns the following output:
Showing dynamic block titles in the theme editor
Anchor link to section titled "Showing dynamic block titles in the theme editor"In specific 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 the following 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, the following block with a setting id of text displays in the sidebar with the title Welcome to our store.
You can create block-specific settings to enable merchants to customize the block with the settings object:
Accessing block settings
Anchor link to section titled "Accessing block settings"Block settings can be accessed through the block object. Refer to Access settings to learn more.
Theme blocks can accept other app and theme blocks as children using the blocks attribute of their schema:
The "@theme" type denotes that this block is compatible with other theme-defined blocks that live in the /blocks folder of the theme, while the "@app" type is used to denote that this block accepts app blocks. App blocks enable app developers to create blocks for merchants to add app content to their theme without having to directly edit theme code.
Rendering nested blocks
Anchor link to section titled "Rendering nested blocks"You can render a block's child blocks by using the {% content_for 'blocks' %} Liquid tag:
In the example above, each block's content is outputted by the {% content_for 'blocks' %} tag in the order stored in the JSON template.
Presets are default configurations of blocks that enable merchants to easily add a block to a JSON template through the theme editor. A block can have multiple different presets that combine its settings in a variety of different configurations. Additionally, presets of a block may reference other child blocks and assemble them in any number of configurations.
Presets have the following attributes:
| Attribute | Description | Required |
|---|---|---|
name
|
The preset name, which displays in the Add block picker of the theme editor. | Yes |
settings
|
A list of default values for any settings that you might want to populate. Each entry should include the setting name and the value. | No |
blocks
|
A list of child 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 block, assuming that the theme also contains a text block located in the /blocks/text.liquid Liquid file:
By default, when Shopify renders a block, 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.
For example, the following schema returns the following output:
Rendering blocks without a wrapper
Anchor link to section titled "Rendering blocks without a wrapper"In some advanced use cases, you might want more control over the tag and the attributes that are passed to it. For example, dynamically setting a tag or class name based on the settings of the block. In these scenarios, you can render blocks without a wrapper by setting the tag attribute to null.
When the tag attribute is set to null, Shopify doesn't wrap the contents of the block in a wrapper element, and instead directly outputs the contents of the block.
For blocks to be compatible with the theme editor, the top level HTML element must be tagged with the {{ block.shopify_attributes }} Liquid tag. This adds the necessary data attributes for the block to be identified by the theme editor. Shopify's theme editor uses that attribute to identify blocks in its JavaScript API.
When Shopify renders a block, it’s wrapped in an HTML element with the shopify-block class. You can append other classes by using the class attribute: