---
title: "Section reference"
space: "Commera"
url: "https://docs.bwh.tech/commera/build-a-section-theme/section-reference"
updated: "2026-11-07"
---

Every setting type, block rule, limit and error message for section themes, in one place.

## Files

A section is two files in the theme's `sections/` folder. The file name, without the extension, is the section type.

```
sections/sale_banner.html
sections/sale_banner.json
```

A section type can use letters, digits and underscores. Anything else, for example `sale-banner`, is not found.

A page layout is a file in the `layouts/` folder:

| File | Page |
| --- | --- |
| `layouts/index.json` | Home page |
| `layouts/products.json` | Product list |
| `layouts/product.json` | Product page |
| `layouts/search.json` | Product list, when a shopper searches |
| `layouts/page.json` | Content pages |
| `layouts/header_group.json` | Header, on every page |
| `layouts/footer_group.json` | Footer, on every page |

There are no Python files for sections. A section gets its data from its settings, and from the `commera` object in the template.

## Section file

```json
{
	"name": "Sale banner",
	"category": "Banners",
	"settings": [],
	"blocks": {},
	"max_blocks": 3
}
```

| Key | What it does |
| --- | --- |
| `name` | The name in the editor, in the Add section list and in the section tree. |
| `category` | The group the section sits under in the Add section list. |
| `settings` | A list of settings. Each one becomes a field in the editor. |
| `blocks` | The kinds of block a merchant can add, by block type. Leave it as `{}` for none. |
| `max_blocks` | The most blocks the section can hold. If you leave it out, or set it to 0, the limit is 50. |
| `groups` | Where the section can go. The default is `["pages"]`. Use `["header_group"]` or `["footer_group"]` for header and footer sections. |
| `pages` | Limits the section to some pages, for example `["index"]`. |
| `required` | Set it to `true`, and if the theme's layout file for a page has this section, the page cannot be saved without it. |
| `max_products` | For a section with a `source` setting, how many products to load. The default is 8. |

### Setting

```json
{ "id": "title", "type": "text", "label": "Title", "default": "Flat 20% off" }
```

| Key | What it does |
| --- | --- |
| `id` | The name you use in the template: `section.settings.title`. Required. |
| `type` | One of the types below. |
| `label` | The field name in the editor. Without it, the editor shows the `id`. |
| `default` | The value until the merchant changes it. |
| `options` | For `select` only: the list of choices. |

## Setting types

| Type | Field in the editor | What the template gets |
| --- | --- | --- |
| `text` | One line of text | The text, with HTML escaped |
| `textarea` | A few lines of text | The text, with HTML escaped |
| `url` | One line of text | The text, with HTML escaped |
| `image` | An Upload button | A ready image URL, with HTML escaped. Empty if the file is missing. |
| `number` | A number | A float, for example `4.0`. Use `\| int` when you need a whole number. |
| `checkbox` | A tick box | `true` or `false` |
| `select` | A drop-down | The chosen option, as written in `options` |
| `collection` | A collection picker | The collection handle |
| `products` | A product picker | A list of product codes |

The editor does not know any other `type`. It stops with `Unknown section setting type: <type>`.

The editor shows each `select` option with its first letter in capitals and `_` or `-` changed to a space. So `on_sale` shows as On sale.

A text value can also be saved for each language, for example `{"en": "Sale", "ar": "..."}`. The template gets the one that matches the page language. If there is none, it gets the English one, or the first one.

### Images

An `image` value can be:

| Value | Result |
| --- | --- |
| `images/hero.webp` | A file in your theme's `public/themes/<theme>/` folder. |
| `/files/dress.webp` | A file a merchant uploaded. It must exist. |
| `/assets/...`, `http://...`, `https://...` | Used as written. |

If the merchant clears an image, the `default` of the setting is used.

### The `source` setting

A section with a setting called `source` gets a `section.products` list, filled in before your template runs. The section is left out of the page when the list is empty. Use these option names:

