settings_schema.json

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 theme 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 on the theme's Customize theme page.

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:

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 your Shopify admin, click Online Store, and then click Themes (or press G W T).

  2. Find the theme you want to edit, click the ... button, and then click Edit HTML/CSS.

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

    Settings schema json
  4. When you've finished editing, click Save. The Customize theme page updates with your changes.

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 Customize theme page menu.

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 Customize theme page's 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 Customize theme page's sidebar.

When defining input settings in the settings_schema.json file, 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 object. It must only contain alphanumeric characters, underscores, and dashes.
label yes A label for this setting.
default no A value to which the setting can default.
info no Additional information about the setting, if required. It will appear as a tooltip.
Use tooltips sparingly. It's better to use only informative labels whenever you can.

You can create links in labels using the pattern [link text](link URL). For example:

{
  "type": "checkbox",
  "id": "favicon_enable",
  "label": "Use [custom icon](https://en.wikipedia.org/wiki/Favicon)"
}
Settings schema link

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

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

Value Application
text Single-line text fields
textarea Multi-line text areas
image_picker Image uploads
radio Radio buttons
select Selection drop-downs
checkbox Checkboxes

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.

Tip

"type": "text" settings are not updated when switching presets.

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

Ts single line

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

Ts multi line

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

Image picker example

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

Ts radio

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 may 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

Ts dropdown

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 Customize theme page 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": "Display sort by?"
}

Output

Ts check

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 Font picker
collection Collections drop-down
product Products drop-down
blog Blogs drop-down
page Pages drop-down
link_list Link lists drop-down
snippet Snippets drop-down
url URL
video_url Video URL
richtext RichText
article Article

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

Ts color

Font picker

Settings of type font generate a drop-down that is automatically filled with a list of web-safe fonts.

Input

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

Example

{
   "type": "font",
   "id": "header_font",
   "label": "Header Font Face"
}

Output

Ts font

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.

Tip

"type": "collection" settings are not updated when switching presets.

Input

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

Example

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

Output

Ts collection

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.

Tip

"type": "product" settings are not updated when switching presets.

Input

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

Example

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

Output

Ts product

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.

Tip

"type": "blog" settings are not updated when switching presets.

Input

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

Example

{
   "type": "blog",
   "id": "sidebar_blog",
   "label": "Blog for Sidebar"
}

Output

Ts blog

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.

Tip

"type": "page" settings are not updated when switching presets.

Input

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

Example

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

Output

Ts pages

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.

Tip

"Link lists" are called "menus" in the Navigation page of the Shopify admin.

Input

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

Example

{
   "type": "link_list",
   "id": "main_nav",
   "label": "Main Navigation"
}

Output

Ts linklist

Snippets drop-down

Settings of type snippet generate a drop-down that is automatically filled with the names of all the snippets in the store. The output of the option the merchant selects from the drop-down is the name of the snippet, without the .liquid extension.

Input

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

Example

{
   "type": "snippet",
   "id": "left_footer",
   "label": "Leftmost Footer Content"
}

Output

Ts footer

URL

You can use url settings to reference shop resources including blogs, articles, collections, pages, products, and searches. URL settings update automatically if the handle for the referenced resource changes.

For example, if a merchant changes the handle of a product from leather-bag to red-leather-bag, a URL setting of shopify://products/leather-bag would change to shopify://products/red-leather-bag.

For example:

Input

{
  "type": "url",
  "id": "top_product",
  "label": "Link to our best selling product"
}

Example

{
  "top_product": "shopify://products/leather-bag"
}

With Liquid

<a href="{{ settings.top_product }}">View our most popular product</a>

Output

<a href="/products/leather-bag">View our most popular product</a>

Blogs and articles

shopify://blogs/<blog-handle>
shopify://blogs/<blog-handle>/<article-handle>

Collections

shopify://collections
shopify://collections/all
shopify://collections/<collection-handle>

# Using parameters
shopify://collections/all?foo=bar
shopify://collections/all#foo

Pages

shopify://pages/<page-handle>

Products

shopify://products/<product-handle>

Searches

shopify://search?q=<search>

# Using parameters
shopify://search?q=shoes&type=product%2Carticle%2Cpage

External URLs

http, https, mailto, and tel URLs will be returned exactly as they are entered:

http://example.com?foo=bar#qux
https://example.com?foo=bar#qux
mailto:user@example.com?subject=Hello%20world
tel:1234567890

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=LGb3j1CyH0k"
}

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.

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, and paragraphs.

For example:

Input

{
  "type": "richtext",
  "id": "column_richtext",
  "label": "Text",
  "default": "<p>Default <em>richtext</em> content</p>"
}

Example

{
  "column_richtext": "<p>Content for <strong>richtext</strong> setting</p>"
}

With Liquid

<div class="rte">{{ settings.column_text }}</div>

Output

<div class="rte"><p>Content for <em>richtext</em> setting</p></div>

Supported Content

Supported HTML tags: <p>, <br>, <strong>, <b>, <em>, <i>, <u>, <span>

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>

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>

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.

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

Ts bodystyles

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

Ts paragraph

Want to discuss this page?

Visit the Shopify Community