---
url: https://docs.youcan.shop/themes/sections/section-schema.md
---
# Section schema

Every section can include a single `{% schema %}` tag containing a JSON object. This schema tells the theme editor the section's name, what settings and blocks it exposes, and which templates it can be added to.

```liquid
{% schema %}
{
  "name": "Featured products",
  "settings": [],
  "blocks": []
}
{% endschema %}
```

> **Note:** The schema must be valid JSON. Only one `{% schema %}` tag is allowed per section, and it can't contain Liquid.

## Attributes

| Attribute | Type | Description |
| --------- | ---- | ----------- |
| `name` | `string` | Required. The section name shown in the theme editor. Can be a `t:` locale key. `label` is accepted as a deprecated alias. |
| `tag` | `string` | The HTML element the section is wrapped in. One of `article`, `aside`, `div`, `footer`, `header`, or `section`. Defaults to `section`. |
| `class` | `string` | A class added to the section wrapper element. |
| `limit` | `integer` | The maximum number of times the section can be added to a single template. Defaults to `25`, and can't exceed `25`. |
| `max_blocks` | `integer` | The maximum number of blocks the section can hold. Defaults to `25`, and can't exceed `25`. |
| `settings` | `array` | [Setting](/themes/settings/overview) definitions for the section, read through `section.settings`. |
| `blocks` | `array` | The [block](/themes/blocks) types the section accepts. |
| `presets` | `array` | The ready-made versions of the section that sellers can pick. See [`presets`](#presets). |
| `enabled_on` | `object` | The templates and section groups the section can be added to. See [`enabled_on` and `disabled_on`](#enabled-on-and-disabled-on). |
| `disabled_on` | `object` | The templates and section groups the section cannot be added to. See [`enabled_on` and `disabled_on`](#enabled-on-and-disabled-on). |
| `templates` | `array` | The [template types](/themes/templates/overview#template-types) the section can be added to from the editor. When omitted, the section is available on all templates. |

## `settings`

An array of setting schema objects. Each entry renders an input (or a display element) in the theme editor.

```json
"settings": [
  { "type": "header", "content": "Layout" },
  {
    "type": "select",
    "id": "layout",
    "label": "Layout",
    "options": [
      { "value": "grid", "label": "Grid" },
      { "value": "carousel", "label": "Carousel" }
    ],
    "default": "grid"
  },
  {
    "type": "range",
    "id": "products_per_row",
    "label": "Products per row",
    "min": 2,
    "max": 5,
    "step": 1,
    "default": 4
  }
]
```

Values are read in Liquid through `section.settings`:

```liquid
{% if section.settings.layout == 'carousel' %}
  ...
{% endif %}
```

See [Input settings](/themes/settings/input_settings) and [Display settings](/themes/settings/display_settings) for the available types.

## `blocks`

An array of the block types a section accepts. Each block has its own `settings` array.

```json
"blocks": [
  {
    "type": "product",
    "name": "Product",
    "limit": 12,
    "settings": [
      { "type": "product", "id": "product", "label": "Product" }
    ]
  }
]
```

| Property | Type | Description |
| -------- | ---- | ----------- |
| `type` | `string` | Required. Identifier for the block type, referenced as `block.type` in Liquid. |
| `name` | `string` | Required, except for the `@app` type. The block name shown in the editor. Can be a `t:` locale key. `label` is accepted as a deprecated alias. |
| `limit` | `integer` | The maximum number of blocks of this type allowed in the section. Defaults to `50`, and can't exceed `50`. |
| `settings` | `array` | Setting definitions for the block, read through `block.settings`. |

Iterate blocks in the section markup, branching on `block.type`:

```liquid
{% for block in section.blocks %}
  {% case block.type %}
    {% when 'product' %}
      <div {{ block.youcan_attributes }}>
        {{ block.settings.product.title }}
      </div>
  {% endcase %}
{% endfor %}
```

See [Blocks](/themes/blocks) for the full rendering and theme-editor details.

To accept [theme blocks](/themes/theme-blocks), use entries with only a `type`: `@theme` for all public theme blocks, the type of a theme block, or `@app` for app blocks. A section schema cannot have both theme block entries and its own block types.

```json
"blocks": [
  { "type": "@theme" },
  { "type": "@app" }
]
```

## `presets`

A preset is a ready-made version of the section. Sellers pick a preset in the theme editor to add the section, and each preset is listed as its own entry.

```json
"presets": [
  {
    "name": "Image banner",
    "category": "Banners",
    "settings": { "height": "large" },
    "blocks": [
      { "type": "heading", "settings": { "heading": "Browse our latest products" } },
      { "type": "button", "settings": { "label": "Shop all" } }
    ]
  }
]
```

| Property | Type | Description |
| -------- | ---- | ----------- |
| `name` | `string` | Required. The preset name shown in the theme editor. Can be a `t:` locale key. `label` is accepted as a deprecated alias. |
| `category` | `string` | The group the preset is listed under in the theme editor. Can be a `t:` locale key. |
| `settings` | `object` | Setting values for the section, keyed by setting `id`. Settings that are not in the preset get their default value. |
| `blocks` | `array` | `object` | The blocks added with the preset. Each block has a `type`, and can have `settings`. A theme block can also have `blocks`, `static` and `id`. |
| `block_order` | `array` | The order of the blocks, when `blocks` is an object. |

## `enabled_on` and `disabled_on`

Use `enabled_on` to list the templates and [section groups](/themes/sections/section-groups) a section can be added to, or `disabled_on` to list the ones it cannot be added to. Only one of the two can be used in a section. Use `"*"` for all templates or all groups.

```json
"enabled_on": {
  "templates": ["index", "product"],
  "groups": ["header"]
}
```

```json
"disabled_on": {
  "templates": ["cart"]
}
```

| Property | Type | Description |
| -------- | ---- | ----------- |
| `templates` | `array` | [Template types](/themes/templates/overview#template-types), or `"*"`. |
| `groups` | `array` | [Group types](/themes/sections/section-groups#file-format) (`header`, `footer`, `aside`, `custom.<name>`), or `"*"`. |

With `enabled_on`, the section is not offered on a template or a group that is not listed. When `templates` is not set in `enabled_on`, the section is not offered on any template. When `groups` is not set in `enabled_on`, the section is not offered in any group.

## `templates`

Lists the [template types](/themes/templates/overview#template-types) a section can be added to from the theme editor. Omit it to make the section available everywhere.

```json
"templates": ["index", "product", "page"]
```

## Example

```liquid
{% schema %}
{
  "name": "Featured collection",
  "tag": "section",
  "class": "featured-collection",
  "limit": 2,
  "max_blocks": 4,
  "templates": ["index", "collection"],
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Featured collection" },
    { "type": "collection", "id": "collection", "label": "Collection" },
    { "type": "range", "id": "products_to_show", "label": "Products to show", "min": 2, "max": 12, "step": 1, "default": 6 }
  ],
  "blocks": [
    {
      "type": "cta",
      "name": "Call to action",
      "limit": 1,
      "settings": [
        { "type": "text", "id": "label", "label": "Button label" },
        { "type": "url", "id": "link", "label": "Button link" }
      ]
    }
  ]
}
{% endschema %}
```