---
title: Settings
description: >-
  Learn about the types of settings that you can provide to merchants using your
  theme.
source_url:
  html: 'https://shopify.dev/docs/storefronts/themes/architecture/settings'
  md: 'https://shopify.dev/docs/storefronts/themes/architecture/settings.md'
api_name: liquid
---

# Settings

To make it easier for merchants to customize your theme, you can use JSON to create settings that merchants can access through the [theme editor](https://help.shopify.com/en/manual/online-store/themes/customizing-themes/edit#theme-editor).

You can provide settings at the theme, section, or block level. Settings can be fixed (such as informational elements) or interactive (such as a drop-down menu). Setting values can be static, or use [dynamic sources](https://shopify.dev/docs/storefronts/themes/architecture/settings/dynamic-sources) to render contextually appropriate values.

Exposing settings makes your theme more customizable so it can better express a merchant's brand. It also can make your theme more flexible so that you can address various use cases for merchants.

***

## Subtypes

There are two categories of settings:

| Category | Description |
| - | - |
| [Input settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings) | Settings that can hold a value, and are configurable by app users. |
| [Sidebar settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/sidebar-settings) | Settings that can’t hold a value, and aren’t configurable by app users. They’re informational elements that can be used to provide detail and clarity for your input settings. |

***

## Location

You can create settings in the following places:

* `config` > [`settings_schema.json`](#settings_schema-json)
* Section files in the `sections` folder, using the [the section's `{% schema %}` tag](#section-schema)

```text
└── theme
  ├── config
  |   ├── settings_schema.json
  |   ...
  ├── sections
  |   ├── main_product.liquid
  |   ├── another_section_file.liquid
  |   ...
  ...
```

### settings\_​schema.​json

The [settings\_schema.json](https://shopify.dev/docs/storefronts/themes/architecture/config/settings-schema-json) file controls the content of the **Theme settings** area of the theme editor. Settings in this file translate to global theme settings, which can be accessed through the Liquid [settings object](https://shopify.dev/docs/api/liquid/objects/settings).

### Section schema

The section `{% schema %}` tag is where you can create [section settings](https://shopify.dev/docs/storefronts/themes/architecture/sections/section-schema#settings) and [block settings](https://shopify.dev/docs/storefronts/themes/architecture/sections/section-schema#blocks). Those settings can be accessed through the `settings` attribute of the [`section` object](https://shopify.dev/docs/api/liquid/objects/section#section-settings) and [`block` object](https://shopify.dev/docs/api/liquid/objects/block#block-settings), respectively.

***

## Schema

Settings are defined as a JSON `settings` attribute that's parented to the object that the settings apply to. This attribute accepts an array of settings. Input settings and sidebar settings both use standard schema attributes. You can find detailed descriptions of these attributes in their respective sections:

* [Input Settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#standard-attributes)
* [Sidebar settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/sidebar-settings#standard-attributes)

Most setting types may be [conditionally set](https://shopify.dev/docs/storefronts/themes/architecture/settings#conditional-settings) using the `visible_if` attribute.

## Basic setting example

```json
{
  ...
  "settings": [
    {
      "type": "header",
      "content": "My settings"
    },
    {
      "type": "text",
      "id": "my_id",
      "label": "My setting label",
      "default": "Enter text here"
    },
    {
      "type": "select",
      "id": "layout_style",
      "label": "type",
      "options": [
        {
          "value": "flex",
          "label": "Stack"
        },
        {
          "value": "grid",
          "label": "Grid"
        }
      ],
      "default": "flex"
    },
    {
      "type": "select",
      "id": "content_direction",
      "label": "Direction",
      "options": [
        { "value": "row", "label": "Horizontal" },
        { "value": "column", "label": "Vertical" }
      ],
      "default": "column",
      "visible_if": "{{ block.settings.layout_style == 'flex' }}"
    }
  ],
  ...
}
```

***

## Usage

When working with settings, you should familiarize yourself with the following:

* [Accessing setting values](#access-settings)
* [Checking the setting value format](#check-the-format-of-the-setting-value)
* [Using dynamic sources for settings](#dynamic-sources)

### Access settings

Depending on where they were created, you can access settings through the following Liquid objects:

* The [global `settings` object](https://shopify.dev/docs/api/liquid/objects/settings)
* The [`section` object](https://shopify.dev/docs/api/liquid/objects/section#section-settings)
* The [`block` object](https://shopify.dev/docs/api/liquid/objects/block#block-settings)

**Note:**

Settings from the `settings` object can be accessed in Liquid [theme assets](https://shopify.dev/docs/storefronts/themes/architecture#assets).

To access a specific setting, append the `id` attribute of the associated setting to the object that you want to access.

For example, if you had the following setting implemented in each Liquid object:

```json
{
  "type": "text",
  "id": "message",
  "label": "Message",
  "default": "Hello!"
}
```

Then the following Liquid would generate the following output:

## Input

```liquid
// Settings
Message: {{ settings.message }}


// Section
Message: {{ section.settings.message }}


// Block
Message: {{ block.settings.message }}
```

## Output

```text
// Settings
Message: Hello!


// Section
Message: Hello!


// Block
Message: Hello!
```

### Check the format of the setting value

When referencing settings, you should always check that the value is in the format that you expect. Any setting without an automatic default value could end up with no value, which translates to an empty [string](https://shopify.dev/docs/api/liquid/basics/types#string).

For example, if you have a setting with an `id` of `message`, then the following Liquid would generate the following output depending on the value:

## Input

```liquid
// No value
Setting: {{ settings.message }}


// With value
Setting: {{ settings.message }}
```

## Output

```text
// No value
Setting:


// With value
Setting: Message value
```

You can check whether a value is an empty string with the `blank` operator. For example:

```liquid
{% unless settings.message == blank %}
  {{ settings.message }}
{% endunless %}
```

#### Resource-based settings

To avoid an empty string, check that the value is in the format that you expect. It's possible that no resource was selected, selected resource no longer exists, or the selected resource has been hidden.

For example, if you have the following `page` type setting:

```json
{
  "type": "page",
  "id": "page",
  "label": "Page"
}
```

Then you can check for emptiness like the following:

```liquid
{% if settings.page != blank %}
  {{ settings.page.title }}
  {{ settings.page.content }}
{% else %}
  No page, or invalid page, selected.
{% endif %}
```

**Tip:**

Resource-based settings didn't always return the resource object. To learn more, refer to [Legacy resource-based settings](#legacy-resource-based-settings).

#### Legacy resource-based settings

In the past, resource-based settings returned the handle of the associated resource, and you had to access the actual object through Liquid using that handle.

For example, if you had the following product setting, then you would need to access the product object like the following:

## Setting

```json
{
  "type": "product",
  "id": "product",
  "label": "Product"
}
```

## Access setting

```liquid
{% unless settings.product == blank %}
  {% assign product = all_products[settings.product] %}


  {% if product %}
    {{ product.title }} - {{ product.price }}
  {% else %}
    No product, or invalid product, selected.
  {% endif %}
{% endunless %}
```

### Dynamic sources

Settings for sections and blocks included in a [JSON template](https://shopify.dev/docs/storefronts/themes/architecture/templates/json-templates) have the option for merchants to [connect one or more dynamic sources to the setting](https://help.shopify.com/manual/metafields/displaying-metafields-on-your-online-store#connecting-metafields-to-your-theme-by-using-the-theme-editor), depending on the setting type.

[Learn more about dynamic sources](https://shopify.dev/docs/storefronts/themes/architecture/settings/dynamic-sources).

***

## Conditional settings

Settings can be displayed conditionally by passing a boolean expression to the `visible_if` attribute:

```json
"visible_if": "{{ block.settings.layout_style == 'flex' }}"
```

Not all settings can be conditionally set. The following settings support conditional settings:

* All [basic input settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#basic-input-settings)

* All [sidebar settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/sidebar-settings)

* These [specialized input settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings):

  * [color](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#color)
  * [color\_background](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#color_background)
  * [color\_scheme](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#color_scheme)
  * [font\_picker](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#font_picker)
  * [html](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#html)
  * [image\_picker](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#image_picker)
  * [inline\_richtext](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#inline_richtext)
  * [link\_list](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#link_list)
  * [liquid](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#liquid)
  * [richtext](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#richtext)
  * [text\_alignment](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#text_alignment)
  * [url](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#url)
  * [video](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#video)
  * [video\_url](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings#video_url)

**Note:**

Conditional settings cannot access runtime context or resolved data source values. While you can check if a setting with a data source *has a value*, you cannot create conditions based on what that data source *resolves to*.

***

## Platform-controlled settings

In the theme editor, Shopify exposes a [custom CSS setting](https://help.shopify.com/manual/online-store/themes/theme-structure/extend/add-css) at the theme and section level. You can't add or hide this setting in your settings schema.

Any custom CSS that merchants add using this setting is stored in a `custom_css` attribute, either in a JSON template's [section attribute](https://shopify.dev/docs/storefronts/themes/architecture/templates/json-templates#schema), or in the [settings\_data.json](https://shopify.dev/docs/storefronts/themes/architecture/config/settings-data-json) `platform_customizations` object.

This setting is intended to enable users to customize the look and feel of their storefront without editing theme code. As a theme developer, you shouldn't add this setting, or edit the value of this setting after it's set. Instead, you should use dedicated [CSS assets](https://shopify.dev/docs/storefronts/themes/architecture#assets) and [`stylesheet` Liquid tags](https://shopify.dev/docs/storefronts/themes/best-practices/javascript-and-stylesheet-tags#stylesheet), and introduce customization options for CSS in these areas using [theme settings](https://shopify.dev/docs/storefronts/themes/architecture/settings).

***

## Translate settings

Two kinds of translation apply to settings:

* **Schema attributes** (a setting's `label`, `info`, and option text): defined by the theme and translated through [schema locale files](https://shopify.dev/docs/storefronts/themes/architecture/locales/schema-locale-files), based on the store's [active language](https://help.shopify.com/manual/online-store/themes/customizing-themes/language/translate-theme#choose-a-language-for-your-theme).
* **Merchant-entered values** (the content a merchant enters into a setting): translated by the merchant in [Translate & Adapt](https://help.shopify.com/manual/online-store/themes/customizing-themes/language/translate-theme) for text-bearing settings such as `text`, `richtext`, and `html`. A `liquid` setting's value isn't translatable this way. To learn how each setting type behaves, refer to [Input settings](https://shopify.dev/docs/storefronts/themes/architecture/settings/input-settings).

***