Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 61 ยท Layouts, Templates and Sections

Schema Settings and Setting Types in Depth

Learn every common Shopify schema setting type, from text and richtext to image pickers, ranges, font pickers and visible_if, with safe Liquid patterns.

Every control a merchant sees in the theme editor comes from a setting that you declare in JSON. A heading field, a color swatch, a slider for padding, a product picker: each one is one small object in a {% schema %} block (or in config/settings_schema.json for global settings, covered in the next lesson). Pick the right setting type and the merchant gets a friendly control. Pick the wrong one and you either frustrate them or hand your Liquid a value it was never ready for.

In Building a Section you used a few settings. This lesson goes through the types you will use most, the attributes they share, what each one gives you in Liquid, and the traps hiding in empty values. You will also see how visible_if, info, headers and translation keys keep a large schema usable.

Schema, sections and the theme editor run on Shopify, not on this website. Schema code below is read-only and was written for current Online Store 2.0 themes. The two live examples are stand-ins written in JavaScript: one builds a text version of the editor form from a schema, the other checks a schema for mistakes. Shopify's real validation is stricter and more complete, so always run shopify theme check on real themes.

Anatomy of a setting

Every setting is an object with a type and, for input types, an id and a label:

JSON
{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Fresh arrivals",
  "info": "Shown above the product grid."
}
  • type chooses the editor control and the kind of value you receive.
  • id is the key. It must be unique inside its section (or block), and it is how you read the value: {{ section.settings.heading }}. Use snake_case.
  • label is what the merchant reads. Write it for a non-developer.
  • default is the starting value. Some types require it, some forbid it, and some allow only certain values.
  • info is optional help text under the control. Use it for the one fact the label cannot carry, such as a recommended image size.

Inside a section, values arrive as section.settings.<id>. Inside a block, they arrive as block.settings.<id>. Global theme settings use settings.<id>.

flowchart LR
  S["Schema JSON<br/>type, id, label, default"] --> E["Theme editor<br/>control for the merchant"]
  E --> D["Saved value<br/>in the template JSON"]
  D --> L["Liquid<br/>section.settings.id"]

The schema declares the control, the merchant fills it in, and Liquid reads the saved value.

Text and content types

Type The merchant sees Liquid receives
text single-line input a string
textarea multi-line input a string (line breaks kept)
richtext small formatting editor HTML string in paragraph or list tags
inline_richtext formatting for one line HTML string without paragraph tags
number numeric input a number, or nil when empty
url link field with a picker a string, or blank

text and textarea values are plain strings that Liquid does not escape for you. Print them with the escape filter when they go inside an HTML attribute, and read Security in Themes before using them in scripts.

richtext gives merchants bold, italic, links and lists. Its default, when you provide one, must be wrapped in a block tag such as <p>...</p> or a list. The value is HTML that Shopify has already limited to basic formatting tags, so you can print it directly: {{ section.settings.text }}. Use inline_richtext for a headline where you only want emphasis and links, so the value can sit inside an <h2> without invalid nested paragraphs.

number is easy to misuse. An empty field gives you nil, which is not zero. Test with {% if section.settings.limit != blank %}.

url accepts a link the merchant picks (a page, product, collection) or types. Its allowed default values are restricted, so most themes leave it blank and handle that case.

Choice and numeric types

JSON
[
  {
    "type": "select",
    "id": "layout",
    "label": "Layout",
    "options": [
      { "value": "stacked", "label": "Stacked" },
      { "value": "overlay", "label": "Text over image" }
    ],
    "default": "stacked"
  },
  {
    "type": "range",
    "id": "height",
    "label": "Banner height",
    "min": 300,
    "max": 800,
    "step": 50,
    "unit": "px",
    "default": 500
  },
  {
    "type": "checkbox",
    "id": "full_width",
    "label": "Use full width",
    "default": false
  }
]
  • select and radio return the chosen option's value string. Compare against your value strings, never the labels. radio shows all options at once and suits short lists; select suits longer ones.
  • checkbox returns true or false. It is the right choice for on/off, and the wrong one for three-way choices.
  • range is a slider. It needs min, max, step and default, and the default must fall inside the range. The number of steps between min and max is capped (roughly a hundred), so a slider from 0 to 1000 in steps of 1 is not allowed. The optional unit is only a label; your Liquid must still add px or % itself.

The classic habit is to turn a range into inline CSS: style="min-height: {{ section.settings.height }}px". That is fine for one value, but when many settings drive CSS you will prefer CSS variables, which CSS for Themes explains.

Resource and media types

These types let a merchant point at things in their store or upload files.

Type Liquid receives Empty value
image_picker an image object nil
video a Shopify-hosted video object nil
product a product object nil
collection a collection object nil
product_list, collection_list an array of objects empty array
page, blog, article the matching object nil
link_list a menu object (linklist) nil
color a color object blank
font_picker a font object uses the required default

The golden rule: always check for the empty case. A new section starts with nothing selected, and merchants delete products and files. Compare:

