Theme.json

Settings set in theme.json declare the sections and blocks available for use within the theme customiser, and the colour schemes available.

"formatVersion": 5
Denotes that the theme uses the new Version 5 interface. This value is used when the theme is first installed. Changing the formatVersion from another value to 5 after theme installation will have no effect.

When formatVersion is 5, the theme can define sections, blocks, and colour schemes in theme.json, as described in this guide.

settingEditor can be used to set additional properties about how the live preview should look and behave.

The responsiveBreakpoints property can be used to set pixel widths at which point the content breaks into a new responsive design, e.g.

A property of liveSectionReordering can be set to true for the platform to send back to the theme "messages" about the order of sections on a page, enabling the theme to re-order the sections in real time (without reloading the preview). If this feature is enabled, the platform will no longer reload the preview during section reordering.

The platform will send the following messages to the theme:

• selectSection - when dragging starts (the theme can highlight the section)
• deselectSection - when dragging ends
• moveSection - when the position of a section changes

The data for each message will be an object with id, moveSection will also send newPosition (a positive integer).

The sections property must be an array of section objects. A maximum of 75 section objects can be defined.

The required format is:

• name (string, required, maximum length 50, only letters, digits, - and _)
• label (string, optional, maximum length 50)
• icon the icon to display for the section
• settings (array, optional, a maximum of 30 settings are allowed per section, same format as theme settings)
• pageTypes (array, optional, described below)
• separator mark as true to show a gap between it and the section above it (on the 'available sections' sidebar)
• maxBlocks to specify the maximum number of blocks that can be configured for the section
• maxInstances to specify the maximum number of sections of this type a page can have

Adding a property of "separator": true to a section will ensure it appears with a gap above it when in the list of available sections to be added to a page. This is used to group similar sections together.

Settings within a section can be grouped. Within the setting, add a group property:

It is not possible to choose an icon for grouped settings; the default cog icon is used.

Some section types should not be available to be added to all pages (e.g. a 'product information' section should only be available for the product page). By default, a section is assumed to be able to be added to any page type. Use the pageTypes array to specify available page types.

A property of pageTypes (an array of page types) can be used to define available page types for the section. A limit of 20 pageTypes can be defined for each section.

