Theme Settings

To allow users to customise your theme without any knowledge of HTML or CSS, you can create a settings form using settings.json within the settings folder in your theme. The form will be rendered within their store manager toolbar, which appears in the users store.

You can use a range of form input types:

Some additional properties of the settings.json are:

TL;DR head straight for the Full Example and work it out.

Basics

The settings.json should contain an array of settings objects for the data you wish to capture. Here’s the bare shell of a settings.json file:

{ "settings": [
... settings objects ...
]}

Each settings object has a set of properties which differ slightly per input type.

Accessing values

To access the user setting value in your theme, use the input name as follows {{ settings.example_name }} where example_name is the name property of your input.

If the input has multiple values, you can use code similar to below:

<!-- Split the value by comma -->
{% assign values = settings.example_name | split: ',' %}

<!-- If "example_value" is present... -->
{% if values contains "example_value" %}
... something ...
{% endif %}

<!-- If there's more than 2 values -->
{% if values.size > 2 %}
... something ...
{% endif %}

Common Properties

These properties are common to all the settings objects.

Name Required? Description
name Required A unique identifier for that input and is used to access that setting’s value within your theme.
group Optional Reference to a fieldset id to group settings together in an accordion style UI
label Required A description of the input (e.g. Text color).
type Required The type of input. More details on this below.
value Optional The default value for the input. If the user clears their value in the store manager and saves, it’ll roll back this value. For input types that can have multiple values, these should be comma separated.
help Optional This an object that can contain the two properties described in the help properties table below.

Help properties

These properties are nested in the help property above.

Name Required? Description
label Optional Help text that will appear under the label and could be used to help describe the input in more detail.
label Optional Help text that will appear under the input itself and is related to the data expected in the input.

Text

The text type is the most basic and allows you to capture raw text from the user.

