Anatomy of a Theme

If you have any questions, please send us a message.

Every Theme is made up of many Assets and each Asset is one of many types:

  • layout
  • stylesheet
  • javascript
  • template
  • snippet
  • config


Every Theme must have a default.html layout. A layout contains the main structure of your site and store. This includes things like your html, head and body tags.

An example of a layout is:

<!DOCTYPE html>
<html lang="en">
    <meta charset="utf-8">
    <title>{{ }}</title>
    {{ content }}

Note that {{ content }} is where the template gets rendered within the layout.


Every Theme must have a default.css stylesheet. A stylesheet contains a Theme's css.

A stylesheet can be rendered like:

{{ 'default.css' | asset_url | stylesheet_tag: 'screen' }}

Which would produce a custom link tag like:

<link href="/asset/default-c6324.css" media="screen" rel="stylesheet" type="text/css"/>


Every Theme must have a default.js javascript. A javascript contains a Theme's javascript.

A javascript can be rendered like:

{{ 'default.js' | asset_url | script_tag }}

Which would produce a custom script tag like:

<script src="/asset/default-39e50.js" type="text/javascript"></script>


Every Theme has many templates. A template is rendered within a layout and usually lines up with a specific page. For example, the product.html template is rendered on product pages.

Default templates include:

  • index.html
  • category.html
  • product.html
  • order.html
  • maintenance.html
  • 404.html

There are also specialty templates for Apps, including:

  • news.html
  • news-item.html
  • history.html
  • gallery.html
  • contact.html


Snippets are optional and can be used to repeat blocks of a template from multiple areas.

An example is a sidebar.html snippet that is rendered within some, but not all, templates.

A snippet is rendered with include, like a {% tag %}, such as:

{% include 'sidebar.html' %}


Every Theme must have a default.json config. A config is a json formatted document and includes Theme details such as the author, images for the Theme Gallery as well as setting definitions.

An example of a default.json config is as follows:

  "name": "Classic",
  "description": "The classic theme for Limited Run.",
  "author": {
    "name": "Limited Run",
    "website": ""
  "images": [
      "thumbnail": "http://.../classic-1-thumb.png",
      "original": "http:/.../classic-1.png"
      "thumbnail": "http://.../classic-2-thumb.png",
      "original": "http://.../classic-2.png"
  "settings": {
    "background_image_url": {
      "format": "image",
      "label": "Background Image URL",
      "help": "Enter an image URL or choose an image file to upload.",
      "placeholder": "http://",
      "position": 0

Every default.json config can have many settings. Each setting requires the following things:

  • key - ex: "background_image_url"
  • format - Possible values include: "image", "color", "text", "boolean"
  • label - ex: "Background Image URL"
  • position - ex: 0, 1, 2, 3, etc.

Optional fields include:

  • default - a default value, such as #E5E5E5 for a color or true for a boolean
  • help - a further explanation
  • placeholder - an example value

All of the settings in a Theme are show in the "Options" area in the Storefront > Theme area of the Dashboard.

Each format shows a different input field in the "Options" area. The "color" format shows a color picker. The "image" format shows a text field (for an image url) with an adjacent "Upload Image" button. The "text" format shows a plain text field. The "boolean" format shows a checkbox.

To use an option's value in your theme, whether in your default.html, or your default.css, or any other theme asset, simply reference its key, like {{ config['background_image_url'] }}.