Theme architecture
Shopify sections, blocks & theme blocks explained (Horizon, 2026)
Sections, blocks, and the newer theme blocks confuse almost everyone. Here's how they actually fit together in Shopify's current Horizon architecture, with when to reach for each.
Bas Lefeber
Founder, learnshopify.dev · May 30, 2026 · 4 min read
If you've tried to learn Shopify theme development from tutorials, you've probably hit a wall of contradictory advice about "sections" and "blocks." Half the articles describe a world that no longer exists. Shopify's architecture moved on, and the current Horizon model introduced theme blocks, which are a genuinely different thing from the old section blocks. Here's the whole picture, current as of 2026.
Why most tutorials mislead you here
A lot of "Shopify sections and blocks" content was written for the Dawn / Online Store 2.0 era and never updated. It predates theme blocks and {% content_for %}. If a guide doesn't mention those, it's describing an older architecture, follow it and you'll write patterns Shopify is moving away from.
Sections: the big building blocks of a page
A section is a self-contained, reorderable chunk of a page, a hero, a featured-collection strip, a rich-text band. It's a .liquid file in the sections/ folder with a {% schema %} at the bottom that declares its settings. Merchants add, remove, and reorder sections in the theme editor without touching code.
<div class="featured-text"> <h2>{{ section.settings.heading }}</h2> <p>{{ section.settings.body }}</p></div> {% schema %}{ "name": "Featured text", "settings": [ { "type": "text", "id": "heading", "label": "Heading" }, { "type": "richtext", "id": "body", "label": "Body" } ], "presets": [{ "name": "Featured text" }]}{% endschema %}The presets entry is what makes the section show up in the theme editor's "Add section" menu. The settings become section.settings.* in your Liquid.
Blocks: the repeatable pieces inside a section
A block is a smaller, repeatable unit a merchant adds inside a section, the individual slides in a slideshow, the rows in an FAQ, the columns in a multi-column band. The merchant can add, remove, and reorder blocks within the section.
Here's where it splits, and where the confusion lives. There are now two kinds of blocks.
1. Section blocks (the original kind)
Defined inside a section's own {% schema %} under a blocks key, and rendered by looping section.blocks. They only exist inside that one section. This is the classic OS 2.0 pattern and still works.
{% for block in section.blocks %} <details {{ block.shopify_attributes }}> <summary>{{ block.settings.question }}</summary> <p>{{ block.settings.answer }}</p> </details>{% endfor %}2. Theme blocks (the Horizon kind)
Theme blocks are the newer model. They live as their own files in the blocks/ folder, are reusable across any section, and can even nest inside each other. A section opts into them by rendering {% content_for 'blocks' %} instead of manually looping. This is the direction Shopify is going, and the architecture Horizon themes are built on.
<div class="flexible-section" {{ section.shopify_attributes }}> {% content_for 'blocks' %}</div> {% schema %}{ "name": "Flexible section", "blocks": [{ "type": "@theme" }], "presets": [{ "name": "Flexible section" }]}{% endschema %}The @theme block type means "accept any theme block." {% content_for 'blocks' %} then renders whatever blocks the merchant added, in order, including nested ones, with zero manual loop. That reusability and nesting is the whole reason theme blocks exist.
Section blocks vs theme blocks: which do I use?
- Reach for theme blocks when the piece is reusable across sections or you want merchants to compose freely (the modern default on Horizon).
- Section blocks are fine when the block only ever makes sense inside one specific section and you don't need reuse or nesting.
- If you're building new on Horizon, lean theme blocks. It's where the platform is heading and it's what current themes expect.
How it all nests
Putting it together, a page is: a template (JSON, e.g. templates/product.json) that lists which sections appear and in what order; each section contains blocks (section blocks or theme blocks); and the whole thing renders inside a layout (layout/theme.liquid). Merchants control the template + section + block arrangement in the editor; you build the pieces.
The mental model that sticks
Layout wraps the page. Template orders the sections. Sections hold blocks. Blocks are the repeatable bits. Theme blocks are the reusable, nestable evolution of section blocks. Get those five nouns straight and the rest of theme architecture falls into place.
This is the spine of Module 3 on learnshopify.dev, you build real sections and theme blocks against the actual Horizon architecture, not the outdated Dawn patterns most tutorials still teach. It's free during the beta if you want to build it hands-on.
Learn this properly · free lesson
The shape of a theme: where everything lives
Start with the lay of the land: map out where every file lives in a real Horizon theme.
Try this lesson — freeFrequently asked questions
What's the difference between a section and a block in Shopify?
A section is a large, reorderable chunk of a page (a hero, a featured-collection strip) defined in sections/ with its own schema. A block is a smaller repeatable unit inside a section (a slide, an FAQ row). Merchants reorder sections at the page level and blocks within a section.
What are theme blocks and how are they different from section blocks?
Theme blocks (the Horizon model) live in the blocks/ folder, are reusable across any section, and can nest. A section renders them with {% content_for 'blocks' %}. Section blocks (the older model) are defined inside one section's schema and only exist there, rendered by looping section.blocks. Theme blocks are the newer, more flexible approach.
Should I use section blocks or theme blocks?
On current Horizon themes, default to theme blocks when the piece is reusable or you want free composition and nesting. Section blocks are fine for blocks that only make sense inside one specific section. New builds should lean theme blocks, that's where Shopify is heading.
What is content_for in Shopify Liquid?
{% content_for 'blocks' %} renders the theme blocks a merchant added to a section, in order, including nested blocks, without a manual {% for %} loop. It's the Horizon-era mechanism that makes theme blocks composable and reusable across sections.
Keep going in the curriculum