Configuring theme settings
You can use JSON to create settings that merchants can access using the theme editor. A merchant accesses the editor by clicking Customize from the Themes page of their Shopify admin.
About JSON settings
JSON settings can be included in two types of files:
- The
settings_schema.json
file. This file controls the organization and content of the Theme settings area of the theme editor. The settings in this file can be referenced by any other files in your theme. This file is located in theconfig
directory of a theme. - Liquid section files. These files control the appearance and functionality of sections in your theme. The
{% schema %}
tag in this file controls the organization and content of each section's settings in the theme editor. The settings in each section file are specific to the section and can't be referenced by other files in your theme. These files are located in thesections
directory of a theme.
If you edit the JSON settings of your theme settings or sections, your changes must follow the specified file format.
To learn how to reference these settings, refer to Working with other theme files.
If your theme has no settings_schema.json file
If a theme doesn't have a settings_schema.json
file, you can do one of the following actions:
- generate the file automatically
- create a new one from scratch as part of the initial theme development.
You should edit the file according to its specified file format.
Generating automatically
If a theme has no settings_schema.json
file, you can generate one automatically by either of the following actions:
- opening the theme's Edit HTML/CSS page
- exporting the theme.
The generated settings_schema.json
file is saved in the config
directory.
After you generate the file, make sure you edit it according to the specified file format.
Creating from scratch
If you create a settings_schema.json
from scratch, make sure that you:
- save it in the
config
directory - follow the specified file format.
To see examples, look at the settings_schema.json
file for any Shopify theme.
Editing JSON settings
You can edit JSON settings for your sections or theme settings from your Shopify admin.
Open one of the following files:
To edit theme settings: From the file directory in the sidebar, open the Configs folder and click
settings_schema.json
.To edit a section's settings: From the file directory in the sidebar, open the Sections folder and click the appropriate section.
When you've finished editing, click Save.
File format overview
Both settings_schema.json
and Liquid section files contain the definitions for your theme or section settings, grouped into sections according to the setting type. The grouping of the settings is reflected in the theme editor.
In Liquid section files, the settings for the section are enclosed in {% schema %}
and {% endschema %}
tags.
There are two categories of setting:
Input settings: These control the settings that can be configured by merchants.
Sidebar settings: These are not configurable by the merchant. They control informational elements (headers and paragraphs), which you can use to add detail and clarity to the theme editor sidebar.
Defining a theme setting
The structure of the settings definitions is as follows:
- Each
settings
entry contains definitions for individual settings. - Each individual setting has a few attributes, which vary depending on whether the setting is for merchant input or sidebar styling.
Settings extract
Here's an example of a settings
definition for two input settings of type color
in the settings_schema.json
file:
[
{
"name": "Colors",
"settings": [
{
"type": "color",
"id": "color_borders",
"label": "Border colors",
"default": "#e5e5e5"
},
{
"type": "color",
"id": "color_body_text",
"label": "Body text",
"default": "#333333"
}
]
}
]
The JSON structure is validated before it is saved to make sure it follows the correct format.
Attributes for input settings
Input settings are used by the merchant to configure the theme settings for their store. The merchant accesses the settings from the theme editor sidebar.
When defining input settings, use the attributes shown in the table:
Attribute | Required? | Description |
---|---|---|
type |
yes | Name of the type of settings. |
id |
yes | The unique name for this setting. The id is exposed to the Liquid templates via the settings or section.settings objects. It must only contain alphanumeric characters, underscores, and dashes. |
label |
yes | A label for this setting. |
placeholder |
no | A value for the input's placeholder text. This is for text-based setting types only. |
default |
no | A value to which the setting can default. |
info |
no | Additional information about the setting. Use sparingly, as it's better to use only informative labels whenever you can. |
Creating links
You can add links to the info
and content
fields using the pattern [link text](link URL)
. For example:
{
"type": "checkbox",
"id": "enable_payment_button",
"label": "Show dynamic checkout button",
"info": "Each customer will see their preferred payment method from those available on your store, such as PayPal or Apple Pay. [Learn more](https://help.shopify.com/manual/using-themes/change-the-layout/dynamic-checkout)",
"default": true
},
Input setting types
The JSON setting schema accepts a range of values for the setting type
, in two broad categories:
Basic input setting types
You can set the type
attribute for basic input settings to any of the values shown in the table below:
Value | Application |
---|---|
text | Single-line text fields |
textarea | Multi-line text areas |
radio | Radio buttons |
select | Selection drop-downs |
checkbox | Checkboxes |
range | Range sliders |
number | A number field that accepts integers or floats |
Single-line text fields
A setting of type text
is used for capturing short strings, such as URLs, social media usernames, sales banner text, etc.
Input
{
"type": "text",
"id": "id",
"label": "text",
"default": "value",
"info": "text",
"placeholder": "text"
}
Example
{
"type": "text",
"id": "footer_linklist_title",
"default": "Quick links",
"label": "Heading"
}
Output
Multi-line text areas
A setting of type textarea
is used for capturing larger blocks of text, such as embed codes.
Input
{
"type": "textarea",
"id": "id",
"label": "text",
"default": "value",
"info": "text",
"placeholder": "text"
}
Example
{
"type": "textarea",
"id": "home_welcome_message",
"default": "Welcome to my shop!",
"label": "Welcome message"
}
Output
Radio button
A setting of type radio
is used for presenting mutually exclusive options to the merchant, for example, selecting the alignment of the logo.
Input
{
"type": "radio",
"id": "id",
"label": "text",
"options": [
{ "value": "one", "label": "Radio one" },
{ "value": "two", "label": "Radio two" }
],
"default": "one",
"info": "text"
}
Example
{
"type": "radio",
"id": "logo_alignment",
"options": [
{ "value": "left", "label": "Left"},
{ "value": "center", "label": "Centered"}
],
"label": "Logo alignment"
}
Output
Selection drop-down
A setting of type select
is used for presenting a large number of options to the merchant, for example, selecting the number of products to show on the product page.
Options for the setting of type select
can be grouped by setting a value for group
for each option.
Input
{
"type": "select",
"id": "id",
"label": "text",
"options": [
{
"group": "value",
"value": "value",
"label": "text"
},
{
"group": "value",
"value": "value",
"label": "text"
}
],
"default": "value",
"info": "text"
}
Example
{
"type": "select",
"id": "vertical_alignment",
"options": [
{ "value": "top", "label": "Top"},
{ "value": "middle", "label": "Middle"},
{ "value": "bottom", "label": "Bottom"}
],
"label": "Vertical alignment"
}
Output
Checkbox
A setting of type checkbox
is used for toggling preferences on or off, for example, showing or hiding elements on a page.
The values of checkboxes are always forced to be 1
. Hidden fields are inserted by Shopify in the theme editor that is generated for each checkbox, to allow for false
values to be submitted appropriately.
Input
{
"type": "checkbox",
"id": "id",
"label": "text",
"default": false,
"info": "text"
}
Example
{
"type": "checkbox",
"id": "home_page",
"default": true,
"label": "Home page only"
}
Output
Range
The range input setting lets you add a slider that selects from a range of values. For example, merchants can use the range slider to select a font size for text, or to set the spacing between elements. You must set minimum and maximum values for the slider, and optionally a unit of measure such as pixels, seconds, or percentage. The theme editor preview updates as the merchant moves the slider so that they can see their changes in real time.
Range input sliders should only be used when you want to provide merchants with finer control over how an element looks, but you don't need merchants to set a specific value. As a best practice, only use a range input slider when the merchant can rely on the theme preview to see how the element will look.
When setting up your range input slider, keep the following in mind:
- The
step
refers to the step count for the slider values. For example, if you set thestep
to 5, then the range slider will count by fives. By default, thestep
is set to 1. - Your slider must have a minimum of 3 steps, and a maximum of 101 steps.
- The
default
is the value that the slider will be pointing to by default. The default value must be a multiple of the step value that you set. For example, if you set your step to 5, then your default value must be a multiple of 5. If you set your step count to 5, and set a default of 33, you will get an error. - The
default
,min
,max
, andstep
values must be numbers. The numbers can be integers or floats. - The
min
andmax
values must be greater than -10000 and less than 10000. - The unit of measure label can have a maximum of 3 characters. For example, you could use
sec
for seconds, orpx
for pixels.
Input
{
"type": "range",
"id": "id",
"min": value,
"max": value,
"step": value,
"unit": "text",
"label": "text",
"default": value
}
Example
{
"type": "range",
"id": "font_size",
"min": 12,
"max": 18,
"step": 1,
"unit": "px",
"label": "Font size",
"default": 16
}
Output
Number
The number input setting lets you add a number field that accepts keyboard input. For example, merchants can use the number field to adjust a free value like a maximum number of products per customer. You should use a number input when you want to let merchants set a specific value.
This field doesn't accept units of measure or minimum and maximum values. If you need these features, then you should use a Range slider.
The default
is the value that appears in the field by default. This value must be a number. The number can be an integer or a float.
Input
{
"type": "number",
"id": "id",
"label": "text",
"default": value
}
Example
{
"type": "number",
"id": "products_per_customer",
"label": "Max products per customer",
"default": 4
}
Output
Specialized input setting types
As well as basic input setting types, you can also provide specialized theme settings options for merchants.
Set the type
attribute for specialized input settings to any of the values shown in the table.
Value | Application |
---|---|
color | Color picker |
font_picker | Font picker |
collection | Collection selector |
product | Product selector |
blog | Blog selector |
page | Page selector |
link_list | Menu selector |
url | URL |
video_url | Video URL |
richtext | Formatting text that contains HTML |
html | Custom HTML |
article | Article selector |
image_picker | Image selector |
Color picker
Settings of type color
present a color picker to the merchant.
Input
{
"type": "color",
"id": "id",
"label": "text",
"default": "value",
"info": "text"
}
Example
{
"type": "color",
"id": "background_color",
"label": "Background color",
"default": "#ffffff"
}
Output
Font picker
Settings of type font_picker
generate a resource list that is automatically filled with fonts from Shopify's font library. The library includes web-safe fonts, a selection of Google Fonts, and fonts licensed from Monotype.
You can learn more about how to load selected fonts in the Liquid reference for the font
object.
Input
{
"type": "font_picker",
"label": "text",
"id": "id",
"info": "text",
"default": "helvetica_n4"
}
Example
{
"name": "Typography",
"settings": [
{
"type": "font_picker",
"label": "Heading font",
"id": "heading_font",
"default": "helvetica_n4"
}
]
}
You can find the possible values for default
in Shopify's font library.
Output
Collection selector
Settings of type collection
generate a resource list that is automatically filled with the names of all the collections in the store. The output of the option the merchant selects from the resource list is the handle of the collection.
Input
{
"type": "collection",
"id": "id",
"label": "text",
"info": "text"
}
Example
{
"type": "collection",
"id": "feature_collection",
"label": "Featured collection"
}
Output
Product selector
Settings of type product
generate a resource list that is automatically filled with the names of all the products in the store. The output of the option the merchant selects from the list is the handle of the product.
Input
{
"type": "product",
"id": "id",
"label": "text",
"info": "text"
}
Example
{
"type": "product",
"id": "feature_product",
"label": "Featured product"
}
Output
Blog selector
Settings of type blog
generate a resource list that is automatically filled with the names of all the blogs in the store. The output of the option the merchant selects from the list is the handle of the blog.
Input
{
"type": "blog",
"id": "id",
"label": "text",
"info": "text"
}
Example
{
"type": "blog",
"id": "sidebar_blog",
"label": "Blog for sidebar"
}
Output
Page selector
Settings of type page
generate a resource list that is automatically filled with the names of all pages in the store. The output of the option the merchant selects from the list is the handle of the page.
Input
{
"type": "page",
"id": "id",
"label": "text",
"info": "text"
}
Example
{
"type": "page",
"id": "homepage",
"label": "Front page"
}
Output
Menu selector
Settings of type link_list
generate a resource list that is automatically filled with the names of all the menus in the store. The output of the option the merchant selects from the list is the handle of the link list menu.
link_list
settings accept an optional default
parameter, which can be set to main-menu
or footer
.
Input
{
"type": "link_list",
"id": "id",
"label": "text",
"info": "text"
}
Example
{
"type": "link_list",
"id": "main_nav",
"label": "Main navigation"
}
Output
URL
A url
setting lets merchants link to one of the following resources using a picker in the theme editor:
- Articles, blogs, collections, pages, or products
- External URLs (such as
https://example.com
) - Relative paths (such as
/relative/path#anchor
or#about-us
)
url
settings accept an optional default
parameter, which can be set to /collections
or /collections/all
.
For example:
Input
{
"id": "banner_call_to_action",
"type": "url",
"label": "Banner button link"
}
With Liquid
<a href="{{ settings.banner_call_to_action }}">Get started</a>
Output
<a href="/products/leather-bag">Get started</a>
Video URL
A video_url
setting lets merchants insert a video as the content for a block using the video's URL:
{
"id": "video_url",
"type": "video_url",
"label": "Video URL",
"accept": ["youtube", "vimeo"],
"default": "https://www.youtube.com/watch?v=_9VUPq3SxOc",
"info": "text",
"placeholder": "text"
}
A video_url
setting can have the following attributes:
accept
— (required) an array with the URL types that the field accepts. Valid values areyoutube
orvimeo
or both.default
— (optional) the default video to use if no URL is provided.info
— (optional) additional information about the setting, if required. This field will default to a list of URL types that the field accepts.placeholder
— (optional) the input's placeholder text.
You can reference a video_url
setting with Liquid using the syntax {{ settings.video_url }}
. You can reference parts of the URL with Liquid parameters:
{{ settings.video_url.id }}
— the video ID. In the example above, this would beLGb3j1CyH0k
.{{ settings.video_url.type }}
— the site the video is hosted on. In the example above, this would beyoutube
.
RichText
You can use richtext
settings to allow text content with basic formatting. Supported formatting options are bold, italic, underline, links, and paragraphs.
For example:
Input
{
"type": "richtext",
"id": "column_richtext",
"label": "text",
"default": "<p>Default <em>richtext</em> <a href=\"https://example.com/\">content</a></p>"
}
Example
{
"column_richtext": "<p>Content for <strong>richtext</strong> <a href=\"https://example.com/\">setting</a></p>"
}
With Liquid
<div class="rte">{{ settings.column_text }}</div>
Output
Supported content
Supported HTML tags: <p>
, <br>
, <strong>
, <b>
, <em>
, <i>
, <u>
, <span>
, <a>
More HTML tags will be supported in the future.
Top level nodes (including text nodes) should always be wrapped in <p>
tags.
Invalid content | Valid content |
---|---|
Hello World
|
<p>Hello World</p>
|
<em>Hello World</em>
|
<p><em>Hello World</em></p>
|
<p>Hello</p> World
|
<p>Hello</p> <p>World</p>
|
<p>Hello</p> World<p>!!</p>
|
<p>Hello</p> <p>World</p><p>!!</p>
|
<p>Hello</p> <em>World</em><p>!!</p>
|
<p>Hello</p> <p><em>World</em></p><p>!!</p>
|
<a href="https://example.com/">Hello</a>
|
<p><a href="https://example.com/">Hello</a></p>
|
HTML
An html
setting lets merchants add custom HTML code which renders as content for a block. Unclosed tags are automatically closed when settings are saved.
For example:
Input
{
"type": "html",
"id": "html_area",
"label": "Custom HTML",
"default": "<div><p>Some HTML content</p></div>"
}
Example
{
"html_area": "<h1>A heading</h1><p>A paragraph</p>"
}
With Liquid
<div class="html-text">{{ settings.md_area }}</div>
Output
<div class="html-text"><h1>A heading</h1><p>A paragraph</p></div>
Supported content
Most HTML tags are supported, but some tags such as <html>
, <head>
, and <body>
will be automatically removed.
Article
You can use article
settings to reference articles in a Shopify store. Articles function in much the same way as page
or product
settings, in that they return the handle for the referenced object which can be retrieved with a global variable (in this case, articles
).
For example:
Input
{
"type": "article",
"id": "featured_article",
"label": "Article to feature on the home page"
}
Example
{
"featured_article": "news/building-shopify-themes"
}
With Liquid
{% assign article = articles[settings.featured_article] %}
{% if article %}
<a href="{{ article.url }}">{{ article.title }}</a>
{% endif %}
Output
Image
Merchants can use a setting of type image_picker
to upload assets such as logo images, favicons, and slideshow images.
Input
{
"name": "Logo",
"settings": [
{
"type": "image_picker",
"id": "logo",
"label": "Logo image"
}
]
}
Output
Images uploaded through the theme editor are placed in an asset library and can then be re-used in other places and even other themes.
In Liquid, the value of image_picker
settings is either an image object (if an image has been selected and exists) or nil
(if an image has not been selected, or the image doesn't exist). A URL for the image can be generated using the img_url
filter. The image object also has built-in support for alt text.
Sidebar settings
The sidebar settings are not used for input elements and can't be configured by merchants. Use these settings to add organizational information to your sidebar so that merchants can easily find the input settings they require.
Attributes for sidebar settings definitions are shown in the table.
type |
Mandatory | Name for the group of settings to which this setting belongs ( header or paragraph) |
content |
Mandatory | Textual content |
info |
Optional | Additional information about the setting, if required. It will appear as a tooltip. Use tooltips sparingly. It's better to use informative setting names whenever you can. |
Header
Use settings of type header
to add a styled header into the sidebar for informational purposes.
Input
{
"type": "header",
"content": "text",
"info": "text"
}
Example
{
"type": "header",
"content": "Body Styles"
}
Output
Paragraph
Use settings of type paragraph
to add styled text into the sidebar for informational or explanatory purposes.
Input
{
"type": "paragraph",
"content": "text"
}
Example
{
"type": "paragraph",
"content": "All of your collections are listed by default. To customize your list, choose 'Selected' and add collections."
}
Output