Theme blocks

Theme blocks are Liquid files that are defined in the blocks directory of the theme:

Theme block files can contain markup and a schema:

To create a theme block, add a Liquid file in the /blocks folder of your theme. If your theme doesn't have a /blocks folder yet, then add one at the root of your theme.

The following example creates a Text block that can be reused across different sections and blocks of the theme:

Theme blocks have the same access to global objects, tags, and filters as other Liquid theme files, as well as the block object, which contains the properties and setting values of the block.

Aside from global objects, variables created outside of blocks aren't accessible within theme blocks. This means that, unlike section-defined blocks, theme blocks can't access the section object or variables created within their parent section Liquid file.

You can render a theme block in a section or another theme block in the following ways:

• Dynamically rendered in Liquid via {% content_for 'blocks' %}.
• Statically rendered in Liquid, setting the type explicitly using {% content_for “block”, type: “<type>”, id: “<id>” %}. Merchants will not be able to delete or re-order statically rendered blocks.

After theme blocks are defined in your theme, you can update the schema of the sections where you want to accept theme blocks. In a section, theme developers can choose to:

1. Accept all theme blocks for use
2. Select specific theme blocks for use
3. Exclude specific theme blocks from use

To accept all theme blocks in a section by adding a generic entry of type @theme to the blocks attribute of the schema of that section.

In the following example, the Section will have access to all theme blocks.

To accept specific theme blocks, theme developers can explicitly reference blocks in their schema. In the following example, the Slideshow section will have access to only the Slide theme block. In the editor, the block picker for Slideshow will only have a single block: slide. By default, theme blocks are available in all sections and theme blocks. In this example, the slide block will be in the block picker for all sections, not just the slideshow section.

There are cases where you might want to limit the blocks that are available in sections. For example, slides are a type of block that should only be available in slideshow sections. To prevent the default behavior, theme developers can name the block with an underscore prefix.

In this case, slide.liquid can be renamed to _slide.liquid. All underscore prefixed blocks would be excluded from appearing in the block picker for blocks and sections that accept blocks with type @theme. Those blocks and sections will need to explicitly add the block by base filename. Ex: “blocks”: [ { “type”: “_slide” } ]

Theme blocks can accept other theme and app blocks as children using the blocks attribute of their schema and assemble different configurations of these child blocks using the presets attribute.

The following is an example of including nested blocks using a block's presets attribute, and using the {% content_for 'blocks' %} Liquid tag to render the markup of the nested blocks:

Each block's content is outputted by the {% content_for 'blocks' %} tag in the order that's stored in the JSON template.

Learn more about nesting theme blocks and presets.