Other theme files

If you're updating your theme to add enhanced support for the Customize theme page, you must modify your template, CSS, and JavaScript files to target the settings in settings_schema.json.

Targeting input values

To access the values of the settings_schema.json inputs in your Liquid templates and stylesheets, you must do both of the following:

Appending the id attribute to the settings object

To target the settings you've defined in settings_schema.json, you must add the id attribute of the appropriate settings input to each occurrence of the settings Liquid object.

For example, you might have a text input in settings_schema.json that looks like this:

  "type":      "text",
  "id":        "sales_text",
  "label":     "Your Company SubHeader",
  "default":   "Buy Now!",
  "info":      "Use this field to add a subheader to your shop",

The value of this text input can be output using the following format in your liquid templates:

{{ settings.sales_text }}

Amending filenames of CSS or JavaScript files

If your CSS or JavaScript files access the settings object, you must append a .liquid extension to their file names.

For example, if you have a stylesheet named style.css, change it to style.css.liquid.


Remember to also update the settings Liquid object in these files so that your inputs are targeted correctly.

Special-case user selections

You should be aware of some special cases for handling certain setting selections:

Handling the selection of the option "None"

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 %}

It is important to note that a Theme Setting can be set to None as well.

True false available none

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.


{% if settings.fp_page %}
  {% assign page = pages[settings.fp_page] %}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content }}</div>
{% endif %}



Handling the selection of non-existent or hidden settings

There might be cases where a Theme Setting is set to an object that used to exist, but has since been 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's set to frontpage:

"fp_page": "frontpage",

After this is set, the frontpage page could be deleted or hidden by the merchant. 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 %}

This first checks if the Theme Setting is set to a value that is not blank, then checks if it's still accessible in the store.


Themes will make assumptions about objects present in a store 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 store 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 stores come with default content. However, your theme should check that objects exist before trying to output their content.

Before text output

Before outputting text, check if the text is not empty:

{% unless settings.fp_heading == blank %}
<h1>{{ settings.fp_heading }}</h1>
{% endunless %}

If you want to force the use of text, you can specify default text like so:

<h1>{{ settings.fp_heading | default: 'Featured' }}</h1>

If settings.fp_heading is empty, the tag will return 'Featured' — and otherwise the value input in the theme's settings.

Before page content output

Before outputting a page's content, check that a page handle is provided, and that the page exists and is not empty:

{% unless settings.fp_page == blank or pages[settings.fp_page].empty? or pages[settings.fp_page].content == blank %}
{% assign page = pages[settings.fp_page] %}
<h1>{{ page.title }}</h1>
<div>{{ page.content }}</div>
{% endunless %}

As a reminder, empty? only tells us if a resource exists, it does not say if a page has content or not.

Before collection output

Before outputting products in a collection, check that a collection handle is given, and that the collection exists:

{% unless settings.fp_collection == blank or collections[settings.fp_collection].empty? %}
{% assign collection = collections[settings.fp_collection] %}
{% for product in collection.products %}
  {% include 'product-grid-item' %}
{% else %}
  <p>You have selected in your {{ 'Customize theme page' | link_to: '/admin/themes/current/settings' }} the collection {{ collection.title }} to be featured here, but that collection is empty! Go add some products to {{ 'your collection' | link_to: '/admin/collections' }}, or pick another collection.</p>
{% endfor %}
{% endunless %}

Want to discuss this page?

Visit the Shopify Community