AppsThemesSupport
Guides

JSON templates

Suggest Edits

JSON templates allow you to control the look and feel of different pages of the online store using sections.

JSON templates are data files that store a list of sections to be rendered, and their associated settings. Merchants can add, remove, and reorder these sections using the theme editor. When a page is rendered with a JSON template, the sections are rendered in the order specified by the content_for_pages attribute. There's no markup between the sections.

The filename must be a valid theme template type. For example, a product template can be named product.liquid.

Template structure

JSON templates must be valid JSON files. The root should be an object with the following attributes:

AttributeTypeRequiredDescription
content_for_pageArrayYesAn array of section IDs, listed in the order that they should be rendered. The IDs must exist in the sections object. Duplicates are not allowed.
sections ObjectYesAn object that uses section IDs as keys, and section data as values. This attribute needs to contain at least one section.

Duplicate IDs within the template are not allowed.

The format of the section data is the same as section data in settings_data.json. To learn more, refer to Section data.

📘

Tip

Section files must define presets in their schema to support being added to JSON templates using the theme editor. Section files without presets should be included in the JSON file manually, and can't be removed using the theme editor.

Section data

The sections attribute of JSON templates holds the data for the sections to be rendered by the template. These can be either theme sections. You can't share section data across JSON theme templates, so each section must have an ID that's unique within the template.

The following table outlines the format of section data:

ValueTypeRequiredDescription
<SectionID>String-A unique ID for the section. Accepts only alphanumeric characters.
<SectionType>StringYesThe filename of the section file to render, without the extension.
<BlockType>StringYesThe type of block to render, as defined in the schema of the section file.
<SettingID>String-The ID of a setting as defined in the schema of the section or the block.
(multiple)-A valid value for the setting.

For example:

sections: {
  <SectionID>: {
    "type": <SectionType>,
    "settings": { 
      <SettingID>: <SettingValue 
    },
    "blocks": [
      {
        "type": <BlockType>,
        "settings": {
          <SettingID>: <SettingValue>
        }
      }
    ]
  }
}

For example, the following template renders the product.liquid and product-recommendations.liquid section files on product pages:

{
 "content_for_page": [1621646423258],
 "sections": {
   "1621646423258": {
     "type": "product",
     "settings": {
       "layout_on": false,
       "author_on": false,
       "date_on": true,
       "show_vendor": true
     },
     "version": "1",
     "card_name": "product",
     "customer_card_extra": 6,
     "customer_card_name": "product",
     "is_new": true,
     "blocks": []
   }
 }
}

🚧

Caution

Any sections that are included in a template, must exist in the theme. If they don't, then this will result in an error.

Updated about 3 years ago