LiquidSchema & Settings

Schema & Settings

A {% schema %} block at the top of a section declares the settings a merchant can edit. The page editor builds its settings panel from it, fills in the defaults, and checks saved values against it. The block is removed before the template renders.

A schema, live

The settings panel on the right is generated from the schema, the way the page editor generates it for a merchant. Change a value, or edit the schema and watch the panel follow.

Feature strip
Playground
Loading editor…

Runs in your browser on sample data: the same engine and filters as the storefront. Widgets such as add to cart are simulated: clicking one shows what would happen on a store.

The parts of a schema

KeyWhat it is
nameWhat the section is called in the editor’s library and outline. Required.
settingsAn array of settings, in the order they appear in the panel.
blocksOptional. The kinds of repeatable items the section takes. See Blocks below.
max_blocksOptional. Most blocks in total, across all types.
presetsOptional. Starting content, mainly which blocks a new section is created with.

Each setting is an object with these keys:

KeyWhat it does
idUnique in the section. Read it as section.settings.<id>. Letters, numbers and underscores.
typeOne of the types below.
labelThe field’s name in the panel.
defaultThe value a new section starts with, and the value used whenever a saved section has none.
infoHelp text under the field. Use it for units and formats.
optionsselect only: [{ "value": "…", "label": "…" }].
min · max · stepnumber and range: the bounds the panel enforces.

Setting types

TypeStoresNotes
textOne line—
textareaSeveral lines, plain—
rich_textHTML from the editorOutput it directly. It is merchant content, not visitor input.
numberA numbermin, max and step are honoured.
rangeA number on a sliderGive it min, max and step.
checkboxtrue or false—
selectOne of options[{ value, label }]—
colorA hex, or a theme token as default"default": "@color.primary"
imageA media-library URLOpens the media picker.
urlA linkRelative paths are fine: /collections
menuA navigation menu handleRead it with linklists[section.settings.your_id].
productOne product (handle or id)Opens the product picker. Pair with product_source: "product" and read products | first.
blogBlog post slugs, comma-separatedOpens the post picker. Name it article_handles with article_source: "handles" and the posts arrive in articles, in that order.
listAn array of itemsA repeater. Declare "fields" (the settings of one item) and loop over it. Optional "max" and "item_label".
collectionOne collectionResolved to a collection drop: section.settings.your_id.products.
collection_listSeveral collectionsResolved to an array of collection drops (up to 24).
product_listSeveral productsResolved to an array of product drops (up to 24).
pageOne pageResolved to { title, handle, url }.

Grouping settings

{ "type": "header", "content": "Style" } starts a group: the settings after it appear under that heading in the panel. A header has no id and no value.

Defaults that follow the store's theme

A color default of @color.primary (or any @color.*, or @shape.radius) is the merchant's own theme colour, resolved when the section renders. The merchant still gets a picker and can override it. Every other default is literal. See Theme tokens for the full list.

Settings that fetch data

Some ids are reserved: product_source, collection_source, article_source and their companions make the storefront fetch products, collections or posts before the template runs. See Products, collections & posts. Reference types (collection, collection_list, product_list, page) also fetch: the setting stores a handle and the template reads a full object.

A reference settingliquid
{ "id": "featured", "type": "collection", "label": "Collection" }
{%- assign col = section.settings.featured -%}
{%- if col -%}
<h2>{{ col.title }}</h2>
{% for item in col.products limit: 4 %}{{ item.title }}{% endfor %}
{%- endif -%}

List settings

A list is a repeater: the merchant adds, removes and reorders items, each with the fields you declare. Use it for FAQs, testimonials, logos and slides, wherever the items are all the same shape.

List settingliquid
{% schema %}
{
"name": "FAQ",
"settings": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "Questions" },
{ "id": "items", "type": "list", "label": "Questions", "item_label": "Question", "max": 12,
"fields": [
{ "id": "q", "type": "text", "label": "Question" },
{ "id": "a", "type": "textarea", "label": "Answer" }
],
"default": [
{ "q": "Do you deliver outside the valley?", "a": "Yes, in 3–5 days." },
{ "q": "Can I return an item?", "a": "Within 7 days, unworn." }
]
}
]
}
{% endschema %}
<section style="max-width: 640px; margin: 0 auto; padding: 32px 20px; font-family: var(--font-body);">
<h2>{{ section.settings.heading }}</h2>
{%- for item in section.settings.items -%}
<details style="border-bottom: 1px solid var(--color-border); padding: 12px 0;">
<summary style="cursor: pointer; font-weight: 600;">{{ item.q }}</summary>
<p style="color: var(--color-text-muted);">{{ item.a }}</p>
</details>
{%- endfor -%}
</section>

fields can use any type except the reference types. max caps the number of items and item_label names one item in the editor (“Add question”).

Blocks

Blocks are like list items that can be different kinds. A section can take icons and notes, slides and videos, and the merchant mixes them in any order. Loop over section.blocks and branch on block.type.

Blocksliquid
{% schema %}
{
"name": "Icon row",
"settings": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "The details" }
],
"blocks": [
{ "type": "icon", "name": "Icon", "limit": 6, "settings": [
{ "id": "symbol", "type": "text", "label": "Symbol", "default": "✦" },
{ "id": "label", "type": "text", "label": "Label", "default": "Hand finished" }
] },
{ "type": "note", "name": "Note", "settings": [
{ "id": "text", "type": "textarea", "label": "Text", "default": "Made in Patan." }
] }
],
"max_blocks": 8,
"presets": [
{ "name": "Icon row", "blocks": [
{ "type": "icon" },
{ "type": "icon", "settings": { "symbol": "♺", "label": "Recycled card" } },
{ "type": "note" }
] }
]
}
{% endschema %}
<section style="padding: 32px 20px; font-family: var(--font-body); text-align: center;">
<h2>{{ section.settings.heading }}</h2>
<div style="display: flex; gap: 24px; justify-content: center; flex-wrap: wrap;">
{%- for block in section.blocks -%}
<div {{ block.joomni_attributes }}>
{%- case block.type -%}
{%- when 'icon' -%}
<div style="font-size: 28px; color: var(--color-primary);">{{ block.settings.symbol }}</div>
<div>{{ block.settings.label }}</div>
{%- when 'note' -%}
<p style="color: var(--color-text-muted); max-width: 18ch;">{{ block.settings.text }}</p>
{%- endcase -%}
</div>
{%- endfor -%}
</div>
</section>
block.Value
idUnique in the section.
typeThe block type from the schema.
indexPosition, from 1.
settingsIts settings, with defaults filled in and @color.* resolved.
joomni_attributesPut it on the block’s root element. It lets the editor select the block when the merchant clicks it. shopify_attributes is the same string.

list or blocks?

Use a list when every item has the same fields. Use blocks when items differ in kind, or when the merchant should be able to select each one on the canvas.

Pasting a Shopify section

Shopify setting types are accepted and mapped to Joomni's own, so a pasted schema needs no edits:

Shopify typeRendered as
richtextrich_text
inline_richtexttext
html · liquidtextarea
video_url · videourl
radio · text_alignmentselect
link_listmenu
color_background · font_picker · article · metaobjecttext

@app and @theme block types are ignored. A schema with an unknown type, a duplicate id or a malformed option is rejected when the section is saved, with the setting's position in the error.

Still stuck? Our team reads every message.

Need help?