Section schema

Every field of a section's schema, every setting type, and the rules each must follow.

The {% schema %} block holds one JSON object. It describes the section to the theme editor and to the platform, and prints nothing.

Fields#

Field	Required	Meaning
`name`	Yes	The section's name, unique in the theme.
`kind`	No	`section` (default), `layout`, `embed` or `block`. See Sections.
`target`	No	The global surface a `layout` or `embed` section renders in.
`icon`	No	The icon shown for the section in the editor.
`ctx_needs`	No	The store data the section reads. See CTX.
`settings`	No	The section's settings.
`blocks`	No	The blocks the section accepts.
`presets`	No	Ready-made versions of the section offered when a merchant adds one.

Settings#

json

{ "id": "heading", "type": "text", "default": "Welcome",
  "editor": { "label": "Heading", "group": "content" } }

Key	Meaning
`id`	Unique in the section. The template reads `settings.<id>`.
`type`	One of the setting types below.
`default`	The value a new section starts with.
`editor`	`label` and optional `group`. A setting without `editor` is not shown to merchants.
`options`	For `select`: a list of `{ "value", "label" }`.
`fields`	For `object`: a list of `{ "key", "type", "label" }`.
`min`, `max`, `step`, `unit`	For `range`: `min` and `max` are required, `step` and `unit` optional.
`visible_if`	Show the setting only when another setting has one of the given values: `{ "setting": "layout", "values": ["grid"] }`.

label, group, option labels and a preset's name and category can be literal text or keys from the theme's editor translations, locales/<locale>.schema.json: fieldLabel.<label> for setting, option and field labels, fieldGroup.<group> for groups and preset categories, and sectionName.<name> for presets. A theme that ships editor translations must define every key it uses in each of those files, so the editor never shows a raw key. See Theme Locale Files.

Setting types#

Type	Editor control	The template reads
`text`	Single-line text	Text
`textarea`	Multi-line text	Text
`richtext`	Rich text editor	Formatted HTML, cleaned of anything unsafe
`number`	Number	Number
`range`	Slider	Number
`checkbox`	Toggle	`true` or `false`
`select`	Drop-down	The chosen option's `value`
`color`	Colour picker	Hex colour
`color_scheme`	One of the theme's colour schemes	The scheme's id
`image`	Image from the media library	Image URL; use `image_url`
`video`	Video from the media library	Video URL
`url`	Link	URL
`object`	A group of the declared `fields`	Object of field values
`vascula`	Code editor	The rendered output of the merchant's Vascula code
`menu`	Menu picker	See Bound settings
`product`, `collection`, `category`, `vendor`, `brand`, `page`, `blog_post`, `blog_category`, `policy`	Search and pick one	The picked item, or nothing if it was deleted
`product_list`, `collection_list`	Pick and order several	A list of the picked items

Blocks#

json

"blocks": {
  "max": 8,
  "default": ["slide", "slide"],
  "types": [
    { "type": "slide",
      "editor": { "label": "Slide" },
      "settings": [
        { "id": "caption", "type": "text", "editor": { "label": "Caption" } }
      ] }
  ]
}

Field	Meaning
`types`	The block types this section defines. Each has a `type`, an `editor` label and its own `settings`.
`default`	The blocks a newly added section starts with.
`max`	The most blocks a merchant can add. Omit for no limit.
`accept_theme_blocks`	Accept the theme's shared theme blocks.
`accept_app_blocks`	Accept blocks from installed apps.

Presets#

A preset is a ready-made version of the section in the editor's "Add section" list.

json

"presets": [
  { "name": "Two testimonials", "category": "Social proof",
    "settings": { "heading": "Loved by customers" },
    "blocks": [ { "type": "quote" }, { "type": "quote" } ] }
]

Preset settings must be declared settings, and preset blocks must be declared block types, or theme blocks (theme:<name>) when the section accepts them.

Rules#

name is required. Setting ids are unique in the section and in each block type.
An editable setting uses a supported type. select needs options, object needs fields with unique keys, range needs min below max.
visible_if names another setting and at least one value.
Every block type has at least one editable setting, and every type in default is declared.
A block file (kind: block) has no target and no presets, and its blocks may only accept theme blocks.
Saved settings may contain only declared settings. A section with blocks always stores a blocks list, which may be empty.