Preparing Thumbnail Images

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

  • StorefrontMy Themes: Each individual card displays a themewide composite image, which is an image that contains combination of screenshots of the theme’s multiple variations.
  • StorefrontThemes Marketplace: Each card displays one variation of your theme. The three variations of Cornerstone (Light, Warm, and Bold) are displayed across three separate cards.

Desktop View of My Themes

#### Desktop View of My Themes

Desktop View of Themes Marketplace

#### Desktop View of Themes Marketplace

Mobile View of Themes Marketplace

#### Mobile View of Themes Marketplace


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.
  • 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 StorefrontMy Themes, 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 object’s composed_image key 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:

config.json
Referencing composed.png
{
  [...]
  "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’s StorefrontThemes Marketplace, 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 variations object’s desktop_screenshot key 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 variations object’s mobile_screenshot key value.

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

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


Resources

Related Articles