---
url: https://docs.youcan.shop/themes/templates/json-templates.md
---
# JSON templates

A JSON template is a `.json` file in the theme's `templates` directory that describes which [sections](/themes/sections/overview) render on a page, in what order, and with what settings. Unlike a Liquid template, its contents are data: the theme editor reads and writes this file as sellers add, remove, reorder, and configure sections.

## Location

```bash
└── theme
    ├── layout
    ├── templates
    │   ├── index.json
    │   ├── product.json
    │   ├── cart.json
    │   ...
    ...
```

## Structure

```json
{
  "label": "Search",
  "layout": "theme",
  "sections": {
    "main-search": {
      "type": "main-search",
      "settings": {}
    }
  },
  "order": ["main-search"]
}
```

At minimum a template needs a `sections` object and an `order` array. Everything else is optional.

## Top-level properties

| Property | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `sections` | `object` | Yes | Maps a section ID to a [section object](#section-object). A template can hold between 1 and 25 sections. |
| `order` | `array` | Yes | Section IDs listed in render order. Every ID must be a key in `sections`; duplicates aren't allowed. Sections omitted from `order` aren't rendered. |
| `label` | `string` | No | The template's display name in the theme editor. Max 255 characters. |
| `layout` | `string` | No | Filename (without extension) of the [layout](/themes/layouts) the template renders into. Defaults to `theme`. Set to `null` to render without a layout. |
| `wrapper` | `string` | No | HTML element that wraps the template's sections. One of `div`, `section`, or `main`. |

## Section object

Each entry in `sections` is keyed by a section ID (letters, numbers, `-`, and `_`, up to 40 characters) and holds:

| Property | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `type` | `string` | Yes | The section filename (without extension) in the `sections` directory, e.g. `"slideshow"` renders `sections/slideshow.liquid`. |
| `settings` | `object` | No | Values for the section's settings, keyed by the setting `id` defined in the section's [`{% schema %}`](/themes/sections/section-schema). |
| `blocks` | `object` | No | Maps a block ID to a [block object](#block-object). Up to 25 blocks per section. |
| `order` | `array` | No | Block IDs listed in render order. Every ID must be a key in `blocks`; duplicates aren't allowed. Required whenever `blocks` is present. Blocks missing from `order` aren't rendered. |
| `disabled` | `boolean` | No | When `true`, the section is kept in the file and stays configurable in the editor but isn't rendered. Defaults to `false`. |

```json
"slideshow": {
  "type": "slideshow",
  "settings": {},
  "blocks": {
    "slide_1": {
      "type": "slide_item",
      "settings": {
        "slide_heading": "Explore a fantastic world",
        "first_button_label": "Shop Now"
      }
    },
    "slide_2": {
      "type": "slide_item",
      "settings": { "slide_heading": "New arrivals" }
    }
  },
  "order": ["slide_1", "slide_2"]
}
```

## Block object

Each entry in a section's `blocks` is keyed by a block ID (same rules as section IDs) and holds:

| Property | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `type` | `string` | Yes | The block type as declared in the section's schema `blocks`. |
| `settings` | `object` | No | Values for the block's settings, keyed by setting `id`. |

## Ordering and IDs

* `order` arrays (at both template and section level) are the source of truth for what renders and in what sequence. An entry in `sections` or `blocks` with no matching ID in the corresponding `order` is stored but not rendered.
* IDs only need to be unique within their scope and stable across edits. The theme editor generates values like `block_65254f3c09e4c8`; hand-written templates can use readable IDs like `slide_1`.
* A section's `type` can repeat across different IDs. That's how a page shows the same section more than once with different settings.

## Full example

```json
{
  "sections": {
    "slideshow": {
      "type": "slideshow",
      "settings": {},
      "blocks": {
        "slide_1": {
          "type": "slide_item",
          "settings": { "slide_heading": "Explore a fantastic world" }
        }
      },
      "order": ["slide_1"]
    },
    "featured-collection": {
      "type": "featured-collection",
      "settings": {
        "heading": "New Arrivals",
        "button_label": "View all"
      }
    },
    "faqs": {
      "type": "faqs",
      "settings": { "heading": "FAQs" },
      "disabled": true
    }
  },
  "order": ["slideshow", "featured-collection", "faqs"]
}
```