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.

Liquid Gold 2 min read

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

  1. Design small, focused blocks. A block should do one job.
  2. Use clear setting names. Merchants will see them in the editor.
  3. Set sensible defaults. A block should look good the moment it is added.
  4. Limit nesting where it adds confusion. Eight levels is the maximum, not the goal.
  5. Test on mobile. Nested layouts can break on small screens.
  6. 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 →

Keep reading

Related articles