JSON templates

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 order attribute, with no markup between the sections. JSON templates can render up to 20 sections, and each section can have up to 16 blocks.

Although JSON templates differ from Liquid templates in their contents, they are still template files that support the following Shopify theme features:

When you build a JSON template, you should also build a section that contains the core functionality for the template. For example, when you're building a list-collections JSON template, it should reference a section that uses the collections object.

Schema

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

Attribute Type Required Description
name String Yes A name for the template.
layout String
or
false
No The filename of the layout to use when rendering the template. For example, specify "full-width" to render layout/full-width.liquid.

The default layout is theme.liquid.

Use the value false to render the template without a layout. Templates without a layout can't be customized in the theme editor.
wrapper String No The HTML wrapper element for the template's sections. To learn more, refer to The wrapper property.
sections Object Yes An 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. JSON templates can render up to 20 sections, and each section can have up to 16 blocks.
order Array Yes An 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.

Naming JSON templates

The filename must be a valid theme template type, with an optional suffix for an alternate template. For example, a product template can be named product.json or product.alternate.json.

A template can only exist as a JSON or Liquid template, not both. For example, if product.liquid already exists, then you can't create product.json.

The wrapper property

The wrapper property makes it possible to insert HTML tags around all of the sections in a JSON template. You can use the following HTML tags:

  • <div>
  • <main>
  • <section>

For example, a JSON file with the following wrapper property produces the following output:

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 or app sections. You can't share section data across JSON theme templates, so each section must have an ID that's unique within the template.

JSON templates can render up to 20 sections, and each section can have up to 16 blocks.

You can add sections to a template in code, or through the theme editor. The sections that are available to be added to a template in the theme editor might be limited by the templates attribute of the section schema. If no templates attribute is defined, then the section can be added to any template.

The following table outlines the format of section data:

Value Type Required Description
<SectionID> String - A unique ID for the section. Accepts only alphanumeric characters.
<SectionType> String Yes The filename of the section file to render, without the extension.
<SectionDisabled> Boolean No When true, the section is not rendered but can still be customized in the theme editor. Is false by default.
<BlockID> String - A unique ID for the block. Accepts only alphanumeric characters.
<BlockType> String Yes The type of block to render, as defined in the schema of the section file.
<BlockOrder> Array No An array of block IDs, ordered as they should be rendered. The IDs must exist in the blocks object, and duplicates are not allowed.
<SettingID> String - The ID of a setting as defined in the schema of the section or the block.
<SettingValue> (multiple) - A valid value for the setting.

For example:

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