{ 
    "name": "example_text", 
    "group": "examples",
    "label": "Text", 
    "type": "text", 
    "value": "Hello world",
    "placeholder": "e.g. Hello world",
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for text inputs.

Name Required? Description
placeholder Optional The placeholder text for the input, useful for examples such as the classic “e.g. Hello world”

Color

The color type allows you to capture a hex color code from the user.

{ 
    "name": "example_color", 
    "group": "examples",
    "label": "Color", 
    "type": "color", 
    "value": "#000000",
    "placeholder": "#......",
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

If you don’t want hex, you can use LESS or SCSS in your theme to convert to RGBA:

@color: {{ settings.example_color }};
color: rgba(red(@color), green(@color), blue(@color), .5);

If HSL is your thing, you can do similar:

@color: {{ settings.example_color }};
color: hsl(hue(@color), saturation(@color), lightness(@color));

Obviously if you use SCSS, use $ instead of @ as the variable prefix.

Properties

Extra properties for color inputs.

Name Required? Description
placeholder Optional The placeholder text for the color, useful for displaying the default color like “#000000”

Select

The select type allows you to capture one value out of a range of options, from the user.

{ 
    "name": "example_select", 
    "group": "examples",
    "label": "Select", 
    "type": "select", 
    "value": "1",
    "options": [{
        "label": "Option 1",
        "value": "1"
    },
    {
        "label": "Option 2",
        "value": "2"
    },
    {
        "label": "Option 3",
        "value": "3"
    }],
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for select inputs.

Name Required? Description
options Required The options available for selection. This is an array of objects containing label and value properties.

Radios

The radio type allows you to capture one value out of a range of options, from the user. Similar to the select type above but instead all options are visible. This is suitable for up to 5 options but above that and it’s better to use a select type in our opinion.

{ 
    "name": "example_radio", 
    "group": "examples",
    "label": "Radios", 
    "type": "radio", 
    "value": 1,
    "options": [{
        "label": "Option 1",
        "id": "example_radio_option_1",
        "value": 1
    },
    {
        "label": "Option 2",
        "id": "example_radio_option_2",
        "value": 2
    },
    {
        "label": "Option 3",
        "id": "example_radio_option_3",
        "value": 3
    }],
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for radio inputs.

Name Required? Description
options Required The options available for selection. This is an array of objects containing label, id and value properties. The id must be unique.

Checkboxes

The checkbox type allows you to capture multiple value out of a range of options, from the user. The value property can contain multiple (comma separated) values.

{ 
    "name": "example_checkboxes", 
    "group": "examples",
    "label": "Checkboxes", 
    "type": "checkbox", 
    "value": "1,2",
    "options": [{
        "label": "Option 1",
        "id": "example_checkboxes_option_1",
        "value": 1
    },
    {
        "label": "Option 2",
        "id": "example_checkboxes_option_2",
        "value": 2
    },
    {
        "label": "Option 3",
        "id": "example_checkboxes_option_3",
        "value": 3
    }],
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for checkbox inputs.

Name Required? Description
options Required The options available for selection. This is an array of objects containing label, id and value properties. The id must be unique.

Font

The font type allows you to capture a font selection from the user. Currently we only support Google webfont but we will be adding Adobe Typekit and other services.

{ 
    "name": "example_font",
    "group": "examples",
    "label": "Font", 
    "type": "font", 
    "system": true,
    "value": "Montserrat",
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for font pickers.

Name Required? Description
system Optional Allows the user to choose from System fonts also. Defaults to false.

Range

The range type allows you to capture one value out of a range and is rendered as a slider.

{ 
    "name": "example_range", 
    "group": "examples",
    "label": "Range", 
    "type": "range", 
    "value": 1,
    "min": 1,
    "max": 10,
    "step": 1,
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for range inputs.

Name Required? Description
min Optional The minimum value for the range. If not specified, the default is 0.
max Optional The maximum value for the range. If not specified, the default is 100.
min Optional The step value for the range. If not specified, the default is 1.

Upload

The upload type allows you to capture file uploads from the user. The value property can contain multiple (comma separated) values which should be absolute URLs.

{ 
    "name": "example_upload", 
    "group": "examples",
    "label": "Upload", 
    "type": "upload", 
    "multiple": true,
    "richUploader": true,
    "value": "http://example.com/path/to/image1.jpg,http://example.com/path/to/image2.jpg,http://example.com/path/to/image3.jpg",
    "text": {
        "new": "Select images",
        "change": "Add images",
        "delete": "Delete"
    },
    "validate": "image",
    "resize": {
        "enabled": true,
        "maxWidth": 800,
        "maxHeight": 800
    },
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}

Properties

Extra properties for uploads.

Name Required? Description
text Required The labels for the file upload buttons. This is an array of objects containing new, change and delete properties. The new value is used when a file is not selected, the change is for when a file has been selected and delete is displayed in a tooltip on button to remove it from the selection.
multiple Optional Allow the user to select and upload multiple files.
richUploader Optional Allows the user to select from Stock Images (powered by Pexels.com) or upload their own. Defaults to true
validate Optional This is used to validate that the user is uploading the correct file type. The possible values are image, media and file. The default is file if not specified but this will mean the user can upload any type of file which could break your theme. More details about types is below.
resize Optional If the user uploads an image, it can be resized which will have performance benefits all round. The value of the resize property should be a nested object. To enable resizing, add an enabled property and set it to true. Then you can specify maxWidth and maxHeight properties. If you do not set maxWidth or maxHeight, images will be resized to 1000px wide, maintaining their original aspect ratio.

Validate Types

Here’s a list of the validate values and what they mean

Validate Allowed file types
image “jpg”, “jpeg”, “png”, “gif”
media “mpg”, “mpeg”, “mp4”, “m4v”, “ogg”, “mkv”, “webm”, “qt”, “mov”, “wmv”, “avi”, “mp3”, “wav”, “aac”, “m4a”, “wma”, “aiff”, “flac”, “ogg”, “ra”, “rm”
file Anything that’s secure

Fieldsets

The fieldsets property allows you to group settings together in an accordion type UI.

"fieldsets": [{
    "id":       "examples",
    "label":    "Examples",
    "default":  true
},
{
    "id":       "other",
    "label":    "Other"
}]

Properties

The fieldsets property is an array of objects with the following properties:

Name Required? Description
id Required This is the id you need to reference in your setting as the group value
label Required The label displayed for the fieldset.
default Optional Define if the fieldset should be open by default when a user first opens the store editor. Only one can be set to true. If no default is specified, the first fieldset will be open.

Styles

The styles property allows you to define presets – for example, letting users choose from different styles for a theme.

"styles": {
    "default": {
        "enabled": true,
        "label": "Default Style"
    },
    "example_preset": {
        "label": "Example Style",
        "preset": [{ 
            "name": "example_text", 
            "value": "Example preset"
        },
        { 
            "name": "example_color", 
            "value": "#ff0000"
        }]
    }
}

Properties

The styles property is an object where the key is the id for the style. You can specify the default style (your defaults in each setting will be used for this style) as an option with the following properties:

Name Required? Description
enabled Optional Whether to enable the display of the default option.
label Required The label displayed for the style.

To specify additional styles, use the id for your preset as the key and use the following properties:

Name Required? Description
label Required The label displayed for the style.
preset Required This is an array of objects with two properties: name and value. The name should match the name of setting you want to set and the value the desired value.

Full Example

Finally, here’s all of that put together in an example settings.json file.

{ 
"styles": {
    "default": {
        "enabled": true,
        "label": "Default Style"
    },
    "example_preset": {
        "label": "Example Style",
        "preset": [{ 
            "name": "example_text", 
            "value": "Example preset"
        },
        { 
            "name": "example_color", 
            "value": "#ff0000"
        }]
    }
},
"fieldsets": [{
    "id":       "examples",
    "label":    "Examples",
    "default":  true
},
{
    "id":       "other",
    "label":    "Other"
}],
"settings": [{ 
    "name": "example_text", 
    "group": "examples",
    "label": "Text", 
    "type": "text", 
    "value": "Hello world",
    "placeholder": "e.g. Hello world",
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}, 
{ 
    "name": "example_color", 
    "group": "examples",
    "label": "Color", 
    "type": "color", 
    "value": "#000000",
    "placeholder": "#......",
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
},
{ 
    "name": "example_select", 
    "group": "examples",
    "label": "Select", 
    "type": "select", 
    "value": "1",
    "options": [{
        "label": "Option 1",
        "value": "1"
    },
    {
        "label": "Option 2",
        "value": "2"
    },
    {
        "label": "Option 3",
        "value": "3"
    }],
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
},
{ 
    "name": "example_radio", 
    "group": "examples",
    "label": "Radios", 
    "type": "radio", 
    "value": 1,
    "options": [{
        "label": "Option 1",
        "id": "example_radio_option_1",
        "value": 1
    },
    {
        "label": "Option 2",
        "id": "example_radio_option_2",
        "value": 2
    },
    {
        "label": "Option 3",
        "id": "example_radio_option_3",
        "value": 3
    }],
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
},
{ 
    "name": "example_checkboxes", 
    "group": "examples",
    "label": "Checkboxes", 
    "type": "checkbox", 
    "value": "1,2",
    "options": [{
        "label": "Option 1",
        "id": "example_checkboxes_option_1",
        "value": 1
    },
    {
        "label": "Option 2",
        "id": "example_checkboxes_option_2",
        "value": 2
    },
    {
        "label": "Option 3",
        "id": "example_checkboxes_option_3",
        "value": 3
    }],
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
},
{ 
    "name": "example_font",
    "group": "examples",
    "label": "Font", 
    "type": "font", 
    "system": true,
    "value": "Montserrat",
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
},
{ 
    "name": "example_range", 
    "group": "examples",
    "label": "Range", 
    "type": "range", 
    "value": 1,
    "min": 1,
    "max": 10,
    "step": 1,
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
},
{ 
    "name": "example_upload", 
    "group": "examples",
    "label": "Upload", 
    "type": "upload", 
    "multiple": true,
    "richUploader": true,
    "value": "http://example.com/path/to/image1.jpg,http://example.com/path/to/image2.jpg,http://example.com/path/to/image3.jpg",
    "text": {
        "new": "Select images",
        "change": "Add images",
        "delete": "Delete"
    },
    "validate": "image",
    "resize": {
        "enabled": true,
        "maxWidth": 800,
        "maxHeight": 800
    },
    "help": {
        "label": "Example label help",
        "input": "Example input help"
    }
}]
}

Was this helpful?

4 1