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 the config 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 the sections 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.

1. 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.

2. 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 colorin 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:

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
• specialized input setting types

Basic input setting types

You can set the type attribute for basic input settings to any of the values shown in the table below:

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 the step to 5, then the range slider will count by fives. By default, the step 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, and step values must be numbers. The numbers can be integers or floats.
• The min and max 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, or px 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

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.

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 are youtube or vimeo 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 be LGb3j1CyH0k.
• {{ settings.video_url.type }} — the site the video is hosted on. In the example above, this would be youtube.

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.

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.

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