LIQUID
{%- if section.settings.image != blank -%}
  {{ section.settings.image | image_url: width: 1600 | image_tag: loading: 'lazy', widths: '800, 1200, 1600' }}
{%- else -%}
  {{ 'hero-apparel-1' | placeholder_svg_tag: 'placeholder' }}
{%- endif -%}

Here the placeholder branch gives the editor a visible preview before any image is chosen. Image tags and srcset are explained in Product Media.

Resource pickers return the object itself, so you can use all of its properties:

LIQUID
{%- assign featured = section.settings.product -%}
{%- if featured != blank -%}
  <a href="{{ featured.url }}">{{ featured.title }}</a>
  <span>{{ featured.price | money }}</span>
{%- endif -%}

product_list and collection_list take an optional limit attribute for the maximum number of picks. A picked product that was deleted or is no longer visible is left out, so the array can be shorter than the number the merchant chose.

color values are objects with channel properties such as red, green, blue and alpha. A color setting with no default can be blank, so provide a default whenever possible.

font_picker requires a default that names a font in Shopify's library, for example "assistant_n4" (family plus weight and style code). In Liquid it returns a font object with family, weight and style, and filters such as font_face turn it into @font-face CSS. The global typography settings in the next lesson build on this.

Layout helpers: header, paragraph and visible_if

Not every entry is an input. Two types just organize the form:

JSON
{ "type": "header", "content": "Overlay options" },
{ "type": "paragraph", "content": "These options apply when the layout is Text over image." }

header renders a bold divider; paragraph renders explanatory text. Neither has an id and neither produces a value.

When a control only matters for one choice, hide it with visible_if:

JSON
{
  "type": "color",
  "id": "overlay_color",
  "label": "Overlay color",
  "default": "#000000",
  "visible_if": "{{ section.settings.layout == 'overlay' }}"
}

The condition is a Liquid expression in a string that can read other settings of the same section (or block), and global settings with settings.. It supports comparisons and and/or. Two cautions: visible_if only hides the control. The saved value still exists, so your Liquid must not assume a hidden setting is "off". And it works in the editor only, so a shopper never sees any difference.

Translating schema text

Hard-coded English labels are fine for your own store, but themes sold to others should use translation keys:

JSON
{
  "type": "text",
  "id": "heading",
  "label": "t:sections.hero.settings.heading.label",
  "default": "Fresh arrivals"
}

The t: prefix tells the editor to look the key up in a schema locale file such as locales/en.default.schema.json. These keys are for the editor UI; shopper-facing text uses the t filter and ordinary locale files. Both are covered in Translations, Markets and Localization.

Stand-in: building the editor form from a schema

The real editor is not available here, so this first stand-in reads a small schema and prints a text version of the form for two different layout choices. It implements a deliberately small subset of visible_if (one comparison) so you can see how hidden controls drop out.

JS Stand-in: render a settings form from a schema

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In the second form the overlay color appears, because the condition became true. What is real here: the schema shape and the setting types. What is imitation: the drawing of the controls and the tiny condition parser.

Stand-in: catching schema mistakes

Schema errors are a common source of "my section will not save" frustration. Shopify rejects many of them when you upload, and theme check flags more. This stand-in applies a few of those rules to a deliberately broken schema so you can learn what to look for.

JS Stand-in: a tiny schema linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Treat this as a study aid. The real checker knows many more rules, and some limits (like the exact step cap) can change, so trust Shopify's error messages and current documentation over this list.

Habits that keep schemas healthy

  • Group with headers. More than six or seven settings in a row is a wall. Use header entries to cluster them.
  • Prefer a few good controls. Every setting is something the merchant must understand and you must test. Offer a select with three tidy options before ten sliders.
  • Name IDs by meaning, not by position. overlay_opacity, not setting_3. IDs are part of your theme's data, and renaming one later orphans the values merchants already saved.
  • Always handle empty values, as shown above. Test a freshly added section with nothing filled in.
  • Give sensible defaults so a new section looks finished in the editor.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A select setting has options with values stacked and overlay. What does section.settings.layout return?

    Select and radio settings return the chosen option's value, so compare against value strings such as 'overlay', never against labels.
  2. 2. Which is the safest way to use an image_picker setting?

    An image_picker has no default and starts empty, and files can be removed later. Your Liquid must handle the blank case.
  3. 3. What does visible_if do?

    It is an editor-only convenience. The value is still stored, so your Liquid should not assume a hidden setting is switched off.
  4. 4. Why use label values like t:sections.hero.settings.heading.label?

    The t: prefix points to a key in a schema locale file such as en.default.schema.json, which makes the editor UI translatable.

Summary

  • A setting is a JSON object with type, id, label and usually default; Liquid reads it as section.settings.id.
  • Choose the type by the value you want: strings for text, option values for select, booleans for checkbox, objects for pickers.
  • Pickers and numbers can be empty, so always test with != blank and give the editor a placeholder.
  • header, paragraph, info and visible_if keep big schemas readable; t: keys make them translatable.
  • Never rename an id casually: saved merchant values are tied to it.

Next, move up a level to the settings that apply to the whole theme in Global Theme Settings: settings_schema.json and settings_data.json.