settings_schema.json

Use the settings_schema.json file to configure the theme settings that merchants can access using the Shopify Storefront Editor. A merchant accesses the editor by clicking Customize theme from the Themes page of their Shopify admin.

What is the settings_schema.json file?

The settings_schema.json is located in the config directory. It controls the organization and content of the Customize theme page's sidebar.

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

What if there's no settings_schema.json file in the config directory?

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

You should edit the file in accordance with its specified file format.

Automatic generation of settings_schema.json

If a theme has no settings_schema.json file, it can be generated automatically by either of the following actions:

  • opening the theme in the Template Editor
  • exporting the theme (from 2015 only).

The output settings_schema.json file is saved in the config directory.

Make sure you edit the file in accordance with the specified file format.

Generating settings_schema.json 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 other Shopify themes.

Edit the settings_schema.json file

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

  1. From your Shopify admin, click Online Store, then click Themes (or press G W T):

    Click Online Store then Themes

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

    Click Edit HTML CSS button

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

    Edit html screen 02

  4. When you've finished editing, click Save. The Customize theme page updates to reflect 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's sidebar.

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 number of 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:

type Mandatory Name of the type of settings.
id Mandatory 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 Mandatory A label for this setting.
default Optional A value to which the setting can default.
info Optional 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.

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

Information

"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 upload

A setting of type image is used for uploading assets to a theme, such as logo images, favicons, and slideshow images.

You can use the attributes max-width and max-height to define a maximum size for the image. Shopify will maintain the aspect ratio of the uploaded image while constraining it to those maximum dimensions.

Input

{
        "type":      "image",
        "id":        "logo.png",
        "label":     "Text",
        "max-width":  480,
        "max-height": 200,
        "info":      "Text"
},

Example

{
   "type": "image",
   "id": "shop_logo.png",
   "label": "Shop logo"
},

Output

Ts file upload

Images uploaded through the Customize theme page are placed in the theme's Assets folder. The file is saved with a name and format that matches the id attribute of the input tag, regardless of the file's original name or format.

For example, a JPG file of any name that was uploaded through the example above would be saved as logo.png.

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

In addition to 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
blog Blogs drop-down
page Pages drop-down
link_list Link lists drop-down
snippet Snippets drop-down

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.

Information

"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

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.

Information

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

Information

"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 of the link lists in the store. The output of the option the merchant selects from the drop-down is the handle of the link list.

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

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

Requirements for the Theme Store

If you're looking to submit your theme to the Theme Store, the settings_schema.json template of your theme must meet the following conditions:

  • Theme customizations on the Customize theme page should not be overwhelming or tedious
  • Must not include a setting to remove {{ powered_by_link }}
  • Logo upload must work with images of different aspect ratios (for example, landscape vs. portrait)
  • Logo image must be named logo.png
  • Include settings for social icons. Customers must be able to enter the URL of their social pages, and the URL must be applied to their respective icons
  • Settings to change fonts for headings and regular text
  • All type: 'image' settings must have an id that ends with .jpg, .png, .gif, or .ico
  • All settings must have a label
  • Must have theme_info section, logo is optional
Return to top

Ready to put what you've learned into action?

Build an online store with Shopify. Try it free.

Experience the future of retail now.

Shopify Point of Sale. Try it free.