Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 61 ยท Layouts, Templates and Sections

Global Theme Settings: settings_schema.json and settings_data.json

Learn how settings_schema.json defines global theme settings, how settings_data.json stores values, and how color schemes and fonts become CSS variables.

Section settings control one section. Theme settings control the whole store: the brand colors, the fonts, the corner radius of every button, the social links, the cart style. A merchant opens the Theme settings panel in the theme editor, changes a color once, and every page follows. Two files in the config folder make that possible: settings_schema.json describes the controls, and settings_data.json stores the values the merchant picked.

Understanding these two files, and how to turn their values into CSS, is what separates a theme that is easy to restyle from one that needs a developer for every color change. You already know the individual setting types from Schema Settings and Setting Types in Depth; here you use them at the global level.

Real theme settings live inside Shopify's theme editor and servers, so the JSON and Liquid below are read-only and target current Online Store 2.0 themes. The live example is a JavaScript stand-in that turns a settings object into CSS variables the way your Liquid would. Dawn and other reference themes are good places to compare against real, current code.

Two files, two jobs

File Written by Contains
config/settings_schema.json you, the developer the list of groups and controls (the question)
config/settings_data.json the theme editor the saved values (the answer)

You edit the schema. The editor edits the data. When a merchant presses Save, Shopify rewrites settings_data.json, so that file is merchant territory: if you overwrite it with your own copy, you erase their customizations. Version Control and Team Workflows shows how to avoid that.

flowchart LR
  A["settings_schema.json<br/>controls you define"] --> B["Theme editor<br/>Theme settings panel"]
  B --> C["settings_data.json<br/>saved values"]
  C --> D["Liquid<br/>settings.id"]
  D --> E["HTML and CSS<br/>every page"]

The schema defines the panel, the editor saves answers, and Liquid reads them on every page.

The structure of settings_schema.json

The file is a JSON array of groups. The first group holds the theme's own information. Every other group becomes a collapsible section in the Theme settings panel.

JSON
[
  {
    "name": "theme_info",
    "theme_name": "Pebble",
    "theme_version": "1.0.0",
    "theme_author": "Example Studio",
    "theme_documentation_url": "https://example.com/pebble/docs",
    "theme_support_url": "https://example.com/pebble/support"
  },
  {
    "name": "Colors",
    "settings": [
      { "type": "header", "content": "Brand" },
      { "type": "color", "id": "accent", "label": "Accent color", "default": "#2B6CB0" },
      { "type": "range", "id": "button_radius", "label": "Button corner radius", "min": 0, "max": 40, "step": 2, "unit": "px", "default": 6 }
    ]
  },
  {
    "name": "Typography",
    "settings": [
      { "type": "font_picker", "id": "type_body_font", "label": "Body font", "default": "assistant_n4" },
      { "type": "font_picker", "id": "type_header_font", "label": "Heading font", "default": "assistant_n7" },
      { "type": "range", "id": "body_scale", "label": "Body text scale", "min": 90, "max": 130, "step": 5, "unit": "%", "default": 100 }
    ]
  }
]

Each setting uses the same attributes you learned for sections (type, id, label, default, info, visible_if). The difference is where the value shows up in Liquid: settings.accent, available in every template, section and snippet, with no need to pass it around.

Keep group names short and in the order a merchant thinks: Colors, Typography, Layout, Buttons, Cart, Social media. Use t: translation keys for names and labels in themes you plan to distribute.

Reading settings in Liquid

LIQUID
{%- if settings.show_social_links -%}
  <a href="{{ settings.social_instagram_link }}">Instagram</a>
{%- endif -%}

<style>
  body { font-size: {{ settings.body_scale | divided_by: 100.0 }}rem; }
</style>

Two habits matter. First, check blank values before printing a link or image. Second, avoid sprinkling settings.* all over your templates. Read them in one place (usually the <head> of layout/theme.liquid), convert them to CSS variables, and let your stylesheet do the rest.

Settings to CSS variables

CSS variables are the bridge between merchant choices and your stylesheet. The theme prints them once inside a {% style %} tag, which outputs a <style> element and lets the editor update colors live without a full reload:

LIQUID
{% style %}
  :root {
    --color-accent: {{ settings.accent }};
    --button-radius: {{ settings.button_radius }}px;
    --font-body-family: {{ settings.type_body_font.family }}, {{ settings.type_body_font.fallback_families }};
    --font-body-weight: {{ settings.type_body_font.weight }};
    --body-scale: {{ settings.body_scale | divided_by: 100.0 }};
  }
{% endstyle %}

Your CSS then uses var(--color-accent) everywhere. A merchant changes one control, one variable changes, and the whole store updates. Details of building a CSS system on top are in CSS for Themes.

Loading the chosen fonts

A font picker returns a font object. You need two things: the @font-face rules and the family name in CSS.

LIQUID
{{ settings.type_body_font | font_face: font_display: 'swap' }}
{{ settings.type_header_font | font_face: font_display: 'swap' }}

font_face prints an @font-face rule that points at Shopify's font CDN. Using font_display: 'swap' shows fallback text immediately instead of invisible text, which helps loading performance (see Theme Performance and Core Web Vitals). Only load the fonts you actually use, because every extra font is another request.

Color schemes

A single accent color is fine for a small theme, but real stores want several looks on one page: a light section, a dark section, a brand-colored banner. Modern themes solve this with a color scheme group, a set of named schemes the merchant edits globally and then picks per section.

