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.
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 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.
There are two categories of settings:
Category | Description |
---|---|
Input settings | Settings that can hold a value, and are configurable by merchants. |
Sidebar settings | Settings that can’t hold a value, and aren’t configurable by merchants. They’re informational elements that can be used to provide detail and clarity for your input settings. |
You can create settings in the following places:
config
>settings_schema.json
- Section files in the
sections
folder, using the the section's{% schema %}
tag
settings_schema.json
Anchor link to section titled "settings_schema.json"The 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.
Section schema
Anchor link to section titled "Section schema"The section {% schema %}
tag is where you can create section settings and block settings. Those settings can be accessed through the settings
attribute of the section
object and block
object, respectively.
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.
When working with settings, you should familiarize yourself with the following:
- Translating settings
- Accessing setting values
- Checking the setting value format
- Using dynamic sources for settings
- Platform-controlled settings
Translate settings
Anchor link to section titled "Translate settings"You can translate various attributes of the settings schema depending on the online store's active language. These translations are stored in schema locale files.
Access settings
Anchor link to section titled "Access settings"Depending on where they were created, you can access settings through the following Liquid objects:
- The global
settings
object - The
section
object - The
block
object
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:
Then the following Liquid would generate the following output:
Check the format of the setting value
Anchor link to section titled "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.
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:
You can check whether a value is an empty string with the blank
operator. For example:
Resource-based settings
Anchor link to section titled "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:
Then you can check for emptiness like the following:
Legacy resource-based settings
Anchor link to section titled "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:
Dynamic sources
Anchor link to section titled "Dynamic sources"Settings for sections included in a JSON template have the option for merchants to connect one or more dynamic sources to the setting, depending on the setting type.
A dynamic source can be either:
- A metafield value
- A resource attribute
Available values
Anchor link to section titled "Available values"Shopify determines the value of each available dynamic source type based on the following:
- The resource associated with the template that the section is in
- The resource settings in the context of the current setting
For example:
Conditions | Description |
---|---|
The section is included as part of the product template | Metafields and attributes related to the product will be available for the following:
|
The section includes a collection type setting | Metafields and attributes related to the collection will be available for the following:
|
The section's blocks include a product type setting | Metafields and attributes for that product will be available for the block's settings. |
The following table lists the available resources and their associated attributes:
Resource | Attributes |
---|---|
product |
|
collection |
|
page |
|
The following outlines which setting and metafield types will be compatible:
Setting | Metafield(s) | Metafield validation options |
---|---|---|
collection |
|
|
collection_list |
|
|
color |
|
|
image_picker |
|
|
page |
|
|
product |
|
|
product_list |
|
|
richtext |
|
|
text |
|
|
url |
|
|
video |
|
Must accept video file types |
Default values
Anchor link to section titled "Default values"You can configure a setting's default value to reference a dynamic source. However, only do this if you're rendering a section or block in a context where the dynamic source value exists. For example, don't use a product-related value in a section that:
Can be rendered in non-product templates
Doesn't explicitly have a
product
type setting to provide the necessary value
Additional Liquid is invalid when using this method, so you can only reference the value directly. If you include additional Liquid, then you'll get an error.
The following is an example of a default
setting that references a dynamic source:
Platform-controlled settings
Anchor link to section titled "Platform-controlled settings"In the theme editor, Shopify exposes a custom CSS setting 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, or in the settings_data.json platform_customizations
object.
This setting is intended to allow merchants 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 and stylesheet
Liquid tags, and introduce customization options for CSS in these areas using theme settings.