.dev
Partner Dashboard

Settings ​

Last updated View as Markdown

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.

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

Each setting is checked against its type when the file is saved. The save is rejected when:

  • type is not one of the input or display setting types;
  • an input setting has no id or label, or a display setting has no content;
  • a range has no min or max, or they are not numbers;
  • a radio or select has no options array, or a video_url has no accept array.

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:

liquid
// 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.

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

Dynamic sources ​

You can reference a Liquid object in a section or block setting value with {{ }}. The reference is resolved each time the setting is read in a template. The objects of the page are used.

json
{
  "type": "heading",
  "settings": {
    "text": "<h2>{{ closest.collection.title }}</h2>"
  }
}

On a collection page, you get the collection title inside the h2 tag when you print {{ block.settings.text }}.

  • In a text setting, such as text, textarea or richtext, you can put several references and other text in the value.
  • In a resource or media setting, such as product, collection or image_picker, use one reference as the whole value, for example {{ closest.product }}. You get the object.
  • Write a reference as a path to an object, for example {{ product.title }} or {{ closest.collection.title }}.
  • Filters and tags are not resolved. A reference with a filter or a tag is printed as text.
  • When the object does not exist on the page, the reference is replaced by an empty string.
  • References in color settings are not resolved. In color settings, you can use color palette references only.
  • You can also use a reference in a schema default or in a preset value.

See the closest object for the nearest product, collection, page, blog or article.

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:

PropertyTypeRequiredDescription
setting_idstringYesThe id of the setting whose value is evaluated.
valuestring | number | booleanYesThe value to compare against.
operatorstringNoThe comparison operator. Defaults to ==.

Operators ​

OperatorDescription
==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:

json
{
  "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:

json
{
  "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:

json
{
  "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).

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

Liquid conditions ​

visible_if can also be a Liquid string:

json
{
  "type": "range",
  "id": "logo_height",
  "label": "Logo height",
  "min": 20,
  "max": 120,
  "step": 4,
  "default": 40,
  "visible_if": "{{ settings.logo != blank }}"
}

The theme editor evaluates the condition each time a value changes, and shows the setting only when the condition is true. The condition can read:

  • settings: the theme settings.
  • section.settings: the settings of the section.
  • block.settings: the settings of the block, in a block.

A setting that has no value uses its default. Liquid objects such as product or collection are not available in a condition. If the theme editor cannot evaluate a condition, the setting is shown.

Any other value for visible_if, for example true, is rejected when the theme is saved.