Sections and Theme Blocks

A storefront page is a tree. The layout (layout/theme.liquid) outputs {{ content_for_layout }}, which renders the JSON template that matches the requested page. The template lists sections in an order array. A section is a Liquid file in sections with a {% schema %} tag that declares its settings, the blocks it accepts and its presets. Blocks are the pieces inside a section that the merchant can add, remove and reorder in the theme editor, each with its own settings. Header and footer areas use section groups, which are JSON files in sections that list sections in the same way a template does.

Figure 1 compares the three kinds of blocks side by side. The cards list where each kind is defined, who can use it, how it nests, how Liquid renders it and which limits apply.

The structural limits that apply to the whole tree are small and worth memorising:

Source: JSON templates, Section groups, Blocks, Block schema and Changelog, app block limit.

A section is a Liquid file in the sections folder. It has three kinds of content: the markup (HTML and Liquid, with access to global objects, tags and filters plus the section and block objects), optional assets declared with {% stylesheet %} and {% javascript %}, and the schema. A section can be rendered in three ways: by listing it in a JSON template or section group (the normal way, which lets merchants add, remove and reorder it), by rendering it statically with {% section 'name' %} (which merchants cannot remove or reorder, and which has one shared instance for all of its static renderings), or through the Section Rendering API. Rendering statically is discouraged whenever a JSON template or section group can do the job.

When Shopify renders a section it wraps the output in a div with id="shopify-section-<id>" and the class shopify-section. The tag and class schema attributes change the element and add classes.

The {% schema %} tag accepts these attributes. A file may contain only one schema tag, the tag may not be nested inside another Liquid tag, and its content must be valid JSON that uses only the listed attributes.

The section object exposes blocks, id, index, index0, location and settings. The ID of a section that comes from a JSON template is generated by Shopify, while a statically rendered section uses its file name as the ID. The location is template, a section group type such as header or footer, static, or content_for_index. The index properties are nil for statically rendered sections, in the theme editor and in the Section Rendering API, so use them only for non-visual work such as deciding which images to lazy-load. The block object exposes id, settings, shopify_attributes and type.

Source: Sections, Section schema, Liquid object: section and Liquid object: block.

Section blocks are the original block mechanism. They are declared in the blocks array of the section’s own schema and exist only inside that section. They cannot nest, they cannot be used by other sections, and a section that defines them cannot also accept theme blocks. Use them when a section has a small, closed set of repeatable items, such as slides, FAQ rows or the tasting notes below.

Each entry in the section’s blocks array supports four attributes.

The theme editor labels each block in the sidebar with its name, unless a setting with the ID heading, title or text exists, in which case that setting’s value is used, in that order of precedence. A block that is a single element must carry {{ block.shopify_attributes }} so the theme editor can identify it and send JavaScript events to it. The attribute returns nothing outside the theme editor.

The following section lists Pocket Coffee tasting notes. It defines one local block type note with at most three instances, caps the section at six blocks, and also accepts app blocks. It was added to the product alternate template shown later and passed Theme Check with no offences, both with the default theme-check:recommended rules and with theme-check:all.

Source: Section blocks and Section schema, blocks.

Notes on the example:

A theme block is a Liquid file in the blocks folder. The file has markup, optional {% stylesheet %} and {% javascript %} tags, an optional {% doc %} LiquidDoc header and a {% schema %} tag. A theme can contain at most 300 theme blocks. In Online Store 2.0 terms they behave like small sections: they have settings, presets and a wrapper element, merchants can add and reorder them in the editor, and they can contain other blocks.

The {% schema %} tag of a theme block accepts name, settings, blocks, presets, tag and class. Theme blocks cannot define local blocks in their blocks attribute: that attribute only lists @theme, @app or named theme blocks.

By default a theme block is wrapped in <div id="shopify-block-<id>" class="shopify-block">. With "tag": null the block renders without a wrapper. In that case the block file must contain a single topmost HTML element and that element must carry {{ block.shopify_attributes }}; otherwise the theme editor cannot move the whole block when merchants reorder it and leaves orphaned markup behind.

Inside a theme block the Liquid objects are block (its own ID, type and settings), section (the section that rendered it) and the global objects. A theme block cannot see variables created outside it and, unlike a snippet, cannot be passed variables from its parent, with one exception: static blocks receive named arguments, described below.

A section opts into theme blocks by listing @theme in the blocks array of its schema, and renders them with {% content_for 'blocks' %}. A section can either define local blocks or opt into theme blocks. It cannot do both. Theme Check reports the combination with ValidLocalBlocks.

Source: Theme blocks quick start and Liquid tag: content_for.

The blocks array has four entries: @theme accepts every public theme block, @app accepts app blocks, and the two named entries (origin-card and roast-date-badge) are the recommended blocks. When a section lists @theme together with named blocks, the named ones appear first in the block picker and the rest are behind Show all. The preset Beans spotlight pre-populates a badge and a horizontal group that holds two origin cards.

