Outrank AI
A merchant asks for a benefits strip on the homepage. They want to edit the copy before a sale, move it below the hero next month, and remove it later without filing a developer ticket each time. If you hard-code that strip into a section, every one of those requests becomes your job.
That's the maintenance trap Shopify theme blocks are meant to prevent. A block turns a small piece of content into something a merchant can add, remove, reorder, and configure in the editor. The catch is that every block you ship is also a long-term commitment. It needs a clear job, sensible settings, a cap that protects the layout, and a review process before anyone trusts it on the live store. Build blocks carelessly and you'll trade hard-coded templates for a folder full of near-duplicates that nobody wants to touch.
Table of Contents
What Shopify Theme Blocks Are and Where They Fit
Say that benefits strip has four items, each with a short heading and line of text. As a block, each item becomes a small reusable unit inside a section, managed in the theme editor. The merchant can add a fifth item, delete one, or drag them into a new order. You define what can change. They handle routine content work.
Shopify splits blocks into three types, and picking the wrong one creates work later. The Shopify theme architecture documentation for blocks defines theme blocks as standalone Liquid files in the /blocks directory that can be reused across sections and accept nested child blocks, while section blocks are confined to their defining section and can't be nested.
Shopify block types compared
Block type | Where it is defined | Reusable across sections | Nesting | Who supplies it |
|---|---|---|---|---|
Section block | Inside one section | No, confined to its section | Cannot be nested | Theme developer |
Theme block | Standalone file in the /blocks directory | Yes, across compatible sections | Can contain child blocks | Theme developer |
App block | Supplied by an installed app | Yes, where the section allows it | No | App developer |
The App Block Rule That Trips Teams
App blocks don't work everywhere just because an app is installed. They need a JSON template and a section designed to render them, and they can't render on checkout step pages. If you're planning how blocks sit inside larger page structures, our guide to sections in Shopify covers that container relationship.
Decision rule: If a feature appears on several pages, build a theme block. If it belongs to one section only, keep it as a section block. If a third-party app supplies the functionality, use an app block.
I'd apply that rule before writing any Liquid. Most block sprawl starts when a one-off section element gets promoted to a reusable file it never needed to be.
Scale Limits to Plan Around for Large Storefronts
Design against the ceiling first, then set your own working caps well below it. The Shopify JSON templates documentation sets the platform limits below, including 25 sections per JSON template and 50 blocks per section.
Shopify block and template limits
Limit | Value | Applies to |
|---|---|---|
Sections per JSON template | 25 | Each JSON template |
Blocks per section | 50 | Each section |
Blocks per JSON template or section group | 1,250 | All sections combined |
Nesting depth | 8 levels, excluding the section level | Theme block child blocks |
Files in the /blocks directory | 300 | Whole theme, including unreferenced files |
JSON templates per theme | 1,000 | Whole theme |
Set Business Caps Below Platform Caps
Shopify permits 50 blocks in a section. That doesn't mean your benefits strip should allow 50 benefit items. Set max_blocks to a number the layout and the merchant can handle. Six items reads well and stays easy to scan in the editor sidebar. Fifty creates a scrolling list nobody can reorder confidently, and the page design will break long before you hit the platform limit.
The 1,250-block total across a template is important on long homepages. When combining a few block-heavy sections, nested children included, a merchandising-heavy landing page approaches that ceiling faster than anticipated. Count before you design the page, not after the editor refuses to save.
Keep Nesting and File Count Under Control
Eight nesting levels is a platform ceiling, not a target. Past two or three levels, merchants lose track of which parent they're editing, and your schema becomes hard to reason about. I would treat two levels as the default and require a specific reason for a third.
The 300-file limit counts everything in your /blocks folder, including files no template references. Dead experiments and abandoned variants consume real budget. Delete unused blocks as part of normal cleanup, especially before adding a new pattern.
One useful exception is that statically rendered blocks don't count toward merchant-managed limits. That's a genuine design lever. If merchants never need to move or edit a component, rendering it statically keeps it out of the editor math entirely.
Shopify documents platform limits, not conversion or speed outcomes. Don't claim a block variant helps until you've measured it with real storefront analytics and performance traces.
How to Create a Theme Block File and Schema
Work in a development or duplicate theme, never the live one. A malformed schema can break the editor for a section, and you don't want a merchant discovering that during a promotion.
Build the File in Six Steps
Create the file in the blocks folder. Name it for the job, such as blocks/benefit-item.liquid, so the editor shows a recognizable name. Vague names like
content-block-2guarantee confusion six months later.Write semantic markup. Use Liquid and HTML, reading values from block.settings. Headings, links, and lists should carry real meaning, not just styling hooks. Screen readers and search engines both depend on that structure, and retrofitting semantics into a shipped block is tedious work.
Add the schema. Give the block a name, a settings array, and at least one preset. Use setting types such as text, richtext, image_picker, and url. These give merchants constrained, safe inputs instead of raw text fields where they can paste anything.
Inherit theme styles. Pull colour and typography from the theme's existing settings instead of hard-coding hex values or font sizes in the block. When the brand updates its palette, the block follows automatically. Hard-coded values strand your block in the old design.
Keep one block to one job. A benefit item renders one benefit. It doesn't also render the strip heading, a call to action, and a newsletter form. For a repeating list, use child blocks under a parent rather than one oversized block with numbered settings like
heading_1throughheading_8. Numbered settings can't be reordered, and that defeats the point.Save and verify in the editor. Open the theme editor, add the block to a compatible section, and confirm it renders with its default preset before you change any settings.
The Minimal Schema That Actually Appears
A workable starting schema gives the block a name such as Benefit item, one text setting with the id heading and label Heading, and one preset with the same name. That's enough for a merchant to add the block and see something real.
The preset is doing more work than people credit it for. The preset is what makes the block appear in the add menu with usable defaults. Skip it and you get the most common slip in block development: a perfectly valid file that inserts as an empty block, showing nothing until a merchant fills in every field. Merchants reasonably conclude the block is broken.
Practical rule: If a block renders nothing when first added, merchants won't trust it, no matter how good the code is. Ship defaults that look finished.
Keep the settings list short at first. You can add a setting later without breaking existing templates. Removing one that merchants have already used across live pages is a migration, not an edit.
Adding Blocks to Sections in JSON Templates
A finished block file does nothing on its own. It only appears in the editor once a section explicitly allows it, and most "my block doesn't show up" reports trace back to this step rather than to the block itself.
Wire Up the Section Schema
In the section schema, add a blocks entry with type @theme to accept theme blocks and @app to accept app blocks. Set max_blocks to the cap your layout can handle at the same time. Accepting every block type into every section sounds flexible, but it lets merchants drop a wide banner block into a narrow sidebar section and then report the result as a bug. Target deliberately.
Store the Configuration in the Template
In the JSON template, list blocks in block_order and give each one its type and settings. The template stores section configuration as data, which is why the editor can change a page's composition without a code deploy. This is also the mechanism behind flexible layouts like those in a Shopify product page template, where merchandising blocks need to move around the buy box.
Render Each Block Correctly
Inside the section, loop over section.blocks and render each block file. Put block.shopify_attributes on the wrapper element. This step is not optional. Without it, clicking the block in the editor preview selects nothing, and drag-and-drop reordering breaks. Merchants experience that as a frozen editor, and it's a one-line omission on your side.
Test in the Order Merchants Work
Run four editor actions in sequence: add a block, remove one, reorder two, then reload the page. The reload matters because it proves the template data saved correctly, not just that the preview looked right. Then check the empty state. A section with zero blocks shouldn't show a stranded heading, an empty bordered container, or extra spacing where content used to be.
Two failures look like bugs but are configuration gaps. A section without an @theme entry won't accept theme blocks at all, no matter how correct the block file is. And a block copied into a section with no matching schema renders nothing and throws no error. Silent failure is the theme here, so check schema acceptance before debugging markup.
Block Patterns That Hold Up in Real Stores
The patterns below survive contact with real merchandising work because each one has a clear cap, a shallow structure, and a defensible reason for being a theme block or a section block.
Four Patterns Worth Copying
Benefits strip: A theme block with a text and icon setting, capped at four to six items. It earns theme block status because the same strip belongs on the homepage and on product pages, and one file keeps both consistent.
FAQ accordion: A parent theme block holding nested question-and-answer child blocks, kept to two levels deep. Say a support team updates shipping answers monthly. They edit one child block per question, reorder freely, and never touch the accordion behaviour.
Promotional banner: A theme block with text, url, and colour settings, shipped with two presets, one for a sale and one for an evergreen message. Presets carry the two real use cases, so merchants aren't reverse-engineering settings during a campaign launch.
Trust badge row: A section block, deliberately. It lives in one section, gains nothing from reuse, and promoting it to the /blocks folder only adds a file to maintain and a target to manage.
Watching a working block system being assembled in the editor makes the parent and child relationship easier to judge than reading schema alone.
The Sprawl Pattern to Refuse
The failure mode is a near-identical block copied for each landing page. One gets a background toggle, another gets wider padding, a third gets both. Fixes land in one copy and miss the others, and within a year nobody knows which version a given page uses. The file count climbs while actual capability stays flat.
Search the existing /blocks folder before creating a new block, and extend a block with a setting before you copy it.
A new setting is cheap. A new file is a maintenance commitment with its own testing surface. I'd only create a separate block when the markup structure genuinely differs, not when one option would cover it.
Review and Test Blocks Before Publishing
Generated code is not finished code. That assumption is where AI-assisted block work goes wrong. According to Shopify's help documentation on generating blocks with Sidekick, Sidekick adds the generated file to the theme's /blocks folder, containing Liquid, HTML, CSS, JSON, and JavaScript. The editor also re-renders block HTML in the existing DOM without a full page reload, so generated JavaScript can attach duplicate event listeners or hold stale state.
Start With Schema and Presets
Before you look at how a generated block looks, read its schema and presets. Generated settings are often broader than the feature needs, and every unnecessary setting is a decision a merchant has to make and a state you have to test. Trim settings that don't map to a real merchandising need. Check that defaults render something sensible and that labels say what the setting controls in plain language.
Run the Duplicate-Theme Review in Order
Duplicate the live theme. Do all testing there. The duplicate also becomes your rollback point, which matters when a block interacts badly with an existing section only under real content.
Add each block to every section that should accept it. Confirm it appears where intended and is absent where it isn't. Confirm app blocks render only in sections built for them and never on checkout step pages.
Test four states for each block. Empty, minimum settings, maximum block count, and a reordered list. After add, remove, and reorder, run DOM re-render checks, because the editor updates block HTML without reloading. Duplicate listeners often show up as a click firing twice or an accordion that opens and immediately closes.
Check the smallest supported section width and a real phone. A block that looks fine full-width can collapse badly inside a narrower section. Then test keyboard use, screen reader output, and focus order. Generated markup frequently uses clickable divs where a button belongs, and that fails keyboard users outright.
Run Lighthouse on the duplicate and compare Core Web Vitals against the live theme. Generated CSS and JavaScript can be heavier than the feature warrants, and you want that comparison before customers pay for it. Our process for catching regressions like these across a release is covered in the Shopify theme pipeline.
Confirm each analytics event fires once, every merchant-facing string is localized, and no unused files remain in /blocks. Generated blocks count toward the theme's file budget even when no template references them, so abandoned generations aren't free.
Publish only when every block passes. Keep the duplicate theme as the rollback point rather than deleting it in the excitement of shipping.
Govern What You Accept
A generated block can legitimately avoid an app dependency. That's a real win when the feature is simple and stable. But unmanaged generated code swaps app maintenance for theme maintenance. Someone now owns that JavaScript, those styles, and that schema. If nobody owns them, you've replaced a vendor's update cycle with silent rot in your own theme.
Assign an owner to every block you accept, generated or hand-written. Review the /blocks folder on a regular cadence, delete what nothing references, and treat each remaining file as code your team supports. Businesses that want help structuring that ownership can start by booking a call to take control of their Shopify storefront, and the same discipline applies whether you do it internally or with a partner.
If your /blocks folder has grown faster than your team's ability to maintain it, we'd start with an audit of what's referenced, what's duplicated, and what should become a setting instead of a file. Presidio builds custom Shopify themes with reusable blocks merchants can manage, and we support that work with ongoing performance and accessibility improvements. Visit Presidio to book a call and talk through your theme.