Each section must have a corresponding twig file, stored in views/sections. The section file name must match the section name (e.g. a section named image_slider will be loaded from views/sections/image_slider.twig

A render function is available for rendering sections. Installed sections (a section added by a customer through the interface) will be exposed via global.theme.sections variable.

{{ render(global.theme.sections) }}

When using the render function, sections do not have access to the parent template, and, therefore, its variables. They are confined to the sections directory (meaning they cannot include / extend templates from other directories). The render function supports a second argument for passing additional data, e.g.

{{ render(global.theme.sections, { product: product, customer: global.customer, gts: global.theme.settings }) }}

(passes the product, customer and global.theme.settings objects to the section).

Use the render_with_context function instead (preferred) to grant access to the parent template and its variables, e.g.

{{ render_with_context(global.theme.sections) }}

Each rendered section will be wrapped in a div by the platform. An ID (random string of letters and numbers) is added within the div to help the theme identify which section settings are being set by a user (when multiple sections of the same type/name are defined on a page).

A section Twig variable will be available inside section views. The variable has the following properties: type (string), settings (array), id and blocks (array)

• The type property relates to the section name, when rendered
• The settings property is an object of the settings defined for the section
• The id property returns the unique platform-generated ID for the configured section, when rendered.

Within theme.json, the defaultSections property is available. It must be an array of page objects and defines which of the available sections are installed in a theme, by default, when the theme is installed by a user, e.g.

Each section can be either a string (like section1) or an object (with type and optional enabled and blocks). If the section is always enabled and does not have blocks, then a string is a way of defining the section in a more concise way.

Each block can be either a string (like block1) or an object (with type and the optional enabled property).

Sections and their blocks can be installed by default but not enabled (so that the user can easily enable them without having to enable). To denote enabled sections or blocks, an enabled property is available.

Available page names for defining the default sections are as above.

Within theme.json a blocks property (array) is available for sections, e.g.

Each block can have:

• name (string, required, maximum length 50, only letters, digits, - and _)
• label (string, optional, maximum length 50)
• icon which icon to display for the block
• settings (array, optional, a maximum of 30 settings are allowed per block, same format as theme settings)
• maxInstances set to determine the maximum number of instances of the block type that can be configured for the section

Within the settings array, an individual setting (where it is either a single image or text setting) can be marked as "identifier": true. In the theme editor, the image will be used in place of the block icon and the text will be used in place of the block name.

Blocks have additional properties to specify whether blocks are installed by default and enabled by default as defined above (in the default sections and blocks section).

Within the section Twig variable, available inside section views, blocks will return as an array (if defined).

Each block has properties of:

• type (corresponding to the defined block name)
• settings (an object of the defined settings)
• is_app_block (for use by app blocks)

The id property returns the unique platform-generated ID for the configured block, when rendered.

If is_app_block is true it means the block is an app block (type and settings will be empty in this case) and will need to be rendered using the render function.

or

or

Content Areas are 'pseudo sections' and allow you to specify content on a twig view that is not defined within a section file, but still behaves like a section (in that it appears in the theme editor sidebar as a section and can be moved into a new position).

Content areas do not have to be defined in a twig view, but are rendered in the sidebar as a content area by defining them in theme.json.

Within the sections array, add in the content area in the following format:

• The name property can be any name (it will be used in the defaultSections array)
• Any icon name is available and the icon defined will be used in the sidebar
• The label is used as the name of the section as it appears in the sidebar
• contentArea must be defined as true

Next, within the defaultSections array define the page type and the content area name, e.g.

Within the Twig view, the render sections function can be used to allow sections to be configured to appear above and below the contentArea.

e.g. for product.twig

The theme will automatically render sections configured to sit either above or below the contentArea.

On amending and saving the theme.json file, all previously configured sections on the theme are lost. It is therefore advisable to configure a generic developer section that will allow for some degree of customisability without having to define a new section in theme.json.

It is advisable to configure a range of settings within the section and at least one block. Developer sections are normally sections for all other purposes, and defined in exactly the same way.

Icon names that are available for use for sections and blocks are as follows, in the format 'icon_name' -> explanation -> suggested section use

Where an icon is not set or a name used that is not available, the default block icon will be used.

In addition, icons for setting groups can also be used for sections (and vice versa).

Icon names that are available for setting groups are as follows, in the format 'icon_name' -> explanation

Where an icon is not set or a name used that is not available, the default icon cog will be used.

Colour schemes are defined in theme.json

Where a theme uses colour schemes, individual colour settings are not available. If individual colour settings are defined in settings.json and colour schemes are defined in theme.json, individual colour settings will be ignored.

Each theme defines a single colour scheme template, e.g.

The template defines the names of each colour setting (referenced in SCSS/CSS), the label (displayed in the theme customiser) and the default value.

The setting named primary_background_color is used as the background colour where the colour scheme is displayed in the theme customiser.

Each colour scheme configured on the theme uses the same template, and therefore has the same settings and labels. If the user creates a new colour scheme through the theme customiser, it will use the template.

The theme can define predefined colour schemes which are created when the theme is installed, e.g.

Any colour settings not defined in a predefined scheme will still be created in the colour scheme when it is created, when the theme is installed, and use the default colour set in the template.

A theme can have a maximum of 40 colour schemes (which includes both predefined colour schemes and user-created colour schemes).

In the theme customiser, the following elements support colour schemes:

• Pages
• Header
• Footer
• Sections
• Landing pages

These are defined in the theme.

Within theme.json the elements that support colour schemes are declared as follows:

Values default to false unless otherwise defined. In the example above, website pages do not support colour schemes except for the home, contact and landing page pages. Sections also do not support colour schemes except for the hero_image_slider section.

Colour schemes are 'live'

• If names of colours within the template are modified, all colour schemes are recreated and reset
• If colours are removed or added within the template, all colour schemes are recreated and reset
• If an element is enabled for colour scheme selection, selection will be available immediately in the theme customiser

The lockedTitle property can be set to true to prevent the title of a colour scheme being modified in the theme customiser, e.g.

Each theme should utilise a root colour scheme defined as :root as a fallback option where a colour scheme for an element is not selected. This is achieved using the root property, e.g.

Each theme can have only one root colour scheme defined.

Defining a root colour scheme in theme.json enables an additional feature in the theme customiser allowing the user to select the root colour scheme. A root scheme is defined by the platform by default (the first predefined colour scheme is selected as the root) where one is not explicitly set.

For elements defined in settings, a default colour scheme can be defined ensuring that colour scheme is applied to the element on theme installation, e.g.

The user will be able to override a default colour scheme through the theme customiser.

Default colour schemes can be defined for any element.

When specifying individual settings (per item type), they fully override the "inherited" ones. For example, if a default is set for page, but not for pages.home and pages.home is still set (for example, with enabled) then pages.home won't inherit the default from page.

In theme views, a global.theme.color_schemes array returns the colour schemes defined on the theme

• color_scheme.root will return true for the root colour scheme
• color_scheme.name will return the name of the colour scheme
• color_scheme.id will return the unique ID of the colour scheme
• color_scheme.colors is an array of colour settings defined for the colour scheme
• color.name will return the name of the colour
• color.value will return the hexadecimal colour reference (including the leading #) of the colour

For example, use in master.twig:

In theme views, a global.theme.selected_color_schemes array returns details about the selected colour scheme for the element

• global.theme.selected_color_schemes.abc.name returns the name of the selected colour scheme
• global.theme.selected_color_schemes.abc.id returns the ID of the selected colour scheme

abc is replaced with the element returning the colour scheme, available elements are

• page to return the colour scheme selected for a page
• page_header to return the colour scheme selected for the page header
• page_footer to return the colour scheme selected for the page footer

For sections, use

• section.color_scheme.name returns the name of the selected colour scheme
• section.color_scheme.id returns the ID of the selected colour scheme

Within the theme customiser, a single colour scheme can be selected for the header/footer which is used throughout. For sections, a colour scheme is selected for each instance of the colour scheme.