Skip to main content

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.

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.

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.

Theme block files contain markup.

The markup is any HTML or Liquid content that you want to include in the block.

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.

Tip
At this step, you'll be able to reference the theme block in a section file with block targeting. To make this block display in the theme editor's block picker, you need to add a block preset.

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.

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

"presets": [
{ "name": "Text" },
{
"name": "Content",
"settings": {
"text": "Hello, World!"
}
}
]

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.

Tip
Sections can either define blocks locally or opt-in to supporting theme blocks, but they can't support both simultaneously.

Anchor to Render the blocks in LiquidRender the blocks in Liquid

Render the blocks in Liquid using

Render blocks in liquid

{% content_for 'blocks' %}

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

"blocks": [{ "type": "@theme" }, { "type": "@app" }],

Anchor to Nest blocks in theme blocksNest blocks in theme blocks

Theme blocks can accept other theme and app blocks as children.
Theme blocks can contain multiple levels of nested blocks

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

{
"name": "Column",
"settings": {
"color_scheme": "scheme-3"
},
"blocks": [
{
"type": "text",
"settings": {
"text": "<h3>Hello, world!</h3>"
}
},
{
"type": "text",
"settings": {
"text": "<p>How's it going?<\/p>"
}
}
]
}

Each block's content is rendered by the liquid tag

Render blocks in liquid

{% content_for 'blocks' %}

The content is rendered in the order that's stored in the JSON template. This is the same rendering mechanism sections use for blocks.

Tip
Block presets can refer to other theme blocks within the theme. This example refers to the /blocks/text.liquid Liquid file created earlier in this tutorial. Learn more about theme block presets.
Was this page helpful?