Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 61 ยท Layouts, Templates and Sections

Blocks and Theme Blocks

Learn Shopify blocks: section blocks and shopify_attributes, reusable theme blocks in /blocks, nested blocks, the @theme and @app types, block settings, limits and ordering.

A section gives the merchant a place on the page. Blocks give them the pieces to put inside it. A slideshow section holds slide blocks, a features section holds icon-and-text blocks, a product page's buy area holds a title block, a price block and a button block. Merchants add, remove, reorder and customize blocks without touching code, and every block can have its own settings.

Shopify has two block models. Section blocks (the original) are defined inside one section's schema and belong to that section. Theme blocks are newer: each is its own file in the blocks/ folder, reusable across sections, and they can be nested inside each other. This lesson covers both, plus the special @theme and @app types, block.shopify_attributes, settings, ordering and limits.

What this lesson targets: current Shopify themes, including theme blocks (the blocks/ folder and the content_for tag), which build on Online Store 2.0. The Liquid and JSON in the plain blocks are read-only. The editors are JavaScript stand-ins: a renderer that walks a nested block tree, and a function that applies the schema's acceptance and limit rules. They imitate the behavior; they are not Shopify's engine, and details such as nesting depth limits are best checked in the current documentation.

Section blocks

A section block is declared in the section's schema with a type, a name and its own settings. In Liquid you loop over section.blocks:

LIQUID
<div class="cta">
  {%- for block in section.blocks -%}
    {%- case block.type -%}
      {%- when 'heading' -%}
        <h2 {{ block.shopify_attributes }}>{{ block.settings.text | escape }}</h2>
      {%- when 'button' -%}
        <a class="button" href="{{ block.settings.link }}" {{ block.shopify_attributes }}>
          {{ block.settings.label | escape }}
        </a>
    {%- endcase -%}
  {%- endfor -%}
</div>

{% schema %}
{
  "name": "Call to action",
  "blocks": [
    {
      "type": "heading",
      "name": "Heading",
      "settings": [{ "type": "text", "id": "text", "label": "Text", "default": "Join us" }]
    },
    {
      "type": "button",
      "name": "Button",
      "limit": 2,
      "settings": [
        { "type": "text", "id": "label", "label": "Label", "default": "Shop now" },
        { "type": "url", "id": "link", "label": "Link" }
      ]
    }
  ],
  "max_blocks": 6,
  "presets": [{ "name": "Call to action", "blocks": [{ "type": "heading" }, { "type": "button" }] }]
}
{% endschema %}

Each block gives you block.type, block.id, block.settings and block.shopify_attributes. The last one matters more than it looks.

block.shopify_attributes

{{ block.shopify_attributes }} prints data attributes that the theme editor relies on. When a merchant clicks a block in the sidebar, the editor scrolls to the element that carries those attributes and highlights it; when they click the element in the preview, the editor jumps to that block's settings. Outside the editor the output is empty, so the attribute costs nothing for visitors. Put it on the outermost element of each block. Forget it, and the block works but the editor cannot find it, which merchants experience as a broken theme.

Theme blocks

With theme blocks, the block lives in its own file, for example blocks/heading.liquid, with its own schema:

LIQUID
<h2 class="heading" {{ block.shopify_attributes }}>
  {{ block.settings.text | escape }}
</h2>

{% schema %}
{
  "name": "Heading",
  "settings": [
    { "type": "text", "id": "text", "label": "Text", "default": "Join us" }
  ],
  "presets": [{ "name": "Heading" }]
}
{% endschema %}

The presets entry makes the block appear in the editor's "Add block" list. Many sections can now share this one file, and a change to blocks/heading.liquid updates the heading everywhere.

A section opts in by listing the block types it accepts and printing them with content_for:

LIQUID
<section class="feature">
  {% content_for 'blocks' %}
</section>

{% schema %}
{
  "name": "Feature",
  "blocks": [
    { "type": "@theme" },
    { "type": "@app" }
  ],
  "presets": [{ "name": "Feature" }]
}
{% endschema %}

{% content_for 'blocks' %} renders all the block instances the merchant added, in order, each using its own file. If you prefer a loop, {% render block %} inside {% for block in section.blocks %} renders a theme block the same way. Treat section-defined blocks and theme blocks as two separate models in one section and check the current documentation before mixing them.

The special types

Type in the schema Accepts
@theme Any theme block in the blocks/ folder (the ones that have presets)
@app App blocks provided by installed apps
heading (a name) Only the theme block with that file name, blocks/heading.liquid

Listing specific names is how you keep a section focused: a slideshow can accept only slide blocks. Using @theme is how you let merchants build freely.

Nested blocks

A theme block can accept blocks itself. Add blocks to its schema and print the children with content_for 'blocks':

