Configuration

Theme configuration covers the settings that apply to the whole store, not just one section. It includes the settings schema, the current settings values, and the translation files.

Settings schema

The config/settings_schema.json file defines the settings form in the visual editor's "Theme settings" panel. It works like a section schema, but the values are stored on the theme instead of a single section.

[
  {
    "name": "Colours",
    "settings": [
      {
        "type": "color",
        "id": "primary_color",
        "label": "Primary colour",
        "default": "#1a1a1a"
      },
      {
        "type": "color",
        "id": "accent_color",
        "label": "Accent colour",
        "default": "#e63946"
      },
      {
        "type": "color",
        "id": "background_color",
        "label": "Background",
        "default": "#ffffff"
      }
    ]
  },
  {
    "name": "Typography",
    "settings": [
      {
        "type": "font_picker",
        "id": "body_font",
        "label": "Body font",
        "default": "inter_n4"
      },
      {
        "type": "font_picker",
        "id": "heading_font",
        "label": "Heading font",
        "default": "playfair_display_n7"
      }
    ]
  },
  {
    "name": "Social media",
    "settings": [
      {
        "type": "text",
        "id": "social_instagram",
        "label": "Instagram URL"
      },
      {
        "type": "text",
        "id": "social_twitter",
        "label": "X (Twitter) URL"
      },
      {
        "type": "text",
        "id": "social_facebook",
        "label": "Facebook URL"
      }
    ]
  }
]

The top-level array contains groups. Each group has a name (shown as a heading in the editor) and a settings array. The setting types are the same as in section schemas.

Accessing theme settings

Use theme.settings in any template, section, or snippet:

<body style="background: {{ theme.settings.background_color }}; color: {{ theme.settings.primary_color }}">

{% if theme.settings.social_instagram != blank %}
  <a href="{{ theme.settings.social_instagram }}">Instagram</a>
{% endif %}

Theme settings are global. They are the same on every page. Use them for values that need to be consistent across the whole store.

Settings data

The config/settings_data.json file stores the current values. You do not edit this file by hand. The visual editor writes to it when the merchant changes a setting.

{
  "current": {
    "primary_color": "#1a1a1a",
    "accent_color": "#e63946",
    "background_color": "#ffffff",
    "body_font": "inter_n4",
    "heading_font": "playfair_display_n7",
    "social_instagram": "https://instagram.com/mystore"
  }
}

Locale files

Translation files live in the locales/ folder. Each file is named with a language code:

locales/
  en.json
  fr.json
  de.json
  es.json

Each file is a nested JSON object. The keys match what you pass to the t filter:

{
  "general": {
    "search": "Search",
    "cart": "Cart",
    "menu": "Menu"
  },
  "product": {
    "add_to_cart": "Add to Cart",
    "sold_out": "Sold Out",
    "quantity": "Quantity"
  },
  "cart": {
    "title": "Your Cart",
    "empty": "Your cart is empty",
    "subtotal": "Subtotal",
    "checkout": "Checkout"
  }
}

Use the t filter to look up a key:

<button>{{ 'product.add_to_cart' | t }}</button>

The output depends on the visitor's language. In English: Add to Cart. In French: Ajouter au panier.

Variables in translations

Pass dynamic values into a translation string:

{
  "cart": {
    "item_count": "{{ count }} items in your cart"
  }
}

{{ 'cart.item_count' | t: count: cart.item_count }}

Output: 3 items in your cart

Adding a new language

To support a new language, create a new JSON file in the locales/ folder. Copy the structure from en.json and translate every value. The platform picks the right file based on the visitor's locale setting.

Theme settings vs section settings

Scope	Where defined	Where used	Example
Theme	`config/settings_schema.json`	`theme.settings.x`	Brand colours, fonts, social links
Section	`{% schema %}` in the section	`section.settings.x`	Section heading, layout options

Use theme settings for values that need to be the same everywhere. Use section settings for values that change per section.