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

Preparing Thumbnail Images

Where and How Merchants See Your Theme’s Thumbnail Images

A complete Stencil theme includes screenshots to show off the theme on cards that appear in two locations within the BigCommerce Control Panel:

  • Storefront > My Themes: Each individual card displays a themewide composite image, which is an image that contains combination of screenshots of the theme’s multiple variations. Storefront > Themes Marketplace: Each card displays one variation of your theme. The three variations of Cornerstone (Light, Warm, and Bold) are displayed across three separate cards.
How your theme will appear in the Control Panel and Theme Marketplace
Storefront > My Themes
Storefront > My Themes
Each card contains a themewide composite image, showing all the variations of the theme in each. In this image, we see 3 variations for the Cornerstone theme and 4 for the Showroom theme.

General Image Requirements

Below are details about:

  • how to size and save these images to stage them within your theme’s directory structure
  • how to reference the images in your config.json file.

All screenshots described below must meet the following specifications in order for the stencil bundle command to be able to process them:

  • Saved to a supported image file type: .jpg/.jpeg, .png, or .gif.
  • Be stored in your <theme‑name>/meta/ subdirectory.

Also note that all of these screenshots must be in portrait aspect ratio, with specific resolutions listed under Themewide Composite Image below.

Themewide Composite Image

The themewide composite image represents your theme in the Control Panel’s Storefront > My Themes area, which shows merchants their currently available themes (including any custom uploaded themes).

This file will normally be a mosaic of screenshots from multiple variations within your theme. It must meet the following requirements, beyond the general specifications above:

  • Resolution of 600 x 760 pixels (horizontal x vertical).
  • File size smaller than 2 MB.
  • Arbitrary filename prefix, referenced in your config.json file as the meta > composed_image key’s value.

Here is an example of a compliant file type and location:

<theme‑name>/meta/composed.png

Here is how you would reference this file within config.json:

{
  [...]
  "meta": {
    [...]
    "composed_image": "composed.png",	
    [...]
}

Variations: Desktop/Mobile Screenshots

Each variation within your theme must be represented by two additional screenshots if you want that variation to appear in the control panel > Storefront > Themes Marketplace area, which shows merchants the themes that are available for download.

Desktop Screenshot

The first screenshot, showing your theme on a desktop viewport, must meet the following requirements beyond the general specifications above: Resolution of 2048 x 2600 pixels (horizontal x vertical). File size smaller than 5 MB. Arbitrary filename prefix, referenced in your config.json file as the <variation-name> > meta > desktop_screenshot key’s value.

Mobile Screenshot

The second screenshot, showing your theme on a mobile viewport, must meet the following requirements beyond the general specifications above:

  • Resolution of 304 x 540 pixels (horizontal x vertical).
  • File size smaller than 1 MB.
  • Arbitrary filename prefix, referenced in your config.json file as the <variation-name> > meta > mobile_screenshot key’s value.

Here is an example showing two files of compliant types and location:

  • <theme‑name>/meta/desktop_bright.png
  • <theme‑name>/meta/mobile_bright.png

Here is how you would reference these files within config.json, for a variation named Bright:

 [...]
  "variations": [
    {
      "name": "Bright",
      "id": "bright",
      "meta": {
        "desktop_screenshot": "desktop_bright.png",
        "mobile_screenshot": "mobile_bright.jpg",
    [...]
    }
  ]