Making a Theme Customizable with Settings

When creating a theme to sell, or even just one for a client, it's nice to be able to give the end user the ability to customize the store a little.

Shopify offers a simple yet extensive way to do this with the settings_schema.json file. Found in the config folder of your Shopify theme, this file allows you to use json objects to define options for the end user to pick from. You can see the options from the admin panel when you select online store > themes and click customize theme button on the top right hand side. Here there should be a right hand side panel showing you the customization options.

Settings File Format

In the settings_schema.json file, all the data is encolsed by [ ]. Within that, you can group related options together. Each group will have a name and then a group of settings defined in an array. So your file will start something like this:


		[
		   {
		   "name" : "Colors",
		   "settings" : [ ]
		   }
		]
	

Each option is then an object inside the settings array. Something like this:


		[
		   {
		    "name" : "Colors",
		    "settings" : [
			{
			   "type": "color",
			   "id": "color_borders",
			   "label": "Border Colors",
			   "default": "#e5e5e5",
			   "info" : "this will be the colors for borders"
		        },
			{
			   "type": "color",
			   "id": "color_body_text",
			   "label": "Body Text",
			   "default": "#2980b9"
			}
		      ]
		   }
		]
	

In the case above, on the sidebar for the customization settings you'll see a label "Colors". When you click on that, the options will slide in and you can choose from a color picker a new color for either "Border Colors" or "Body Text".

In the case below, the sidebar will have two labels "Colors" and "Logo". This allows you to group customizations into logical sections making it easier for the end user to find all the options.


               [
		   {
		    "name" : "Colors",
		    "settings" : [
			{
			   "type": "color",
			   "id": "color_borders",
			   "label": "Border Colors",
			   "default": "#e5e5e5",
			   "info" : "this will be the colors for borders"
		        },
			{
			   "type": "color",
			   "id": "color_body_text",
			   "label": "Body Text",
			   "default": "#2980b9"
			}
		      ]
		   },
                   {
                    "name": "Logo",
                    "settings": [
                        {
                           "type": "image",
                           "id": "logo.png",
                           "label": "Logo",
                           "max-width": 480,
                           "min-width": 200,
                           "info": "This is the logo for the store"
                        }
                     ]
                   }
		]

Settings Attributes

Each regular setting has 5 attributes : type, id, label, default, info

Type Requirement Description
type mandatory defines the type of input the option takes
id mandatory must be unique. It is how the settings are references in the theme.
label mandatory describes to the user what the option is for.
default optional to define a default value for the option.
info optional to provide additional info about the option to the end user.

Regular Setting Types

The following table describes regular input types allowed. The value of each is set in the type attribute

Value Explanation
text Allows the user to input a single line text field
textarea Allows the user to input multi line text
image Allows the user to upload images
radio Allows the user to select from radio buttons
select Allows the user to select from a drop-down
checkbox Allows the user to check a box return a true or false value

Image type

It is noteworthy that images uploaded this way will be saved in the themes Assets folder. The file will be saved with the name and format that is defined in the id. So even if the image is a .jpg file, and the id is 'logo.png', the image will now be saved as a .png file.

Radio and Select types

Because radio and select types have multiple values to choose from, the settings definition will also require an options attribute. This will take an array of objects with a value and label each.


		{
		  "type":      "radio",
		  "id":        "id",
		  "label":     "Text",
		  "options": [
		    { "value": "one", "label": "Radio One" },
		    { "value": "two", "label": "Radio Two" }
		  ],
		  "default":   "one",
		  "info":      "Text"
		}
	

Specialized Setting Types

Specialized settings are defined the same way as regular settings. The difference is that these settings offer specialized and pre-selected info for the user to choose from. For example the product type is a dropdown but only allows the user to select from products already defined in the store.

Value Explanation
color Allows the user to choose a color with a color picker widget
font Allows the user to select from a list of fonts available
collection Allows the user to choose a product collection available in the store
product Allows the user to select a product available in the store
blog Allows the user to select from a list of blogs set up in the store
link_list Allows the user to select from available menus
page Allows the user to select a certain page defined in the store
snippets Allows the user to select a specific snippet available in the theme

Blog Type

in Blog posts section of your online store you can add blog posts. You also have the ability to add these blog posts (articles) to different blogs. The blogs setting dropdown allows you to choose which blog you'll be using for that setting.

Snippet Type

Snippets are defined in the theme and are found in the snippets folder. They are bits of code you would bring (possibly multiple times) into the templates. A common example of a snippet would be a product loop.

Warning

If you add settings in the Shopify admin and then later start using the settings_schema.json file ALL your admin settings will be wiped out and replaced by the files setting.

Informational Settings

Shopify also allows you to create purely informational settings to go into the sidebar (they refer to these as sidebar settings). The configuration is very similar to all the other settings, but they only have 3 attribute : type, content, info

Type Requirement Description
type mandatory defines the type of input the option takes. For sidebar settings this can only be either header or paragraph
content mandatory text content
info optional to provide additional info about the option to the end user.

Using These Settings in Theme Development

Great, now you can create settings that the store owner can choose from, but how do you incorporate the choices into your actual theme? That's the topic for the next post.