You declare the group once in settings_schema.json:

JSON
{
  "name": "Color schemes",
  "settings": [
    {
      "type": "color_scheme_group",
      "id": "color_schemes",
      "definition": [
        { "type": "color", "id": "background", "label": "Background", "default": "#FFFFFF" },
        { "type": "color", "id": "text", "label": "Text", "default": "#121212" },
        { "type": "color", "id": "button", "label": "Button", "default": "#121212" },
        { "type": "color", "id": "button_label", "label": "Button label", "default": "#FFFFFF" }
      ],
      "role": {
        "background": "background",
        "text": "text",
        "primary_button": "button",
        "on_primary_button": "button_label"
      }
    }
  ]
}

Each entry in definition becomes one color the merchant sets for each scheme, and role tells the theme editor which colors play which role (used, for example, when it previews or recommends schemes). Sections then offer a simple picker:

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

In Liquid, settings.color_schemes is a collection of schemes. Each has an id and settings, so you can print one CSS class per scheme:

LIQUID
{% style %}
  {%- for scheme in settings.color_schemes -%}
    .color-{{ scheme.id }} {
      --color-background: {{ scheme.settings.background.red }}, {{ scheme.settings.background.green }}, {{ scheme.settings.background.blue }};
      --color-text: {{ scheme.settings.text.red }}, {{ scheme.settings.text.green }}, {{ scheme.settings.text.blue }};
    }
  {%- endfor -%}
{% endstyle %}

and a section applies its pick with a class:

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

Writing the channels as separate numbers lets your CSS build colors with rgb(var(--color-background)) or add transparency with rgb(var(--color-text) / 0.6). One class per scheme, one picker per section: that is the whole system.

Presets and style variants

settings_data.json holds the live values in a current object. Themes that ship style variants (a "Light" look, a "Bold" look) can also include named sets of values the merchant can switch between, which is how Theme Store themes present their built-in styles. Your own settings schema does not change for this: variants are different value sets for the same controls. Shipping a clean settings_data.json with good defaults matters, because a brand-new store starts from it. Section-level presets, which control how a section is added in the editor, are a separate feature (see Building a Section).

A trimmed example of the data file:

JSON
{
  "current": {
    "accent": "#2B6CB0",
    "button_radius": 6,
    "type_body_font": "assistant_n4",
    "type_header_font": "assistant_n7",
    "body_scale": 100,
    "color_schemes": {
      "scheme-1": {
        "settings": { "background": "#FFFFFF", "text": "#121212", "button": "#121212", "button_label": "#FFFFFF" }
      },
      "scheme-2": {
        "settings": { "background": "#121212", "text": "#F5F5F5", "button": "#F5F5F5", "button_label": "#121212" }
      }
    }
  }
}

You almost never write this by hand. The editor does. But reading it helps you debug: if a setting "does nothing", check that its id exists in the data and matches the schema exactly.

Stand-in: from saved settings to CSS variables

Here the "theme editor" is a plain JavaScript object, and a function does what your {% style %} block does: loop over schemes and print variables. The stand-in uses the same channel-splitting idea as the Liquid above, so you can see the finished CSS.

JS Stand-in: generate CSS variables from theme settings

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

No output.

Notice what is real and what is not. The CSS output has the same shape as a real theme's. The saved settings object, the hex-to-channel conversion and the function itself are stand-ins: in a real store Shopify supplies settings and color objects, and Liquid does the printing.

Stand-in: a merchant edit changes everything

The next stand-in imitates what happens when a merchant changes one control. It builds a tiny "page" from the variables, then prints two versions so you can see how many places one change reaches. It is only an illustration of why variables beat hard-coded values.

JS Stand-in: one setting, many places

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

No output.

Practical guidance

  • Name by purpose. accent, button_radius, type_header_font survive redesigns better than blue or big.
  • Give every setting a default. A new store starts from your defaults, so they are the first impression.
  • Do not duplicate section settings globally. A global setting says "everywhere"; a section setting says "here". Offer both only when a merchant could reasonably want a global default with a local override.
  • Treat settings_data.json as data. Do not rewrite it casually in a team repository.
  • Mind performance. Each font and each large inline CSS block costs bytes on every page. Print only what the page needs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file stores the values a merchant picks in the Theme settings panel?

    settings_schema.json only defines the controls. The values are written to settings_data.json when the merchant saves.
  2. 2. How do you read a global theme setting with the id accent in Liquid?

    Global theme settings are available everywhere as settings.<id>. section.settings is for one section only.
  3. 3. Why print settings as CSS variables inside a style tag in the head?

    Variables centralize the mapping from settings to CSS, so your stylesheet stays static and a single merchant edit updates every use.
  4. 4. What does a color_scheme_group define?

    The group lists the colors every scheme contains. The merchant edits several schemes globally and each section picks one with a color_scheme setting.

Summary

  • settings_schema.json defines global controls in groups; settings_data.json stores the merchant's saved values and should not be overwritten casually.
  • Read global settings anywhere with settings.<id>.
  • Convert settings to CSS variables in one {% style %} block, then keep your stylesheet static.
  • font_picker values need font_face to load and give you family and weight for CSS.
  • A color_scheme_group plus per-section color_scheme pickers give you flexible, merchant-controlled looks.

Next, see how the main page types are assembled in Product, Collection, Cart and Page Templates.