From Shopify Wiki

To learn more about tweaking your theme settings in your shop, head over here: How do I change the look and feel of my shop? If you're a designer and want to add settings to the theme you're working on, keep on reading.

Introduction

Theme settings provide an easy way for any user to customize the look and feel of their shop without having to delve into HTML or CSS code. In order for a theme to be customizable in this way, a couple of things need to be put in place:

• A settings form built with standard HTML
• References to the settings object and its properties in your Liquid files.

The form is rendered at the top of the theme editor screen in your shop's admin panel. The name attributes of the various inputs in the form (aside from file uploads, explained below) are mapped directly to properties on the settings object in Liquid.

For example, if a user sets the value of a text field named "text_color" to "#303030", then this value could be used in any layout or template like so:

  <style>
    body {color: {{ settings.text_color }};}
  </style>

If a user has not yet saved any values through the form, then the defaults are used as defined in the form. This is done through a combination of the value or checked attributes for input tags, the selected attribute for option tags, and the text content of textarea tags.

The settings form

Requirements

The settings form is defined in settings.html, which resides in your theme's config folder. The file doesn't contain the whole form; Shopify takes care of the actual form tag and submit button. Shopify also manipulates the code a bit at render time to make it work well in the admin section.

The form is validated before being saved to make sure it follows a few rules. Most notably, you can't 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.

Available form inputs

You can use the following inputs in your form by using standard HTML:

• Single-line text fields *NOTE* Make sure the value attribute is present.

<tr>
  <th>
     <label for="my_text">Name of this setting</label>
  </th>
  <td>
     <input type="text" id="my_text" name="my_text" class="text" value="" />
  </td>
</tr>

• Multi-line text areas *NOTE* Make sure the value attribute is present.

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

• Drop-down menus

<tr>
  <th><label for="my_dropdown">Name of this Setting</label></th>
  <td>
    <select name="my_dropdown" id="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>

• Radio buttons
• Checkboxes

<tr>
  <th><label for="my_checkbox">Name of this Setting</label></th>
   <td><input type="checkbox" id="my_checkbox" name="my_checkbox" value="1" /></td>
 </tr>

• File uploads

<tr>
  <th><label for="my_img">Settings Name</label></th>
  <td>
    <input type="file" id="my_img" name="my_img.jpg"  data-max-width="100" data-max-height="200" />
  </td>
</tr>

Things to consider

Checkboxes

The values of checkboxes are always forced to be "1", and hidden fields are inserted by Shopify in the theme settings form that is generated for each checkbox to allow for "false" values to be submitted appropriately.

File uploads

File uploads always go to the theme's asset folder. The name of the saved file is not determined by the original name of the user's uploaded file, but rather is equal to the name attribute of the file input tag. For example, a file uploaded through this input would always be saved as a theme asset called logo.png:

<input type="file" name="logo.png" />

Furthermore, since the name has an image file extension, Shopify will try to convert the uploaded file to the appropriate format (PNG) before saving it. If a user tries to upload a file which Shopify cannot convert to PNG (such as an SWF file), they will get an error telling them so.

You can also specify a maximum height and width for an image upload and Shopify will resize it accordingly:

<input type="file" name="logo.png" data-max-height="200" data-max-width="700" />

Shopify will then maintain the aspect ratio of the uploaded image while constraining it to those maximum dimensions.

Special CSS classes you can use

color

Add the color class to a text field and Shopify will turn it into a dynamic javascript-driven color picker:

  <input name="text_color" class="color" type="text" value="#332211" />

font

The font class can be applied to a select tag to populate it with a standard list of web-safe CSS font family definitions for the user to select using concise and readable names:

  <select class="font" name="header_font" id="header_font">
    <option value="Georgia, Utopia, 'Times New Roman', Times, serif" selected="selected">Georgia</option>
  </select>

Shopify will try to intelligently merge any custom options you provide into the default ones.

collection

The collection class can be applied to a select tag to populate it with a list of the shop's product collections.

  <select class="collection" name="frontpage_collection" />

