Shopify Theme Blocks and Nested Blocks: How to Build Flexible Sections
Learn how Shopify theme blocks and nested blocks work, how to build reusable blocks in Liquid and why they give merchants more control in the editor.
Theme blocks let developers build reusable pieces of a page that merchants can add, move and nest in the theme editor. Shopify introduced them in the Winter ’25 Edition, with support for nesting up to eight levels deep. This guide explains the idea and the basic pattern.
The problem blocks solve
Traditional sections have fixed blocks defined inside each section file. If you wanted the same “button” or “testimonial” block in several sections, you copied code. Merchants could not drop a block anywhere they liked.
Theme blocks separate the block from the section. A block lives in its own file and can be reused across sections, and a block can contain other blocks.
How the pattern works
A block is a Liquid file in your theme’s blocks folder, with its own schema that defines its settings. A section or another block then declares where blocks are allowed and renders them:
{% content_for 'blocks' %}
In the editor, merchants see an “Add block” option and choose from the blocks you permit. Because blocks can nest, a “Row” block can hold “Heading”, “Text” and “Button” blocks, and a “Group” block can hold several rows.
Why merchants like it
- More freedom to rearrange layouts without a developer
- Consistent design, since every instance of a block uses the same code
- Fewer one-off sections to maintain
Why developers like it
- Less duplicated code
- Cleaner file structure
- Easier updates, because changing one block file updates every place it is used
- Better scope control, because you decide which blocks each section accepts
Best practices
- Design small, focused blocks. A block should do one job.
- Use clear setting names. Merchants will see them in the editor.
- Set sensible defaults. A block should look good the moment it is added.
- Limit nesting where it adds confusion. Eight levels is the maximum, not the goal.
- Test on mobile. Nested layouts can break on small screens.
- Keep accessibility in mind. Use correct heading order and alt text.
Tools to speed up development
Shopify CLI 4.0, released in May 2026, adds semantic versioning and auto-updates, and removes the deprecated --force flag. Keep your CLI current so theme commands behave consistently across your team.
Check the docs for syntax
Shopify’s developer documentation is the source of truth for block schema and rendering syntax. Check it before you build, because details can change between versions.
FAQ
Do theme blocks work in any theme? They work in themes built to support them. Older themes may need updates.
Are blocks better than sections? They solve a different problem. Sections define page structure, and blocks provide flexible content inside them.
Related reading: Custom Shopify Theme vs Premium Theme, Shopify Metaobjects: Practical Use Cases for Custom Content and Logic and Migrating Checkout UI Extensions to Polaris Web Components.
Need a custom block library?
Liquid Gold builds custom Shopify themes with reusable, merchant-friendly blocks. Talk about theme development →