Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars Syntax and Helpers
Handlebars.js
Handlebars Helpers
Stencil Object Model
Stencil Objects

Managing Theme Variations

Creating and Naming a New Theme Variation (Cascading Settings from config.json)

You define variations in your <theme-name>/config.json file. From the default Stencil theme’s config.json, here is the Light variation’s definition, followed by the head of the Bold variation’s definition:

"variations": [
{
  "name": "Light",
  "id": "light",
  "meta": {
    "desktop_screenshot": "desktop_screenshot.jpg",
    "mobile_screenshot": "mobile_screenshot.png",
    "description": "This is the light style of the Stencil Theme",
    "demo_url": "https://stencil-light.mybigcommerce.com",
    "optimized_for": ["fashion", "image_heavy", "etc"],
    "industries": []
  },
{
  "name": "Bold",
  "id": "bold",
...

Try inserting a new custom variation of your own, below the "Light" block shown above. Your variation’s definition might look something like this:

"variations": [
...
{
  "name": "MyCustomVariation",
  "id": "my_custom_variation",
  "meta": {
    "desktop_screenshot": "my_custom_desktop_screenshot.jpg",
    "mobile_screenshot": "my_custom_mobile_screenshot.png",
    "description": "This is a really cool custom style of the Stencil Theme",
    "demo_url": "https://stencil-custom.mybigcommerce.com",
    "optimized_for": ["fashion", "image_heavy", "etc"],
    "industries": []
  },
{
  "name": "Bold",
  "id": "bold",
...
"variations": [
...
{
  "name": "MyCustomVariation",
  "id": "my_custom_variation",
  "meta": {
    "desktop_screenshot": "my_custom_desktop_screenshot.jpg",
    "mobile_screenshot": "my_custom_mobile_screenshot.png",
    "description": "This is a really cool custom style of the Stencil Theme",
    "demo_url": "https://stencil-custom.mybigcommerce.com",
    "optimized_for": ["fashion", "image_heavy", "etc"],
    "industries": []
  },
{
  "name": "Bold",
  "id": "bold",
...

Changing a Theme Variation’s Font Family (config.json)

To learn more about defining variations, see the config.json reference for details about each key’s usage and allowable values. In particular, note the option to configure settings and variables that are scoped to each variation. For example, you could insert the "settings":...”body-font-family” block shown below, to set body text throughout this variation (only) to a specific typeface/family:

{
  "name": "MyCustomVariation",
  "id": "my_custom_variation",
  "settings": {
    ...
    "body-font-family": "MyCoolFont, AnotherFont, sans-serif",
    ...
  }
}

Preparing a Variation’s Thumbnails

For details on preparing screenshots that enable merchants to preview each variation – and to preview your theme as a whole – in the BigCommerce control panel and Theme Marketplace, see Preparing Thumbnail Images.

Using Stencil CLI to Change Variations

To locally test/debug a specific variation of your theme, launch it by invoking the Stencil CLI’s (command-line interface’s) stencil start -v switch. Depending on how you’ve named your variation in config.json, you would type something like this on the command line:

stencil start -v MyCustomVariation

Bundling and Uploading Your Theme

If at this stage you are ready to bundle and upload your theme, refer to Bundling and Uploading a Theme.