LIQUID
<div class="group" {{ block.shopify_attributes }}>
  {% content_for 'blocks' %}
</div>

{% schema %}
{
  "name": "Group",
  "blocks": [{ "type": "@theme" }],
  "presets": [
    { "name": "Group", "blocks": [{ "type": "heading" }] }
  ]
}
{% endschema %}

Now a merchant can put headings, buttons and even other groups inside a group, building a layout out of boxes without a developer. In the template JSON the tree is stored with the same blocks and block_order keys at every level:

JSON
"feature": {
  "type": "feature",
  "blocks": {
    "g1": {
      "type": "group",
      "blocks": { "h1": { "type": "heading", "settings": { "text": "Summer sale" } } },
      "block_order": ["h1"]
    }
  },
  "block_order": ["g1"]
}

Nesting depth is limited, so do not design a layout that needs a dozen levels. Look up the current maximum in the documentation, and keep trees shallow for performance and for merchants' sanity.

flowchart TD
  S["Section: feature<br/>accepts @theme, @app"] --> G["Block: group<br/>accepts @theme"]
  S --> A["Block: app block<br/>shopify://apps/..."]
  G --> H["Block: heading"]
  G --> B["Block: button"]
  G --> G2["Block: group (nested)"]
  G2 --> H2["Block: heading"]

Sections hold blocks; a group block can hold more blocks, including other groups.

Static theme blocks

Sometimes a block must always be present in a fixed place, such as the product title in the buy area. Instead of content_for 'blocks' you render one specific block with an id:

LIQUID
{% content_for 'block', type: 'heading', id: 'main-title' %}

It is a static block: the merchant can edit its settings but cannot move or remove it. Give it an id that stays the same, because the saved settings are matched to the id.

Comparing the two models

Section blocks Theme blocks
Defined in The section's {% schema %} A file in blocks/ with its own schema
Reuse Only inside that section Any section that accepts them
Nesting No Yes
App blocks Needs a @app entry Needs a @app entry
Best for Simple sections Flexible, merchant-built layouts

For a small one-off section, section blocks are less work. For a theme that wants a flexible page builder feel, theme blocks are the direction Shopify is pushing.

Block settings

Block settings use the same setting types as section settings (Schema Settings in Depth) and read the same way: block.settings.label. The same habits apply: output text with | escape, test for blank, and give every setting a sensible default so a freshly added block looks right.

Ordering and limits

The merchant's order is stored in block_order, so Liquid always sees blocks already in the right sequence. A section's max_blocks sets a total, and a block type's own limit caps how many of that type may appear. Shopify's own ceiling per section is 50 at the time of writing. Choose the numbers on purpose: if a hero can look good with three buttons, a limit of 3 protects the design.

Stand-in 1: rendering a nested block tree

The first editor walks the same JSON shape a template stores. Block "files" are JavaScript functions standing in for blocks/*.liquid, and data-block-id plays the role of block.shopify_attributes. An app block is recognized by its shopify://apps/ type and rendered by a placeholder.

JS Render a tree of theme blocks

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in 2: what may go where

The second editor models the schema rules for acceptance, limits and ordering. It decides if a block type is accepted by @theme, @app or a named type, refuses a block when max_blocks or a per-type limit is hit, and reorders blocks by editing block_order. The messages are our own wording.

JS Block acceptance, limits and order

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why put {{ block.shopify_attributes }} on a block's outer element?

    The attributes connect the element in the preview to the block in the editor sidebar. The block still renders without them, but merchants cannot select it.
  2. 2. What is the difference between a section block and a theme block?

    Theme blocks live in blocks/, can be shared across sections and can contain other blocks.
  3. 3. What does { "type": "@app" } in a section's blocks list allow?

    @app opens the section to app blocks. @theme does the same for the theme's own blocks.
  4. 4. Where is the merchant's block order stored, and how do you render the blocks in that order?

    The JSON template stores block_order, and Liquid already sees blocks in that order.

Summary

  • Blocks are the repeatable, reorderable pieces inside a section; merchants add and customize them in the editor.
  • Section blocks are defined in the section schema and rendered with for block in section.blocks. Theme blocks are files in blocks/ with their own schema and presets, rendered with {% content_for 'blocks' %}.
  • Put {{ block.shopify_attributes }} on every block's outer element so the editor can select it.
  • @theme accepts any theme block, @app accepts app blocks, and a name accepts only that block file.
  • Theme blocks can nest. Use {% content_for 'block', type: ..., id: ... %} for a fixed static block.
  • block_order stores the order; max_blocks and per-type limit bound the count. Keep trees shallow.

Next lesson: Schema Settings and Setting Types in Depth.