Section schema

Each section has a schema.json next to its design file. It declares the settings shown in Visual, the blocks a seller can add, and the presets offered in Add section.

src/sections/announcement/schema.json

{
  "name": "Announcement",
  "category": "text",
  "description": "A short line above the header.",
  "settings": [
    { "type": "text", "id": "text", "label": "Text", "default": "Instant delivery on every order" },
    { "type": "url", "id": "link", "label": "Link" },
    { "type": "checkbox", "id": "dismissible", "label": "Can be closed", "default": false }
  ],
  "limit": 1,
  "templates": ["index", "page"],
  "presets": [{ "name": "Announcement" }]
}

Section fields

string

required

Name shown in the editor.

string

Group in Add section: header, footer, hero, products, text, media, social, layout or main.

string

A short description of the section.

Setting[]

required

The section’s settings, in panel order. See Setting types.

Block[]

Block types the section accepts. See Blocks and nesting.

number

Most blocks of any type in one section.

boolean

default:"false"

Lets a block sit one level under another block, for example menu dropdowns.

number

Most instances of this section in one template.

string[]

Templates the section can be added to. page means every custom page. Omit it to allow every template.

object

Defaults for the shared style settings: width, padding_top, padding_bottom, background, background_image, overlay, text_color, radius, animation.

Preset[]

Starting points offered in Add section. A section without presets cannot be added from the editor. Use this for main sections such as the product page body.

Presets

A preset sets the name shown in Add section and, optionally, starting settings, style and blocks.

"presets": [
  {
    "name": "Hero with two buttons",
    "settings": { "heading": "Instant delivery" },
    "style": { "padding_top": 120 },
    "blocks": [
      { "type": "button", "settings": { "label": "Shop now", "url": "/products" } },
      { "type": "button", "settings": { "label": "Reviews", "url": "/reviews" } }
    ]
  }
]

Every block type in a preset must be declared in blocks.

Setting types

All value settings share these fields:

string

required

The setting type below.

string

required

Key in settings. Lowercase letters, digits and _, starting with a letter. Unique in the section.

string

required

Label in the settings panel.

string

Help text under the control.

string | number | boolean

Value used when nothing is stored.

Text

Type	Control	Value	Extra fields
`text`	One-line input	string	`placeholder`
`textarea`	Multi-line input	string	`placeholder`
`richtext`	Formatted text editor	HTML string	`placeholder`
`html`	HTML code field	HTML string	`placeholder`
`css`	CSS code field	string	`placeholder`
`url`	Link picker	string	`placeholder`

{ "type": "text", "id": "heading", "label": "Heading", "default": "Welcome", "placeholder": "Your headline" }

In Liquid, output richtext and html values with | raw. Everything else is escaped.

Media and style

Type	Control	Value
`image`	Image picker	Image URL, empty for none
`video`	Video picker	Video URL, empty for none
`color`	Color picker	Hex color, empty for theme default
`font`	Font picker	Font id, for example `space-grotesk`
`icon`	Icon picker from the shared set	Icon name, empty for no icon

{ "type": "color", "id": "accent", "label": "Accent", "default": "#3ddcf2" }

Numbers and choices

Type	Control	Value	Extra fields
`range`	Slider	number	`min`, `max` (required), `step`, `unit`; `default` is required and must be between `min` and `max`
`checkbox`	Switch	boolean
`select`	Dropdown	string	`options` (required); `default` must be one of them
`radio`	Button group	string	`options` (required); `default` must be one of them

{ "type": "range", "id": "columns", "label": "Columns", "min": 1, "max": 4, "step": 1, "default": 3 }

{
  "type": "select",
  "id": "align",
  "label": "Alignment",
  "options": [
    { "value": "start", "label": "Start" },
    { "value": "center", "label": "Center" }
  ],
  "default": "center"
}

Store data pickers

Type	Picks	Value
`category`	A store category	Category id, empty for all
`group`	A product group	Group id, empty for all
`product`	A product	Product id, empty for none

{ "type": "product", "id": "product", "label": "Product" }

Layout rows

header and paragraph add a heading or a line of text to the settings panel. They hold no value and have no id.

{ "type": "header", "content": "Buttons" }

{ "type": "paragraph", "content": "Leave a link empty to hide its button." }

Values in templates

Template files store setting values by id. A missing value uses the schema default. A key that is not a setting, or a value of the wrong kind, is a warning: the storefront ignores it and uses the default. Publish offers Remove unused values to clean these up. See Publish and updates.

Start here

Build a theme

Builder

Storefront features

Help

Old Nunjucks themes

Section fields

Presets

Setting types

Text

Media and style

Numbers and choices

Store data pickers

Layout rows

Values in templates

​Section fields

​Presets

​Setting types

​Text

​Media and style

​Numbers and choices

​Store data pickers

​Layout rows

​Values in templates

Section fields

Presets

Setting types

Text

Media and style

Numbers and choices

Store data pickers

Layout rows

Values in templates