{% content_for %} creates a designated area where blocks are rendered. It takes a type argument that selects between two behaviours.

Both forms are used in sections and in theme blocks. The ID of a static block is mandatory and it must be a string literal, because Shopify never generates it. Theme Check checks the arguments with ValidContentForArguments, the existence of the block file with ValidStaticBlockType and the uniqueness of IDs with UniqueStaticBlockId.

Source: Liquid tag: content_for and Static blocks.

Targeting decides what the Add block picker offers. The picker is built from the blocks array of the section or block that the merchant is editing.

A theme block shows in the picker only if it has at least one preset, and by default every block with a preset is available in all sections and blocks that accept @theme. When a block should be reserved for one parent, give the file a leading underscore. Underscore-prefixed blocks (private blocks) are excluded from @theme and must be named explicitly. In Pocket Coffee, tasting notes and brew steps are private blocks, so they are offered only by the cards and the brew guide that name them. Horizon 4.3.0 follows the same convention for 51 of its 95 blocks.

Presets appear alphabetically in the picker, grouped in collapsible categories when a preset has a category, with uncategorised presets first.

Source: Theme block targeting and Block schema, blocks.

Theme blocks nest by listing child blocks in their own blocks attribute and rendering them with {% content_for 'blocks' %}. The origin-card above accepts @app, the private _tasting-note and the public text block, and renders them inside its body. Theme blocks can nest up to eight levels deep, counted below the section. The JSON template stores the tree: each block has an ID, a type, settings, a blocks map of children and a block_order array that gives their order. The same rendering mechanism is used by sections and by blocks.

Figure 2 shows the Pocket Coffee product template as nested boxes. The coffee-feature section holds the badge and a group, the group holds two origin cards, and the first card holds a tasting note. The brew-guide section holds dynamic steps and a static timer, and the roast-notes section holds one local section block.

The complete template is an alternate product template, templates/product.coffee.json. The dynamic blocks are in block_order. The static timer has "static": true and is not in block_order, because its position is decided by the Liquid code, not by the merchant. The three section IDs coffee_feature, brew_guide and notes are alphanumeric with underscores and unique within the template.

Source: JSON templates, section data and Theme blocks quick start, nest blocks.

Block IDs inside the JSON do not have to be unique across the section any more. A block ID must be unique only among the children of its immediate parent. That matters for static blocks, which can be rendered in several places.

A hand-edited template can name a block type that does not exist. Theme Check reports that with JSONMissingBlock, and reports block references inside schemas with ValidBlockTarget.

Presets turn an empty block file into something merchants can pick from a list. There are three similarly named concepts, and mixing them up is a common mistake.

A section or block preset has these attributes:

The origin-card and coffee-feature files above each define more than one preset. For example, origin-card has a plain Origin card preset and a Yirgacheffe card preset that pre-populates two tasting notes with their own settings. A preset can also refer to other theme blocks in the theme, which is how a Column preset of a group block can include two text blocks, as in the official quick start.

Section presets are different from default: the default object is for sections that are statically rendered, and it takes the same attributes as a preset. Sections that are installed on several themes or shops, and statically rendered sections that ship pre-installed in a theme, should use default and the per-setting default attribute instead of a preset.

Source: Section schema, presets, Block schema, presets and Theme blocks quick start, add a block preset.

A static block is a theme block rendered with {% content_for 'block', type: '...', id: '...' %} instead of {% content_for 'blocks' %}. It lets a section or block fix the position of a block: merchants can hide it and change its settings, but they cannot move, delete or duplicate it. It also lets Liquid render the block conditionally or in a loop, which a dynamic block cannot do.

The type is the name of a block file in blocks. The id is required, because the same block can be rendered statically more than once. Any further named argument is passed to the block as a variable, for example color: "#111" is available as {{ color }} inside the block. The changelog entry dated 2025-05-21 introduced this parameter passing. Static blocks also receive dynamic source data from their parents, and Liquid can set a source for the closest resource with an argument such as closest.product: product, which Horizon 4.3.0 uses in its collection card.

Block settings can be connected to data instead of fixed values: merchants connect compatible settings to a dynamic source in the theme editor, and a theme block can read data from four places.

Theme blocks are reusable and nestable, so a block cannot know where its data will come from. The closest access path resolves the nearest resource of a type: {{ closest.product }}, {{ closest.collection }}, {{ closest.article }}, {{ closest.blog }}, {{ closest.page }} and {{ closest.metaobject[<definition_type>] }}. The resolution order is the closest Liquid context setter, then the closest ancestor block setting, then the section settings, then the template resource. closest works only in settings, usually as a preset value, as in the roast date badge, and it keeps pointing at the same ancestor even when that ancestor’s setting is empty (the nested blocks show placeholders).

