Settings System

Define configurable options for themes and sections.

Schema Structure

Each section ends with a {% schema %} block:

{% schema %}
{
  "name": "Section Name",
  "category": "cta",
  "tag": "section",
  "settings": [...],
  "blocks": [],
  "presets": []
}
{% endschema %}

Setting Types

Display-Only Types

These types don't store values - they're for organizing and explaining settings.

header

Section divider with label text.

{
  "type": "header",
  "content": "Text Colors"
}

Renders as a styled header to group related settings visually.

---

info

Informational text box with helpful context.

{
  "type": "info",
  "content": "Used when sections have 'Light Text' enabled (for dark backgrounds)"
}

Renders as a blue info box to explain settings to theme editors.

---

Input Types

text

Simple text input or textarea.

{
  "type": "text",
  "id": "title",
  "label": "Title",
  "default": "Default text",
  "nb_rows": 1
}

Option	Description
nb_rows	1 = input, 2+ = textarea
html	true = rich text editor (Trix)
line_break	Allow line breaks

Live Preview - Use .attr accessor:

<h2 {{ section.settings.title.attr }}>{{ section.settings.title }}</h2>

---

color

Color picker (no transparency).

{
  "type": "color",
  "id": "bgcolor",
  "label": "Background Color",
  "default": "#1F2937"
}

Live Preview - Use CSS variables:

{% capture section_style %}--bgcolor: {{ section.settings.bgcolor }};{% endcapture %}
{% section_wrapper 'section' style: section_style data-css-vars: 'bgcolor' %}
  <div style="background-color: var(--bgcolor);">

---

color_alpha

Color picker with transparency.

{
  "type": "color_alpha",
  "id": "overlay_color",
  "label": "Overlay Color",
  "default": {"color": "#1F2937", "alpha": 80}
}

Value format: {"color": "#RRGGBB", "alpha": 0-100}

Liquid Filter:

{{ section.settings.overlay_color | color_alpha_to_rgba }}
<!-- Output: rgba(31, 41, 55, 0.80) -->

---

image

Image picker from asset library.

{
  "type": "image",
  "id": "background_image",
  "label": "Background Image",
  "default": "https://example.com/default.jpg"
}

Liquid Filter - Use image_url with size:

<img src="{{ section.settings.background_image | image_url: 'large' }}">

Sizes: thumb, small, medium, large, hero

---

link

Link with text, URL, and optional target.

{
  "type": "link",
  "id": "button",
  "label": "Button",
  "with_text": true,
  "default": {
    "text": "Click Here",
    "href": "/about",
    "target": ""
  }
}

Usage - Access properties directly:

<a href="{{ section.settings.button.href }}"
   target="{{ section.settings.button.target }}">
  {{ section.settings.button.text }}
</a>

Property	Description
.text	Link display text
.href	URL (also available as .url)
.target	"" or "_blank" for new tab

---

select

Dropdown selection.

{
  "type": "select",
  "id": "columns",
  "label": "Columns",
  "options": [
    {"value": "2", "label": "2 Columns"},
    {"value": "3", "label": "3 Columns"},
    {"value": "4", "label": "4 Columns"}
  ],
  "default": "3"
}

---

number

Numeric input with optional unit.

{
  "type": "number",
  "id": "count",
  "label": "Number of Items",
  "default": 6
}

With unit (for CSS variables):

{
  "type": "number",
  "id": "border_width",
  "label": "Border Width",
  "default": 2,
  "unit": "px"
}

---

range

Slider input with min/max bounds.

{
  "type": "range",
  "id": "spacing",
  "label": "Spacing",
  "min": 0,
  "max": 100,
  "step": 5,
  "unit": "px",
  "default": 20
}

Option	Description
min	Minimum value (required)
max	Maximum value (required)
step	Increment amount (default: 1)
unit	Unit for display AND CSS variable generation

Allowed units: px, %, em, rem, vh, vw, vmin, vmax, ch, ex

CSS Variable Generation

The unit property is appended to auto-generated CSS variables:

/* With "unit": "px" */
--section-spacing: 20px;

/* Without unit */
--section-opacity: 80;

If the setting controls CSS spacing/sizing, always include unit. Without it, padding: var(--section-spacing) fails because padding: 20 is invalid CSS.

---

icon

Icon picker with search (uses Remix Icons).

{
  "type": "icon",
  "id": "icon",
  "label": "Icon",
  "default": "ri-star-line"
}

Stores the icon class (e.g., ri-star-line). The picker supports search and allows custom class input.

Usage:

<i class="{{ section.settings.icon }}"></i>

---

checkbox

Boolean toggle.

{
  "type": "checkbox",
  "id": "show_date",
  "label": "Show Date",
  "default": true
}

Usage - Use natural boolean checks:

{% if section.settings.show_date %}
  <span>{{ post.date }}</span>
{% endif %}

tip

Boolean settings now return raw true/false values, so you can use natural boolean checks (if, unless, elsif). This change makes checkbox conditions more intuitive and readable.

---

post

Post picker with async search.

{
  "type": "post",
  "id": "featured_post",
  "label": "Featured Post",
  "placeholder": "Select a post..."
}

Stores post slug as value. Shows post title in the UI.

---

Conditional Display (show_if)

Show/hide settings based on other values:

{
  "type": "checkbox",
  "id": "use_custom_colors",
  "label": "Use Custom Colors",
  "default": false
},
{
  "type": "color",
  "id": "custom_bg",
  "label": "Background Color",
  "default": "#ffffff",
  "show_if": { "setting": "use_custom_colors", "eq": true }
}

The color picker only appears when the checkbox is checked.

---

Quick Reference

Type	Live Preview	Key Usage
header	N/A	Display-only, organizes settings
info	N/A	Display-only, explanatory text
text	.attr accessor	{{ setting.attr }}
color	CSS variable	data-css-vars attribute
color_alpha	CSS variable	color_alpha_to_rgba filter
image	CSS variable	image_url filter
link	N/A	.href, .text, .target
select	Server re-render	Direct value access
number	Server re-render	Direct value access
range	Server re-render	Direct value access, with min/max/step
icon	Server re-render	Stores icon class (e.g., ri-star-line)
checkbox	Server re-render	Natural boolean checks (if/unless)
post	Server re-render	Stores slug