Sections

Learn how to create and customize theme sections.

Introduction to Sections

Sections are modular components that allow you to build flexible and customizable theme layouts in Finqu. They can be added, removed, and reordered to create unique page structures.

How Sections Are Rendered

Sections are rendered in templates using either the content_for_index placeholder (which outputs all sections assigned to that template) or the section tag to render a specific section:

{% section 'section-name' %}

Section Directory

All section files are stored in the sections directory of your theme. Each file represents a single section and contains its Liquid markup, logic, and schema.

Section Schema

Each section file defines its configuration using a {% schema %} tag. The schema describes the section’s name, description, tag, class, category, keywords, and settings. For example:

{% schema %}
{
  "name": {
    "en": "Accordion tabs",
    "fi": "Välilehdet"
  },
  "description": { "en": "A set of collapsible question-and-answer panels." },
  "tag": "section",
  "class": "section section-accordion-tabs",
  "category": "theme-featured",
  "keywords": {
    "en": ["accordion tabs", "faq", "guide"],
    "fi": ["välilehdet", "ukk", "opas"]
  },
  "settings": {
    // ...section settings...
  }
}
{% endschema %}

• The category property must match one of the categories defined in your theme’s settings_schema.json file.

Section Schema Properties

Below is a table describing the main properties available in a section schema, along with explanations and examples for each:

Each property helps define how the section appears and behaves in the theme editor and on the storefront. For more details on settings and blocks, see the relevant documentation sections below.

See the full section schema definition  for the authoritative, machine-validated shape.

Section Groups

A section group is an ordered, merchant-managed collection of sections that is shared across pages — for example a header or footer region that appears on every template. Unlike a template’s own sections (which live only on that template), the sections in a group are stored once and rendered wherever the group is included.

Define a group

Create a JSON file under the theme’s section-groups/ folder. The filename (without extension) is the group name.

section-groups/header-group.json

{
  "name": {
    "en": "Header",
    "fi": "Ylätunniste"
  },
  "max_sections": 10,
  "allowed_sections": ["announcement-bar", "header", "navigation"],
  "default_sections": [
    {
      "name": "announcement-bar",
      "title": "Announcement",
      "settings": {},
      "blocks": [],
      "sticky": false
    },
    {
      "name": "header",
      "title": "Header",
      "settings": {},
      "blocks": [],
      "sticky": true
    }
  ]
}

Definition fields

default_sections entry

Render a group in a layout or template with the {% sections %} tag. See Templates & Layouts for layout examples.

Opt a section into a group

A section declares which group(s) it belongs to via section_groups in its {% schema %}. When set, the section is only addable inside those groups — never in free template content.

sections/announcement-bar.liquid

<div class="announcement-bar"> ... </div>
 
{% schema %}
{
  "name": { "en": "Announcement bar" },
  "section_groups": ["header-group"],
  "settings": []
}
{% endschema %}

How the two whitelists interact

A section is offered for a group when both are satisfied:

1. The section’s section_groups includes the group (or is empty — then it may be used in any group), and
2. The group’s allowed_sections includes the section (or is empty — then any opted-in section is allowed).

The stricter of the two always wins.

Section creatability and placement flags

These apply to sections regardless of groups:

Group section data is stored on the release configuration under section_groups[groupName].sections, not on individual templates, which is what makes a group shared across pages. If a group has no stored configuration yet, default_sections is used to build the initial layout.

Blocks in Sections

Sections can contain blocks, which are reusable content elements defined in the theme’s blocks/ directory. Blocks are rendered inside a section using the container tag. You can optionally define an id for the container:

{% container 'id' %}

The container tag is not a block tag, but a way to group and render blocks within a section. The id can be used to target a specific container for styling or logic. An unnamed {% container %} renders blocks that have no container assignment — this is fine for a section with a single drop zone and no declared containers. Id must be unique within the section and must be defined if the section contains multiple containers.

Use allowed_blocks in the section schema to restrict which blocks merchants can add at the section’s top level. See Blocks for the full resolution rules.

Repeatable item types in the settings sidebar (e.g. carousel slides) use setting_blocks inside grouped settings — not the section schema root. See Settings for that pattern.

Section Containers

For sections with more than one drop zone, declare named containers via containers in the schema — the same containerDefinition shape used by layout blocks:

<section class="two-column">
  <div class="two-column__left">
    {% container 'left' %}
  </div>
  <div class="two-column__right">
    {% container 'right' %}
  </div>
</section>
 
{% schema %}
{
  "name": { "en": "Two columns" },
  "category": "theme-featured",
  "containers": [
    { "id": "left", "title": { "en": "Left column" } },
    { "id": "right", "title": { "en": "Right column" } }
  ]
}
{% endschema %}

Container Preset Blocks

A container’s preset.blocks array is a fallback, used only when the section is statically imported (rendered via {% section 'name' %} in a template) and has no stored configuration. Preset blocks render read-only in the designer until the merchant makes the first change, at which point they are persisted as real block instances — see Container Preset Blocks in the Blocks doc for the full mechanics, which are identical here.

{
  "id": "left",
  "title": { "en": "Left column" },
  "preset": {
    "blocks": [
      "rich-text",
      { "name": "image-block", "settings": { "fit": "cover" } }
    ]
  }
}

Block shorthand (a bare block-type name string) is only valid inside preset.blocks.

Section Presets

The presets property defines ready-made variants shown in the add-section picker. Unlike container presets, which are a read-only fallback, a section preset is applied eagerly — when a merchant picks it, its settings and blocks are written into the section’s stored configuration immediately.

presets accepts a plain array or a locale-keyed map:

{
  "name": { "en": "Hero" },
  "category": "theme-featured",
  "presets": [
    {
      "name": { "en": "Centered" },
      "default": true,
      "settings": {
        "heading": "Welcome",
        "alignment": "center"
      }
    },
    {
      "name": { "en": "With button" },
      "settings": { "heading": "Welcome" },
      "blocks": [
        { "name": "buy-button", "settings": { "label": "Shop now" } }
      ]
    }
  ]
}

Preset block instances

Each entry in a preset’s blocks array is authored declaratively as a tree:

Internal fields (parent_block_id, is_static, blocks_customized) are derived when the preset is applied — never author them by hand.

For localized preset copy (different heading/body text per market) and locale-keyed preset maps, see Localization.

Sticky sections in templates

Sections listed in a template’s template_sections schema are sticky: always present on that template, reorderable but not removable by merchants. See Templates & Layouts for how sticky sections interact with {{ content_for_index }}.

Section Best Practices

• Use clear and descriptive names and categories for your sections.
• Organize settings and blocks logically for ease of use.
• Reuse blocks and settings where possible to keep sections maintainable.
• Test your sections in different templates to ensure flexibility and compatibility.