Section settings of type product or collection can be used as dynamic sources, and app blocks get the same behaviour through autofill. For that reason a section that supports app blocks should have at most one resource setting of each type, to avoid ambiguity. In Pocket Coffee the coffee-feature section has one product setting and one static badge that reads it:

This line is part of sections/coffee-feature.liquid above and passed Theme Check.

Source: Dynamic sources for theme blocks and Dynamic sources.

An app block is a block that an app ships and a merchant adds to a theme. It lets an app put content in a section without editing theme code, and it replaces the old script-tag pattern for visible content. Both sides have work to do: the theme must accept and render @app, and the app must ship a theme app extension whose block has the right schema.

In the theme editor, merchants of eligible stores can describe a block in plain text and Sidekick generates a theme block, with markup, optional CSS and JavaScript, and the schema. From the developer’s point of view a generated block is an ordinary theme block stored in blocks, and it counts toward the limit of 300. A section accepts generated blocks when it accepts @theme. When a merchant generates a block in a new section Shopify wraps it in a platform section called _blocks.liquid. A theme can override the wrapper with its own sections/_blocks.liquid, which must accept @theme and @app, define presets, call content_for 'blocks' and not define templates.

Source: AI generated theme blocks.

The Liquid July '26 developer preview (2026-07-21) adds a way to compose a page directly in a Liquid template, next to the JSON template model. The {% block 'name' %} tag renders the file blocks/name.liquid the way render renders a snippet: it takes named parameters and optional body content that the block prints with {{ content }}. A parameter whose name matches a schema setting also sets that setting, and the tag accepts inline array literals, which render does not. The tag is valid only in layout and templates files. The {% partial 'name' %} tag marks a named server-rendered region that JavaScript can refresh.

The preview needs a development store with the developer preview enabled, so it was not rendered for this page. Theme Check 3.31.0 understands the tag, and the following alternate template passed with no offences in a copy of the example theme.

Source: Liquid tag: block and Changelog, Liquid July '26.

Existing themes keep working with sections, theme settings and JSON templates. The preview adds a model alongside them. Because block calls are parsed statically, Theme Check can compare the arguments with the block’s schema, LiquidDoc declarations and content interface. In the same copy, adding an argument that the group block does not declare, {% block 'group', class: 'coffee-page' %}, produced the warning Unknown argument 'class' in block tag for 'group' (UnrecognizedBlockArguments), and moving the tag into sections/ produced the error from ValidBlockTagPlacement.

When a merchant edits a section or block, the editor re-renders its HTML into the existing page without a reload, so code that ran at load time must run again. Blocks identify themselves through {{ block.shopify_attributes }}, which adds data attributes that the editor’s JavaScript API reads. The editor dispatches bubbling, non-cancellable events whose target is the section or block element.

Detection helpers: request.design_mode in Liquid and Shopify.designMode in JavaScript are true in the theme editor. request.visual_preview_mode and Shopify.visualPreviewMode are true in the visual preview used when a merchant adds a new preset, which helps a block render expanded or populated for the preview. Shopify.inspectMode reports the preview inspector. The roast date badge uses request.design_mode to show a placeholder only in the editor.

Source: Integrate sections and blocks with the theme editor.

Theme Check is the offline validator for sections and blocks. The Shopify CLI embeds it, so shopify theme check needs no login. Its first run downloads the Liquid reference data, and later runs can use the cached copy. The checks below are the ones that apply to the block model.

Source: Theme Check checks and the output of shopify theme check --list (CLI 5.0.0).

The commands used for this page, run from the root of the example theme (a copy of Skeleton with the files above added):

Source: Theme Check.

Results on 2026-10-27, Shopify CLI 5.0.0 with Theme Check 3.31.0:

To prove that the checks bite, ten deliberate mistakes were introduced in a throwaway copy, one at a time or in pairs, and each was reported:

Two points came out of the runs. Passing an extra named argument to a static block, such as bogus: 1, was not reported, because arbitrary arguments are the point of the feature. The quick-start schema in the official tutorial has a trailing comma in its settings array; Theme Check 3.31.0 did not flag it in a copy of Skeleton, but strict JSON parsers reject trailing commas, so write valid JSON.

Source: Theme Check checks and local runs of shopify theme check 5.0.0.

Shopify’s theme best practices for sections and blocks reduce to a few rules that this page’s examples follow.

Source: Building with sections and blocks.

The example theme for this page puts every concept to work in one product template.

The code shown on this page was checked with Theme Check and, for the extension, with an offline shopify app build. It was not rendered in a theme editor, because that needs a store and a login, which were not used. What was run and what was not is therefore: validated offline were the schemas, targeting, static block rules, JSON template references, the preview block tag syntax and the extension bundle. Not run were the theme editor, the block picker, drag and drop ordering, dynamic source resolution at render time, app block autofill, deep links, apps.liquid wrapping and the Sidekick block generator.