settings.html
Caution
The settings.html file has been deprecated in favour of the settings_schema.json. Settings.html does not support the live preview window of the upgraded Customize theme page.
The settings.html file is rendered on the Customize theme page of the Haravan Admin. The Customize theme page allows users to easily customize the look-and-feel of their shop without having to dive into the theme's HTML, CSS, or Liquid code.
The settings.html and settings_data.json files are found in the config folder of a theme. The latter file stores the settings that the user selected in settings.html in JSON format.

- The Settings Object
- Markup
- Input Types
- Special CSS Classes
- Customize theme page considerations
- Requirements for the Theme Store
The Settings Object
The values of the settings.html inputs can be accessed in your Liquid templates and stylesheets by appending the name attribute of the input to the settings
Liquid object. For example, you may have a text input in settings.html that looks like this:
<input type="text" name="sales_text" value="" />
The value of this text input can be output using the following format:
{{ settings.sales_text }}
The settings
object can be accessed in any of the Liquid templates in your theme. If you're looking to access settings
in a CSS file or a JavaScript file, you can do so by appending a .liquid
extension to their file names. For example, if you have a stylesheet named style.css, you would change it to style.css.liquid.
Markup
The settings.html file is validated before being saved to make sure it follows a few rules. You cannot use any Javascript and you can't define any custom CSS styles. It is also run through an XML parser to make sure it's a valid XML fragment.
Input Types
settings.html accepts the following type of HTML inputs:
Single-line Text Fields
Useful for capturing short strings, such as URLs, social media usernames, and sales banner text. When using single-line inputs, be sure to include the value
attribute.
Input
<tr>
<th>
<label for="my_text">Single-line Text</label>
</th>
<td>
<input type="text" name="my_text" value="" />
</td>
</tr>
Multi-line Text Areas
Useful for capturing larger blocks of text, such as embed codes. When using multi-line inputs, be sure to include the value
attribute.
Input
<tr>
<th>
<label for="my_textarea">Name of this setting</label>
</th>
<td>
<textarea name="my_textarea" cols="60" rows="5" id="my_textarea" value="" />
</td>
</tr>
File upload
Useful for uploading assets to a theme, such as logo images, favicons, and slideshow images.
You can use the attributes data-max-width
and data-max-height
to define a maximum size for the image. Haravan will maintain the aspect ratio of the uploaded image while constraining it to those maximum dimensions.
Input
<tr>
<th>
<label for="my_file">File Upload</label>
</th>
<td>
<input type="file" name="logo.png" data-max-width="500" data-max-height="300" />
</td>
</tr>
Files uploaded through settings.html are placed in the theme's assets folder. The name of the saved file is not determined by the original file, but rather by the name
attribute of the file input tag. For example, the file uploaded through the example above would be saved as logo.png. Furthermore, Haravan will convert the image to the type specified in the name
attribute.
Radio button
Useful for presenting a limited amount of options to the user; for example, selecting the alignment of the logo.
Input
<tr>
<th>
<label for="my_radio">Radio Buttons</label>
</th>
<td>
<input type="radio" name="logo_option" value="1" /> Option 1
<input type="radio" name="logo_option" value="2" /> Option 2
</td>
</tr>
Select drop-down
Useful for presenting a large number of options to the user; for example, selecting the number of products to show on the product page.
Input
<tr>
<th><label for="my_dropdown">Select drop-down</label></th>
<td>
<select name="my_dropdown">
<option value="1" selected="selected">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
</select>
</td>
</tr>
Checkbox
Useful for toggling preferences on or off; for example, showing/hiding elements on a page.
The values of checkboxes are always forced to be 1
, and hidden fields are inserted by Haravan in the Customize theme page that is generated for each checkbox to allow for false
values to be submitted appropriately.
Input
<tr>
<th>
<label for="my_checkbox">Checkbox</label>
</th>
<td>
<input type="checkbox" name="my_checkbox" value="1" />
</td>
</tr>
Special CSS Classes
For some inputs, you can apply a CSS class to have it render a special Theme Setting with pre-populated values.
color
Applying the CSS class color
to an input of type text will generate a color picker once settings.html is rendered.
Input
<tr>
<th>
<label for="my_color">Color Picker</label>
</th>
<td>
<input type="text" name="my_color" class="color" value="" />
</td>
</tr>
font
Applying the CSS class font
to a select will generate a drop-down that is automatically filled with a list of web-safe fonts.
Input
<tr>
<th>
<label for="my_font">Font</label>
</th>
<td>
<select class="font" name="my_font" />
</td>
</tr>
collection
Applying the CSS class collection
to a select will generate a drop-down that is automatically filled with all of the collections in the shop. The output of the selected option is the handle of the collection.
Input
<tr>
<th>
<label for="my_collection">Collection</label>
</th>
<td>
<select class="collection" name="my_collection" />
</td>
</tr>
blog & page
Applying the CSS class blog
or page
to a select will generate a drop-down that is automatically filled with all of the blogs or pages in the shop. The output of the selected option is the handle of the blog or page.
Input
<tr>
<th>
<label for="my_blog">Blog</label>
</th>
<td>
<select class="blog" name="my_blog" />
</td>
</tr>
linklist
Applying the CSS class linklist
to a select will generate a drop-down that is automatically filled with all of the link lists in the shop. The output of the selected option is the handle of the link list.
Input
<tr>
<th>
<label for="my_linklist">Linklist</label>
</th>
<td>
<select class="linklist" name="my_linklist" />
</td>
</tr>
snippet
Applying the CSS class snippet
to a select will generate a drop-down that is automatically filled with all of the snippets in the shop. The output of the selected option is the name of the snippet, without the .liquid
extension.
Input
<tr>
<th>
<label for="my_snippet">Snippet</label>
</th>
<td>
<select class="snippet" name="my_snippet" />
</td>
</tr>
Customize theme page considerations
Handling "None" selections
A theme will rarely call on a hard-coded page, collection, or blog. Instead, they typically look at the theme's Customize theme page.
In other words, you would not see objects being loaded as follows:
{% for product in collections.frontpage.products %}
{% include 'product-grid-item' %}
{% endfor %}
Instead, you would load a page, collection, or blog selected through the settings
object:
{% for product in collections[settings.fp_collection].products %}
{% include 'product-grid-item' %}
{% endfor %}
Theme customizations with any of the special CSS classes will allow you to pick among existing published objects.
It is important to note that a Theme Setting can be set to None as well.
This does not return a string with the value None - instead, it returns an empty string in your theme's config/settings_data.json file:
"fp_page": "",
To determine if the Theme Setting for the page, blog, or collection is empty, compare your the appropriate settings
attribute to blank
as follows:
{% if settings.fp_page == blank %}
<!-- The merchant does not want to add a page here. His fp_page theme setting was set to None. -->
{% endif %}
An unless statement would work as well:
{% unless settings.fp_page == blank %}
{% assign page = pages[settings.fp_page] %}
<h1>{{ page.title }}</h1>
<div>{{ page.content }}</div>
{% endunless %}
The example below would not work, as empty strings are truthy in Liquid. If your settings.fp_page
is an empty string, then {% if settings.fp_page %}
will be true, resulting in empty elements on the page.
Input
{% if settings.fp_page %}
{% assign page = pages[settings.fp_page] %}
<h1>{{ page.title }}</h1>
<div>{{ page.content }}</div>
{% endif %}
Output
<h1></h1>
<div></div>
Handling non-existent settings
There may be cases where a Theme Setting is set to an object that used to exist, but was deleted or hidden. From a theme's point of view, a hidden resource is the same as one that doesn't exist.
For example, you may have a Theme Setting that is set to frontpage:
"fp_page": "frontpage",
After this is set, the frontpage page could be deleted or hidden by the user. You can account for this situation by performing two checks:
{% unless settings.fp_page == blank or pages[settings.fp_page].empty? %}
{% assign page = pages[settings.fp_page] %}
<h1>{{ page.title }}</h1>
<div>{{ page.content }}</div>
{% endunless %}
We first check if the Theme Setting is set to a value that is not blank, then check if it is still accessible in the shop.
Information
Themes will make assumptions about objects present in a shop when installed. All themes come with presets that are saved copies of Customize theme page's values. For example, a theme preset may assume that a shop has a page with handle frontpage and may have a fp_page setting set to frontpage.
This is not an unreasonable assumption to make as all new shops come with default content. However, good themes also check if the objects exists before trying to output their content.
Requirements for the Theme Store
If you're looking to submit your theme to the Theme Store, the settings.html 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)
- Include a setting for uploading a custom background image
- 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