| `source` | Products | Needs the setting |
| --- | --- | --- |
| `newest` | The newest products | |
| `on_sale` | Products with a sale price | |
| `collection` | Products in one collection | `collection` |
| `hand_picked` | The products the merchant picked | `products` |

Do not use `source` as a name for anything else.

## Blocks

```json
"blocks": {
	"offer": {
		"name": "Offer",
		"settings": []
	}
}
```

The key (`offer`) is the block type. `name` is what the editor shows. `settings` works like the section's settings.

In the template, `section.blocks` is the list of blocks. Each block has `type`, `id` and `settings`.

Add `{{ block.editor_attributes }}` to the block's outer tag. The editor uses it to select the block when the merchant clicks it in the preview. It prints nothing on the live store.

Blocks of a type that the section does not list are skipped. Blocks after the `max_blocks` limit are not shown.

## Layout file

```json
{
	"sections": [
		{
			"id": "hero",
			"type": "hero",
			"hidden": false,
			"settings": { "background": "warm" },
			"blocks": [
				{ "id": "slide-1", "type": "slide", "settings": { "image": "images/hero.webp" } }
			]
		}
	]
}
```

| Key | Rule |
| --- | --- |
| `id` | Required. Each section id must be different on a page. Each block id must be different inside its section. |
| `type` | Required. The file name of a section in the theme. |
| `hidden` | `true` or `false`. A hidden section stays in the editor and is left out of the store. |
| `settings` | Only setting ids that the section file lists. You can leave out any setting, and its `default` is used. |
| `blocks` | A list. Only block types that the section file lists. |

A merchant's saved layout comes before the layout file. See [Ship it](/commera/build-a-section-theme/ship-it).

## Errors

These are the messages that come back when a layout cannot be saved. A layout file is not checked when the store loads. A section type that does not exist is skipped, and its place on the page is empty.

| Message | What to do |
| --- | --- |
| `A layout must be an object with a "sections" list.` | The file must be `{ "sections": [ ... ] }`. |
| `Section entries need an id and a type.` | Add `id` and `type` to every section. |
| `Block entries need an id and a type.` | Add `id` and `type` to every block. |
| `Section id <id> is used twice.` | Give each section a different `id`. |
| `Block id <id> is used twice.` | Give each block in the section a different `id`. |
| `Section type <type> does not exist in this theme.` | There is no `sections/<type>.json` file. Check the spelling. |
| `Section type <type> cannot be used in <page>.` | The section's `groups` or `pages` do not allow it on this page. |
| `Section <id>: hidden must be true or false.` | Use `true` or `false`, without quotes. |
| `Section <id>: blocks must be a list.` | Use `[ ... ]` for `blocks`. |
| `Section <id> allows at most <number> blocks.` | Remove blocks, or raise `max_blocks`. |
| `Section <id> does not allow blocks of type <type>.` | Add the block type to the section's `blocks`. |
| `<Name> section: settings must be an object.` | Use `{ ... }` for `settings`. |
| `<Name> section: unknown setting <id>.` | The section's `.json` file has no setting with this `id`. |
| `<Name> section: "<Label>" has the wrong type.` | The value does not fit the type. For example, `select` values must be one of the `options`, and `checkbox` must be `true` or `false`. |
| `<Name> section: image <path> is not an uploaded file.` | A `/files/...` image that is not in the site. |
| `<Name> section: image <path> does not exist in this theme.` | No such file in the theme's `public/themes/<theme>/` folder. |
| `<Name> section: product <code> does not exist or is not published.` | Use the code of a published product. |
| `<Name> section: collection <handle> does not exist.` | Use a collection handle that exists. |
| `The <page> page needs its <Name> section.` | The section has `"required": true`. Put it back. |

For a block, `<Name> section` is `<Block name> block in <Section name> section`.

If a section fails while it renders, the page shows the rest of the sections and the Error Log gets an entry called `Theme section <type> failed to render`.

## Next steps

- [Add sections](/commera/build-a-section-theme/add-sections)
- [Ship it](/commera/build-a-section-theme/ship-it)
