Theme Settings

To allow users to customize 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 user's store.

You can use a range of form input types:

Text
Color
Select
Radio Buttons
Checkboxes
Range Sliders
Font Picker
File Uploads

Some additional properties of the settings.json are:

Fieldsets
Styles

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"
    }
}]
}

Theme Settings

Basics

Accessing values

Common Properties

Help properties

Text

Properties

Color

Properties

Select

Properties

Radios

Properties

Checkboxes

Properties

Font

Properties

Range

Properties

Upload

Properties

Validate Types

Fieldsets

Properties

Styles

Properties

Full Example

Contact Us