Settings

Settings are the controls a merchant sees in the theme editor. A theme has its own settings (colours, fonts, the logo), and every section and block declares its own in its <schema>.

Theme settings

config/settings_schema.json is a list of panels:

config/settings_schema.json

[
  {
    "name": "Colours",
    "settings": [
      { "type": "color", "id": "color_ink", "label": "Text", "default": "#111111" },
      { "type": "color", "id": "color_bg", "label": "Background", "default": "#ffffff" }
    ]
  },
  {
    "name": "Layout",
    "settings": [
      { "type": "range", "id": "page_width", "label": "Page width", "min": 960, "max": 1600, "step": 20, "default": 1200 }
    ]
  }
]

Read them anywhere through settings:

<style>
  :root {
    --color-ink: {settings.color_ink};
    --color-bg: {settings.color_bg};
    --page-width: {settings.page_width}px;
  }
</style>

config/settings_data.json holds the values your theme starts with. When a merchant changes settings in the editor, the store saves them as a draft and makes them live when they publish.

A setting

Key	Means
type	The control (see below)
id	Its name in settings.<id>: lowercase letters, digits and _, starting with a letter, unique in its schema
label	What the merchant reads
default	The value before the merchant changes it
info	Help text under the control
placeholder	Placeholder for text inputs
options	The choices for select and radio: [{ "value": "…", "label": "…" }]
min, max, step	For number and range
css_var, css_unit	A CSS custom property (e.g. --gap) and its unit (e.g. px), so the editor previews the change instantly

Setting types

Type	Control	Value in the template
text, textarea	Text input, multi-line text	Text
richtext, html	Formatted text	HTML, limited to safe tags (paragraphs, headings, lists, links, bold, italic)
code	Code editor	Text
number, range	Number input, slider	Number
checkbox	On/off	true or false
select, radio	Dropdown, radio buttons	The chosen value
color	Colour picker	#rrggbb
url	Link	A URL
image	Image picker	An image
video	Video picker	A video (url, poster_url, mime_type)
product	Product picker	A product
collection	Collection picker	A collection
link_list	Menu picker	The menu’s handle: read the menu with linklists[settings.menu]
offer	Bundle offer editor	A list of offer tiers
city_list	Delivery cities	A list of cities
courier	Courier picker	The chosen courier’s key
header, paragraph	A heading or a paragraph in the editor panel; not a setting, so no id	—

Run sworen check to validate every schema with the same rules the store applies.