Quick Start
Learn how to build a basic theme block and add it to a section and another block file.
Theme blocks are blocks that are defined at the theme level. You can reuse theme blocks across different sections of the theme, unlike section-defined blocks that can only be used within the section where they're defined. Additionally, theme blocks can be nested within other theme blocks to create hierarchy.
Requirements
Project
Anchor to Create a theme blockCreate a theme block
At the end of this tutorial, you should have a text block that can be reused across different sections and blocks of the theme. You will add it to a Custom Section and a Group block.
Anchor to Add a blocks folderAdd a blocks folder
Theme blocks are Liquid files that are defined in the blocks
directory of the theme. 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.
Add a text.liquid
file to the /blocks
folder.
Anchor to Write the markupWrite the markup
Theme block files contain markup.
The markup is any HTML or Liquid content that you want to include in the block.
Anchor to Write the schemaWrite the schema
Theme block files contain a schema.
The schema is the {% schema %}
Liquid tag, which is used to configure settings and attributes of the block. Learn how to write block schema.
Anchor to Use Liquid objects in blocksUse Liquid objects in blocks
Blocks use a few key liquid objects:
- Theme blocks reference a
block
object, which contains the properties and setting values of the block. - Theme blocks can reference the
section
object of the section that rendered the theme block. - Theme blocks have access to global objects.
In this Text block example, this block references the settings attribute of the block object.
Theme blocks cannot access variables created outside the block and cannot be passed variables like when using a snippet.
Anchor to Add a block presetAdd a block preset
Presets need to be defined in order for the theme block to be available for merchants in the theme editor block picker. You can author multiple presets for the same theme block.
In this example, the text theme blocks has two presets called Text and Content.
Block presets
Anchor to Use theme blocks in sectionsUse theme blocks in sections
After theme blocks are defined in your theme, you need to update the theme's sections to render blocks.
Anchor to Render the blocks in LiquidRender the blocks in Liquid
Render the blocks in Liquid using
Render blocks in liquid
Anchor to Update the section schemaUpdate the section schema
To accept all theme blocks in a section, add the type @theme
to the blocks attribute of the schema of that section. To be more restrictive about which blocks can be use in specific sections, use block targeting.
blocks attribute
Anchor to Nest blocks in theme blocksNest blocks in theme blocks
Theme blocks can accept other theme and app blocks as children.

Theme blocks use the blocks
attribute of their schema and assemble different configurations of these child blocks using the presets
attribute.
In this example, the Group block has a preset called Column which is nesting the Text block using the presets
attribute.
Group block's Column preset nests Text blocks
Each block's content is rendered by the liquid tag
Render blocks in liquid
The content is rendered in the order that's stored in the JSON template. This is the same rendering mechanism sections use for blocks.
/blocks/text.liquid
Liquid file created earlier in this tutorial. Learn more about theme block presets.Anchor to Next StepsNext Steps
The examples above demonstrate basic theme blocks usage. Theme blocks support several more advanced features to enhance the merchant experience as well as provide flexibility to theme developers.
Learn how to configure theme block settings and attributes through their schema.
Learn how to use targeting in order to restrict which theme blocks can be added by merchants to sections and blocks that accept nested blocks.
Learn how to have stricter control over the layout of theme blocks and sections using static blocks.
Learn how to enable more flexibility for merchants by connecting theme blocks to dynamic sources.