Section groups

A section group is a JSON file in sections/ that bundles several sections into one shared region — the header, the footer, an aside, or a custom band — so the same stack of sections renders on every page that includes it. Edit the header group once and the change applies storewide, because each template pulls the group in by reference rather than copying it.

Section groups are the counterpart to JSON templates. A template builds the body of one page type; a group builds a band that’s the same across many page types. Both are composed from sections, so they share the same sections / order shape and the same editing surface.

File shape

A group file lives at sections/<name>.json and is a JSON object with four keys:

{
  "type": "header",
  "name": "Header",
  "sections": {
    "announcement": {
      "type": "announcement-bar",
      "settings": { "text": "Free shipping over ₹999" }
    },
    "main-header": {
      "type": "header",
      "settings": { "sticky": true }
    }
  },
  "order": ["announcement", "main-header"]
}

Key	Type	Purpose
`type`	string	The group’s role — one of `header`, `footer`, `aside`, or `custom.<name>`
`name`	string	Label shown in the visual editor (max 50 characters)
`sections`	object	The section instances, keyed by an id you choose
`order`	array	The ids from `sections`, in the sequence they render

Each entry in sections is a section instance — exactly the same shape used inside a JSON template. It carries a type (the section file to render) plus optional settings, blocks, block_order, and a disabled flag. A disabled instance is skipped at render time but kept in the file so you can toggle it back on in the editor.

Group types

The type field declares which region the group fills, and it must be one of:

Type	Used for
`header`	The top band — announcement bar, logo, menu, cart
`footer`	The bottom band — links, newsletter, policies, payment icons
`aside`	A side region, such as a slide-out menu or drawer
`custom.<name>`	Any other shared region you define, e.g. `custom.overlay`

A custom type’s suffix must match custom.<letters-digits-hyphens-underscores>, for example custom.popups. Any other value fails validation with invalid "type" … Expected header|footer|aside|custom.<name>.

Rendering with `{% sections %}`

A group never renders on its own. You include it from the layout with the {% sections %} tag, passing the group’s handle (the file name without the .json extension):

{% comment %} layout/theme.liquid {% endcomment %}
<body>
  {% sections 'header' %}
  <main>{{ content_for_layout }}</main>
  {% sections 'footer' %}
</body>

The tag has two firm rules, both enforced at render time:

Layout only. {% sections %} can be used only in a layout/*.liquid file. Calling it from a section, snippet, or template throws {% sections %} can only be used in layout files.
One quoted handle. The argument must be a single quoted name, e.g. {% sections 'footer' %}. The handle may include letters, digits, _, ., and -; a missing or malformed argument throws Usage: {% sections 'name' %}.

When the tag runs, it loads the matching group file, validates it, then renders each instance in order, skipping any marked disabled. An empty order renders nothing on the live storefront (and a placeholder region in the editor so you can still add sections to it).

Validation rules

A group file is validated when the theme is imported, saved, and rendered, so these rules are enforced, not advisory. A failing group blocks the save with a specific error.

type is valid — one of header, footer, aside, or custom.<name>.
sections is an object and order is an array — missing or wrong-typed either one fails with must define a "sections" object / must define an "order" array.
Per-group cap. A group may contain at most 25 sections. A longer order fails with exceeds the maximum of 25 sections.
order references existing instances. Every id in order must exist as a key in sections; a dangling id fails with order references missing section. order may not repeat an id (Duplicate section id), and every key in sections must appear in order (sections are missing from order).
Each instance has a type. An instance without a string type fails with sections[…].type is required.

Gating which sections can join a group

A section’s schema can restrict where it’s allowed to appear using enabled_on or disabled_on (use one, never both). Alongside templates, those rules accept a groups array that limits the section to specific group types:

{% comment %} the {% schema %} of sections/announcement-bar.liquid {% endcomment %}
{
  "name": "Announcement bar",
  "enabled_on": {
    "groups": ["header"]
  },
  "settings": []
}

The values allowed in a groups array are:

Token	Meaning
`*`	Any group
`header`	Header groups only
`footer`	Footer groups only
`aside`	Aside groups only
`custom.<name>`	A specific custom group, e.g. `custom.overlay`

Any other value fails validation with groups contains invalid group. Use this to keep, say, a footer-only newsletter section out of the header group, or to make an announcement bar offerable only inside the header.

Editing groups in the visual editor

In the visual editor (Online store → Themes, then Customize), section groups appear in the left sidebar as their own regions, separate from the template sections of the current page. The header and footer regions show on every page because the layout includes them everywhere, so you can edit them from any template.

Within a group region you can:

Add a section — only sections whose enabled_on/disabled_on rules allow that group type are offered.
Reorder sections — drag to change the order.
Edit a section’s settings and blocks — the same controls as a template section.
Hide a section — sets disabled so it’s skipped on the storefront but stays in the file.

Because the change is saved to the shared group file, it takes effect on every page that includes the group — that’s the point of a section group.

Group vs. template — at a glance

	Section group	JSON template
File	`sections/header.json`	`templates/product.json`
Rendered by	`{% sections 'header' %}` in the layout	The page-type router
Scope	One shared band, every page that includes it	One page type’s body
Section cap	25	Per-template limits
Shape	`type`, `name`, `sections`, `order`	`sections`, `order`, `layout`, …

Next steps

Theme architecture

How templates, sections, blocks, and groups fit together — Theme architecture.

Section schema

Every key of a section’s {% schema %}, including enabled_on/disabled_on — Section schema.

Liquid tags

The {% sections %} tag and the rest of the theme tag set — Liquid tags.