# 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:

```liquid
{% 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:

```liquid
{% 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:

| Property   | Description                                                                 | Example |
|------------|-----------------------------------------------------------------------------|---------|
| `name`     | The display name of the section, usually localized for different languages. **Required.** | `{ "en": "Accordion tabs", "fi": "Välilehdet" }` |
| `description` | Optional description shown in the editor and used for discovery.       | `{ "en": "A set of collapsible question-and-answer panels." }` |
| `category` | The category for the section, must match a category in [`settings_schema.json`](/build-with-finqu/liquid-themes/settings#theme-settings-settings_schemajson). **Required.** | `"theme-featured"` |
| `tag`      | The HTML tag or identifier for the section.                                 | `"section"` |
| `class`    | CSS classes applied to the section container.                               | `"section section-accordion-tabs"` |
| `keywords` | Search tags for the add-section picker. A plain string array or locale-keyed arrays. | `["hero", "banner"]` or `{ "en": ["accordion tabs", "faq"], "fi": ["välilehdet", "ukk"] }` |
| `templates` | Template types the section is available on. Empty or absent = all templates. | `["product"]` |
| `section_groups` | Restrict the section to specific section groups. When set, the section is only addable inside those groups. | `["header-group"]` |
| `is_creatable` | If `false`, the section cannot be added by merchants (e.g. a fixed, theme-controlled section). Defaults to `true`. | `false` |
| `allowed_blocks` | Whitelist of block names accepted at the section's top level. Empty or absent = all public, template-compatible blocks. | `["product-title", "buy-button"]` |
| `settings` | [Configuration options](/build-with-finqu/liquid-themes/settings) for the section. Use `settings.groups[].setting_blocks` for repeatable settings item types in the sidebar — not theme `{% block %}` instances. | `{ /* ...section settings... */ }` |
| `containers` | Named drop zones within the section, each with optional preset blocks. See [Section Containers](#section-containers). | `[{ "id": "sidebar" }]` |
| `presets`  | Predefined variants shown in the add-section picker. See [Section Presets](#section-presets). | `[{ "name": "Default", "default": true }]` |

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.

## 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`

```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

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | string \| localized object | — | Display name of the group in the designer. |
| `max_sections` | number | `25` | Maximum number of sections a merchant may add to the group. |
| `allowed_sections` | string[] | `[]` (all) | Whitelist of section names addable in this group. Empty/absent = any section that opts into the group. |
| `default_sections` | object[] | `[]` | Sections rendered when the merchant has not customized the group yet. |

#### `default_sections` entry

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Section name (file in `sections/`). |
| `title` | string | Label shown in the designer section list. |
| `settings` | object | Initial section settings. |
| `blocks` | array | Initial blocks for the section. |
| `sticky` | boolean | If `true`, the section can be reordered but not removed. |

Render a group in a layout or template with the `{% sections %}` tag. See [Templates & Layouts](/build-with-finqu/liquid-themes/templates-layouts#section-groups) 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`

```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:

| Schema field | Effect |
|--------------|--------|
| `is_creatable: false` | The section cannot be added by merchants at all (e.g. a fixed, theme-controlled section). |
| `section_groups: [...]` | The section is group-only; it will not appear in the normal "add section" list for template content. |
| `templates: [...]` | The section is only offered on matching template types. The template **type** is the part before the first dot — e.g. `product` and `product.custom` both have type `product`. |

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:

```liquid
{% 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](/build-with-finqu/liquid-themes/blocks#allowed_blocks-whitelist) 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](/build-with-finqu/liquid-themes/settings#setting-blocks) 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](/build-with-finqu/liquid-themes/blocks#layout-blocks-and-containers):

```liquid
<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 %}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Container identifier, referenced by `{% container 'id' %}`. **Required.** |
| `title` | string \| localized object | Label shown for the container in the designer. |
| `type` | string | Container type, e.g. `"static"` for a fixed container. |
| `allowed_blocks` | string[] | Optional whitelist of block names addable into this container. Empty/absent = any public block. |
| `preset` | object | Blocks seeded into this container when the section is statically imported with no stored configuration. See [Container Preset Blocks](#container-preset-blocks) below. |

### 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](/build-with-finqu/liquid-themes/blocks#container-preset-blocks) in the Blocks doc for the full mechanics, which are identical here.

```json
{
  "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:

```json
{
  "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" } }
      ]
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Optional stable identifier for this preset variant. |
| `name` | string \| localized object | Label shown for this preset in the add-section picker. |
| `default` | boolean | If `true`, this is the default preset offered. |
| `settings` | object | Setting id → value pairs (and `setting_blocks`) applied to the section. |
| `blocks` | array | Block instances applied to the section immediately on add. When present, [container presets](#container-preset-blocks) are **not** used for that section — the preset's `blocks` takes over entirely. |

### Preset block instances

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

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Block type name (matches a file in `blocks/`). **Required.** |
| `id` | string | Optional stable id matching a theme-placed static block's `{% block 'name' id:'...' %}` tag. When set, this preset block seeds or overrides that static block's children instead of creating a new instance. |
| `settings` | object | Setting values for the instance. |
| `container` | string \| null | Container id this block belongs to, or omitted/`null` for the default container. |
| `blocks` | array | Nested preset blocks, for preset blocks that are themselves layout or static blocks with containers. |

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](/build-with-finqu/liquid-themes/localization#presets).

## 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](/build-with-finqu/liquid-themes/templates-layouts#template-schema) 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.