Settings are how a merchant configures your section without touching code. Each one you declare in {% schema %} becomes a field in the theme editor, and its value is read back in Liquid through section.settings.<id> or block.settings.<id>. Choosing the right setting type is the difference between an editor that feels native and one that frustrates the people using it.

This is a complete reference to every input setting type Shopify supports, grouped by purpose, with the Liquid you write to use each value. To assemble these into a full schema visually, use the Schema Builder; for the broader schema rules, see the Section Schema reference.

How settings work

Every setting needs three things at minimum — a type, an id, and a label:

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

You then read the value in your Liquid:

<h2>{{ section.settings.heading }}</h2>

Settings come in two broad families: input settings that store a merchant-entered value, and sidebar settings (header, paragraph) that only add labels and instructions to the editor and store nothing.

Basic input settings

These are the everyday building blocks. They map almost one-to-one to standard form controls.

Type	What it stores	Use it for
text	Single-line string	Short headings, labels
textarea	Multi-line string	Short paragraphs, plain text
richtext	HTML (block-level)	Editorial copy with bold, links, lists
inline_richtext	HTML (inline only)	Headings that need bold/italic, no <p> wrapper
number	Integer or nil	Counts, optional numeric values
range	Number from a slider	Bounded values like padding or columns
checkbox	true / false	Toggles ("Show on mobile")
radio	One value from options	A small set of exclusive choices
select	One value from options	Layout/style pickers with many options

A range must define min, max, step, and a default within range — miss any and the section won't save:

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

Read it like any other value:

<div class="grid grid-{{ section.settings.columns }}">

A common mistake is reaching for text when you mean richtext. Use richtext whenever a merchant should be able to add links or formatting — it stores proper HTML, while text escapes everything.

Sidebar settings (labels, not values)

These don't have an id because they store nothing — they organize the editor:

{ "type": "header", "content": "Layout" },
{ "type": "paragraph", "content": "These options control spacing." }

Use header to group related settings and paragraph to explain a non-obvious option. A well-organized settings panel is a real quality signal.

Specialized resource settings

These let merchants pick existing store resources. Each returns a full Liquid object you can read properties from — far more powerful than asking a merchant to paste an ID or URL.

Type	Returns	Example use
product	A product object	Featured product
product_list	Array of products	Curated product row
collection	A collection object	Featured collection
collection_list	Array of collections	Collection grid
blog	A blog object	Blog to pull posts from
article	An article object	Featured post
page	A page object	Embed page content
link_list	A linklist (menu)	Custom navigation
url	A URL string	Button links
image_picker	An image object	Section imagery
video	A Shopify-hosted video	Self-hosted video
video_url	A YouTube/Vimeo URL	Embedded video
font_picker	A font object	Heading/body font
html	Raw HTML string	Custom embeds
liquid	Liquid string (limited)	Advanced custom output

Because these return objects, you access their properties directly. A product setting:

{% assign product = section.settings.featured_product %}
{% if product != blank %}
  <a href="{{ product.url }}">
    {{ product.featured_image | image_url: width: 400 | image_tag }}
    <h3>{{ product.title }}</h3>
    <span>{{ product.price | money }}</span>
  </a>
{% endif %}

Two important rules from the Shopify docs worth committing to memory:

• Always guard resource settings with != blank. A merchant may not have made a selection, and the resource may have been deleted.
• Resource settings don't switch with presets and several (like article) don't support a default. Don't rely on a default selection being present.

For an image_picker, pair it with the image_url and image_tag filters to get responsive output rather than a raw <img> — covered in depth in the Liquid Objects guide.

The color family

Color settings have grown into a small family, and picking the right one matters for theme-wide consistency.

Type	Stores	Use it for
color	A single color	One-off color overrides
color_background	A CSS gradient/background	Section backgrounds, gradients
color_scheme	A reference to a scheme	The modern, recommended approach
color_palette	A palette (legacy)	Older theme color systems

The modern best practice is color_scheme. Instead of exposing a dozen individual color pickers per section, themes define reusable color schemes globally (background, text, button, etc.), and each section simply chooses which scheme to apply:

{
  "type": "color_scheme",
  "id": "color_scheme",
  "label": "Color scheme",
  "default": "scheme-1"
}

<div class="section color-{{ section.settings.color_scheme }}">

This keeps a store visually consistent and gives merchants far less opportunity to create clashing color combinations. Reach for a standalone color setting only for genuine one-off accents.

Note: the older hex_to_rgba filter for manipulating these values is deprecated — use color_modify and color_to_rgb instead. More on that in common mistakes.

Metaobject settings

Two newer types connect sections to structured custom content:

Type	Returns
metaobject	A single metaobject entry
metaobject_list	A list of metaobject entries

These are powerful for CMS-style content — author profiles, size charts, FAQ entries — defined once as metaobjects and reused across sections:

{
  "type": "metaobject",
  "id": "author",
  "label": "Author",
  "metaobject_type": "author"
}

{% assign author = section.settings.author %}
{{ author.system.handle }}
{{ author.name.value }}

If metaobjects are new to you, start with the Metafields in Liquid guide and Shopify's metaobject documentation.

Text alignment and other UI helpers

text_alignment gives merchants a familiar left/center/right control that returns a CSS-ready value:

{ "type": "text_alignment", "id": "alignment", "label": "Alignment", "default": "center" }

<div style="text-align: {{ section.settings.alignment }}">

Conditionally showing settings with visible_if

Most setting types support visible_if, which hides a setting until a condition is met. This is the cleanest way to avoid a cluttered editor — show advanced options only when they're relevant:

{
  "type": "select",
  "id": "layout",
  "label": "Layout",
  "options": [
    { "value": "grid", "label": "Grid" },
    { "value": "slider", "label": "Slider" }
  ],
  "default": "grid"
},
{
  "type": "range",
  "id": "slides_to_show",
  "label": "Slides to show",
  "min": 1, "max": 4, "step": 1, "default": 2,
  "visible_if": "{{ section.settings.layout == 'slider' }}"
}

The slides_to_show slider only appears once the merchant chooses the slider layout — progressive disclosure that keeps the panel tidy.

Quick decision guide

• Short string → text. Needs formatting/links → richtext (or inline_richtext for headings).
• A bounded number → range. An open number → number.
• A few choices → radio. Many choices → select. On/off → checkbox.
• A store resource → the matching picker (product, collection, image_picker, …) — never ask for an ID.
• Color → color_scheme for consistency; color only for one-offs.
• Structured reusable content → metaobject / metaobject_list.
• Keep the editor clean → group with header, explain with paragraph, hide with visible_if.

Next steps

You don't have to memorize all of this — the Schema Builder lets you add any of these setting types visually and generates valid JSON you can paste straight into a section. From there, the HTML to Liquid converter can turn a block of HTML into a section with settings already wired up, and the Liquid Cheatsheet shows the exact syntax for reading each value.