Settings

You can use section JSON schemas to create settings, allowing sellers to customize your theme with little to no technical experience.

These settings can be defined on sections, blocks, or on the theme itself.

Types

There are two main types of settings:

• Input settings - Settings that can hold a value and are configurable by sellers.

• Display settings - These are static values with which you can provide context about parts of your theme to the seller.

Location

Settings can exist in one of two places:

• sections/*.liquid - Can be defined on the section's {% schema %} tag. These can either be section settings or block settings, accessible from the section and block objects respectively.

• config/settings_schema.json - Can be defined at the theme level. These can be accessed from the global settings object.

Schema

Settings can be defined as an array of setting schema objects as a settings attribute on the appropriate object.

{
  ...
  "settings": [
    {
      "type": "header",
      "content": "Product settings"
    },
    {
      "id": "product_1",
      "type": "text",
      "label": "Product identifier",
      "info": "Select a product id to display"
    }
  ],
  ...
}

Access

Settings can be accessed by referencing the appropriate liquid object, this can be one of the following:

• The section object.
• The block object.
• The global settings object.

For example, if you have your settings as is shown above on each of these liquid object, you may access them as follows:

// settings
Product identifier: {{ settings.product_1 }}

// section
Product identifier: {{ section.settings.product_1 }}

// block
Product identifier: {{ block.settings.product_1 }}

Checking for a setting's value

You should always check a setting's value before using it, blank or nil values are converted into an empty string when referenced.

When referencing a simple setting, you may check whether or not it is an empty string by comparing it to the liquid blank object.

 {%- if section.settings.product_1 != blank -%}
  {{ section.settings.product_1 }}
 {%- endif -%}

Conditional settings

You can conditionally show or hide a setting in the theme editor based on the current value of another setting in the same section, block, or theme settings category.

Use the visible_if property on any setting to define the condition.

You can conditionally show/hide any input or display setting type.

Note: The referenced setting_id must belong to the same settings array as the setting that declares visible_if. You cannot reference a setting from a different section, block, or theme settings category.

Structure

visible_if is an object with the following properties:

Property	Type	Required	Description
setting_id	string	Yes	The id of the setting whose value is evaluated.
value	string | number | boolean	Yes	The value to compare against.
operator	string	No	The comparison operator. Defaults to ==.

Operators

Operator	Description
==	Equal to (default)
!=	Not equal to
>	Greater than
<	Less than
>=	Greater than or equal to
<=	Less than or equal to

Examples

Show a setting only when a checkbox is enabled:

{
  "type": "checkbox",
  "id": "show_overlay",
  "label": "Show overlay",
  "default": false
},
{
  "type": "color",
  "id": "overlay_color",
  "label": "Overlay color",
  "default": "#000000",
  "visible_if": {
    "setting_id": "show_overlay",
    "value": true
  }
}

Show a setting only when a specific option is selected:

{
  "type": "select",
  "id": "layout",
  "label": "Layout",
  "options": [
    { "value": "grid", "label": "Grid" },
    { "value": "list", "label": "List" }
  ],
  "default": "grid"
},
{
  "type": "number",
  "id": "columns",
  "label": "Columns",
  "default": 3,
  "visible_if": {
    "setting_id": "layout",
    "value": "grid"
  }
}

Show a setting based on a numeric threshold:

{
  "type": "number",
  "id": "item_count",
  "label": "Number of items",
  "default": 3
},
{
  "type": "checkbox",
  "id": "show_pagination",
  "label": "Show pagination",
  "default": false,
  "visible_if": {
    "setting_id": "item_count",
    "operator": ">",
    "value": 5
  }
}

Multiple conditions

To require multiple conditions to all be true simultaneously, pass an array of condition objects. All conditions must be satisfied for the setting to be visible (AND logic).

{
  "type": "text",
  "id": "button_label",
  "label": "Button label",
  "visible_if": [
    { "setting_id": "show_button", "value": true },
    { "setting_id": "button_style", "value": "custom" }
  ]
}