The collection handles become the option values, while the full collection names are used for the option labels. This means that you can access the selected collection in Liquid like so:

  {% for product in collections[settings.frontpage_collection].products %}
    <!-- show the product -->
  {% endfor %}

Note that it is the collection's handle which gets exposed to Liquid, not the collection itself. The handle is just a string which we're using as a key for the collections object, so settings.frontpage_collection.products would not return anything useful.

blog & page

The blog and page classes can be applied to select tags to populate them with lists of the shop's blogs or pages.

  <select class="blog" name="main_blog" />
  <select class="page" name="welcome_message" />

These work pretty much like the collection selectors:

  {% for article in blogs[settings.main_blog].articles %}
    <!-- show the article -->
  {% endfor %}

  {{ pages[settings.welcome_message].content }}

linklist

The linklist class can be applied to select tags to populate them with lists of the shop's link lists.

  <select class="linklist" name="sidebar_linklist" />

Works like the blog and page selectors:

  {% for link in linklists[settings.sidebar_linklist].links %}
    <li>{{ link.title | link_to: link.url }}</li>
  {% endfor %}

snippet

The snippet class can be applied to a select tag to populate it with a list of the current theme's snippets.

  <select class="snippet" name="sidebar_widget" />

The value exposed to liquid is the name of the snippet without the .liquid extension, so it is perfect for using directly in an include tag:

  {% include settings.sidebar_widget %}

Using the settings object in Liquid

The settings object is available to you in any .liquid files kept in your layout, templates, snippets, or assets folders. A .css.liquid file in assets is the ideal place to define user-specified styles. JavaScript files can use theme settings as well — for example to set the duration of a transition in an image slideshow.

For example, in main.css.liquid:

  body {
    color: {{ settings.text_color }};
    background-color: {{ settings.bg_color }};
  }

If you want to allow the user to easily switch between bundled style presets, one option is to present a drop-down menu with values corresponding to specialized stylesheets you have created in addition to your main stylesheet.

In your settings.html:

  <select name="color_scheme">
    <option value="ocean.css">Ocean</option>
    <option value="forest.css">Forest</option>
    <option value="solar.css">Solar</option>
  </select>

In your theme.liquid:

  {{ 'main.css' | asset_url | stylesheet_tag }}
  {{ settings.color_scheme | asset_url | stylesheet_tag }}

Another option for easily providing switchable style presets to users is to simply save each style as a Theme Settings Preset from the Theme Settings page.

On your Theme Settings page:

1. Fill out your Theme Settings for the style

2. Enable the check mark at the bottom of your Theme Settings "Save current settings as a preset"

3. Give your new Preset a name

4. Press "Apply Changes"

5. Repeat steps 1-4 for each style you wish to bundle with the theme. Remember there is a maximum of 4 presets allowed per theme in the ThemeStore.

Those presets will be stored in the settings_data.json file which will part of your theme files. Include the settings_data.json file in your uploaded theme. When someone installs your theme, this file will also be installed and users will then have your pre-built styles accessible from the Presets drop down in their Theme Settings.

Some other things to keep in mind:

• Any text fields with the color class will produce 6-digit hex codes prefixed with the pound (#) symbol, ready to use in your theme's CSS styles.
• Checkboxes always produce boolean true/false values which are most useful in if/else statements.

Linking to the theme settings

You can direct a shop-owner to his theme settings page in your theme setup instructions by using theme.id inside your .liquid template or snippet:

<p>Go to your <a href="/admin/themes/{{ theme.id }}/settings">theme settings</a> and...</p>

The variable theme represents the currently active theme, that is, the one which contains the template that's currently being rendered.

The above will work even when the theme you are looking at is not published — it will work all the time.

Say, you can't use Liquid where you are and you need to link to the published theme settings, then you can use /admin/themes/current/settings. And how about linking to the theme.liquid file? Use /admin/themes/current/#layout/theme.liquid.