The Shopify Horizon theme system replaces the classic {% for block in section.blocks %} loop with a single Liquid tag, {% content_for 'blocks' %}, that renders all merchant-configured blocks in the correct order, including every nested level beneath them. Theme blocks live in a dedicated /blocks folder, are reusable across every section in the theme, and can be nested up to 8 levels deep (not counting the section itself). Once you understand the two variants of content_for and the handful of hard limits Shopify enforces, the architecture becomes predictable.
Key takeaways
{% content_for 'blocks' %}replaces the manual block loop; it handles ordering and nesting automatically.- Theme blocks live in
/blocks, are reusable across sections, and support nesting. Section blocks do not support nesting. - Nesting is capped at 8 levels, excluding the section level. The per-section block limit is 50; per-template it is 1,250.
- A theme can hold at most 300 files in
/blocks, including AI-generated blocks that are never referenced. - Sections can support theme blocks OR local section blocks, never both simultaneously.
Why this matters: Horizon vs. Dawn at the architecture level
Dawn builds pages by stacking sections vertically, each owning its own block definitions inside its schema. That is Online Store 2.0 at its most literal. Horizon fundamentally changes the relationship between sections and blocks.
Horizon was launched on May 21, 2025, and it is the first theme family built entirely on the new theme-block model. The theme ships 95 theme block files; Dawn ships zero. What that means in practice: in Horizon, the section is a container that delegates rendering to blocks, and those blocks are shared across the whole theme rather than owned by one section.
| Characteristic | Section blocks (Dawn model) | Theme blocks (Horizon model) |
|---|---|---|
| Where defined | Inside one section's {% schema %} | Own file in /blocks/ |
| Reusable across sections | No | Yes |
| Nesting supported | No | Yes, up to 8 levels |
| Rendered by | {% for block in section.blocks %} | {% content_for 'blocks' %} |
| Can define local child blocks inline | Yes (in sections) | No |
| Visible in block picker without presets | Yes | No, presets are required |
| Counts toward 300-file limit | No | Yes, even if unreferenced |
The architectural difference means there is no automatic translation when moving a Dawn customization into a Horizon section.
How content_for 'blocks' actually works
The tag has two distinct forms, and conflating them is the most common mistake I see in code reviews.
Form 1: render all dynamic blocks
{% content_for 'blocks' %}
This outputs every block the merchant has added in the theme editor, in the order stored in the JSON template. No loop, no {% case block.type %}, no manual {% render block %}. The platform handles everything. You use this in both sections and in any theme block that accepts child blocks.
Form 2: render a single static block
{% content_for 'block', type: 'announcement-bar', id: 'top-bar' %}
This pins a specific block to a specific position in your Liquid. The merchant can still configure its settings, but they cannot move or delete it. Static blocks carry "static": true in the saved JSON and are excluded from the block_order array because merchants cannot reorder them. Shopify determines their display order relative to dynamic blocks based on their position in the Liquid source. You can also pass arbitrary parameters to static blocks, for example color: "#F00", which the block accesses as {{ color }}.
One rule that catches people out: statically rendered blocks added with {% content_for %} do NOT count toward the 50-blocks-per-section or 1,250-blocks-per-template limits. Only merchant-addable dynamic blocks count.
Opting a section into theme blocks
A section opts in by doing two things:
- Declaring
{ "type": "@theme" }(and optionally{ "type": "@app" }) in itsblocksarray. - Placing
{% content_for 'blocks' %}where the blocks should render.
{%- comment -%}
sections/flexible.liquid
{%- endcomment -%}
<div class="flexible-section" {{ section.shopify_attributes }}>
{% content_for 'blocks' %}
</div>
{% schema %}
{
"name": "Flexible section",
"blocks": [{ "type": "@theme" }, { "type": "@app" }],
"presets": [{ "name": "Flexible section" }]
}
{% endschema %}
@theme tells the editor to offer every file in /blocks that has a preset defined. @app tells it to also accept blocks from installed apps. If you omit @app, app review widgets and similar integrations simply cannot inject into that section.
One hard constraint: a section can support theme blocks OR local section blocks, never both at the same time. The moment you add { "type": "@theme" }, the section hands off all block management to the theme-block system.
Building a nestable theme block
Making a theme block accept children is exactly the same pattern, applied one level down:
{%- comment -%}
blocks/group.liquid
{%- endcomment -%}
<div class="group" {{ block.shopify_attributes }}>
{% content_for 'blocks' %}
</div>
{% schema %}
{
"name": "Group",
"blocks": [{ "type": "@theme" }, { "type": "@app" }],
"presets": [{ "name": "Group" }]
}
{% endschema %}
The {{ block.shopify_attributes }} output on the wrapper element is not optional. The theme editor uses those data attributes to wire up click-to-select behaviour. Without it, clicking the block in the preview does not open the block's sidebar panel.
One constraint unique to theme blocks: unlike sections, theme blocks cannot define local blocks inline in their schema. They can reference existing blocks by type (@theme, @app, or a named type like "slide"), but they cannot declare a brand-new block inside their own schema. All blocks must exist as separate files in /blocks.
The underscore prefix: hiding blocks from the picker
If you want a theme block to be used only as a child of a specific parent, prefix its filename with an underscore: blocks/_slide-item.liquid. Blocks with an underscore prefix are excluded from the global block picker that appears when a section uses { "type": "@theme" }. They still appear when a parent block explicitly references them by name: { "type": "_slide-item" }. This is how Horizon builds constrained slot patterns without losing the flexibility of the shared /blocks folder.
The hard limits, all in one place
Shopify's official theme limits page publishes these numbers:
| Limit | Value |
|---|---|
| Blocks per section (dynamic) | 50 (reducible with max_blocks) |
| Blocks per JSON template or section group | 1,250 |
| Theme block nesting depth | 8 levels, excluding the section |
Theme block files in /blocks | 300 (including unreferenced files) |
| Sections per JSON template | 25 |
The 300-file ceiling is the one that bites Horizon stores with heavy AI block generation. Every .liquid file in /blocks counts toward that limit, even blocks that are no longer referenced by any section or template. If you are using Sidekick to generate custom blocks during development, audit the folder regularly.
Common mistakes and how to avoid them
- Mixing section blocks and theme blocks in the same section. Shopify will not render both. Pick one model and commit.
- Missing
{{ block.shopify_attributes }}on the wrapper. Editor click-to-select breaks silently. - Adding
limitto@appentries. The@appblock type does not accept alimitparameter; it causes a schema error. - Over-nesting. Eight levels is the ceiling, but anything past level 3 or 4 becomes difficult for a merchant to navigate in the sidebar. I generally treat level 5+ as a code smell unless the design genuinely demands it.
- Shipping unused AI-generated blocks. They count toward the 300-file limit and inflate the
/blocksfolder silently. - Skipping presets on a theme block. A theme block without a preset defined in its schema does not appear in the block picker and is therefore inaccessible to merchants without code changes.
Verifying your block setup
A few quick checks after wiring up a new theme block or section:
- Open the theme editor and confirm the block appears in the "Add block" picker for the target section.
- Click the block in the preview pane and confirm the sidebar panel opens. If it does not,
{{ block.shopify_attributes }}is missing. - Nest the block inside a group and confirm the child block renders correctly and that its editor panel is reachable.
- Run
shopify theme checklocally. TheSchemaPresetsStaticBlockscheck will warn if a preset static block lacks a matchingcontent_for 'block'tag in Liquid, which is a silent runtime failure. - Count files in
/blocksbefore shipping:ls blocks/ | wc -l. Stay well below 300 unless you have a cleanup plan.
For a more detailed treatment of how the Horizon theme departs from Dawn's cart architecture specifically, see why Horizon has no main-cart-items.liquid. For a quick reference on the Liquid objects and tags used throughout this post, the Shopify Liquid reference guide covers block, section, and related drop properties.
Conclusion
The theme-block system is a genuine architectural shift, not a cosmetic update. {% content_for 'blocks' %} is the mechanism that makes reusability and nesting possible without custom loop logic, and understanding its two forms (all dynamic blocks vs. one pinned static block) is the prerequisite for building anything non-trivial in Horizon. The limits are real: 8 nesting levels, 50 blocks per section, 300 files in /blocks, and a strict mutual exclusion between theme blocks and local section blocks in the same section. Work within those constraints from the start and the architecture stays clean; try to work around them and you will hit walls that require a rebuild.
If you would rather hand this off, my studio Lintel offers Shopify theme development.
Frequently asked questions
What is the difference between `{% content_for 'blocks' %}` and `{% content_for 'block', type: ..., id: ... %}`?
The first form renders all dynamic blocks the merchant has added to a section or parent block, in the order stored in the JSON template. The second form renders a single static block pinned to a specific position in Liquid code, which merchants can configure but not move or delete.
Can a Shopify section support both theme blocks and local section blocks at the same time?
No. A section must choose one model. If the section schema includes a block type of @theme, it uses the theme-block system and content_for 'blocks' for rendering. Adding local block definitions to the same schema is not supported and will not work.
Why does my theme block not appear in the block picker?
A theme block only appears in the picker if it defines at least one preset in its schema. Without a preset, the block exists in the /blocks folder but is invisible to merchants in the theme editor.