Configuring theme settings

You can use the settings_schema.json file to configure the theme 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 settings_schema.json

The settings_schema.json file is located in the config directory of a theme. It controls the organization and content of the menu in the theme editor.

settings_schema.json lists all settings that are available for your theme, grouped into sections. If you edit settings_schema.json, your changes must follow the specified file format.

If your theme has no settings_schema.json file

If a theme doesn't have a settings_schema.json file, you can:

• 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 settings_schema.json

You can edit your theme's settings_schema.json file from your Shopify admin.

1. From the file directory in the sidebar, open the Configs folder and click settings_schema.json.

   

2. When you've finished editing, click Save.

File format overview

The settings_schema.json file contains the definitions for your theme settings, grouped into sections according to the setting type.

The grouping of the settings in settings_schema.json is reflected in the theme editor.

There are two categories of theme 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 in settings_schema.json 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.

Extract from a settings_schema.json file:

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 settings_schema.json file is validated before being 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 in the settings_schema.json file, 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": "favicon_enable",
  "label": "Use custom favicon",
  "info": "Learn more about [favicons](https://en.wikipedia.org/wiki/Favicon)"
}

Input setting types

The settings_schema.json file 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": "Footer link list 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

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.

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": "icon_cart",
   "options": [
      { "value": "none", "label": "None"},
      { "value": "light", "label": "Light"},
      { "value": "dark", "label": "Dark"}
   ],
   "label": "Cart icon"
}

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": "products_per_page",
   "options": [
      { "value": "8", "label": "8 Products"},
      { "value": "12", "label": "12 Products"},
      { "value": "16", "label": "16 Products"}
   ],
   "label": "Products per page"
}

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": "collection_sort",
   "default": true,
   "label": "Enable sorting"
}

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 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 drop-down menu 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

Collections drop-down

Settings of type collection generate a drop-down that is automatically filled with the names of all the collections in the store. The output of the option the merchant selects from the drop-down is the handle of the collection.

Input

{
   "type":      "collection",
   "id":        "id",
   "label":     "Text",
   "info":      "Text"
}

Example

{
   "type": "collection",
   "id": "feature_collection",
   "label": "Feature collection"
}

Output

Products drop-down

Settings of type product generate a drop-down that is automatically filled with the names of all the products in the store. The output of the option the merchant selects from the drop-down is the handle of the product.

Input

{
   "type":      "product",
   "id":        "id",
   "label":     "Text",
   "info":      "Text"
}

Example

{
   "type": "product",
   "id": "feature_product",
   "label": "Feature product"
}

Output

Blogs drop-down

Settings of type blog generate a drop-down that is automatically filled with the names of all the blogs in the store. The output of the option the merchant selects from the drop-down 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

Pages drop-down

Settings of type page generate a drop-down that is automatically filled with the names of all pages in the store. The output of the option the merchant selects from the drop-down is the handle of the page.

Input

{
   "type":      "page",
   "id":        "id",
   "label":     "Text",
   "info":      "Text"
}

Example

{
   "type": "page",
   "id": "homepage",
   "label": "Front page"
}

Output

Link lists drop-down

Settings of type link_list generate a drop-down that is automatically filled with the names of all the menus in the store. The output of the option the merchant selects from the drop-down 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

<div class="rte"><p>Content for <em>richtext</em> <a href="https://example.com/">setting</a></p></div>

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

<a href="/news/building-shopify-themes">Building Shopify Themes</a>

Sidebar settings

The sidebar settings in settings_schema.json 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": "Thanks for buying my theme.  Please contact me at support@theme.com for support details."
}

Output