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

config.json Metadata

config.json Overview

You configure the /theme‑name/config.json file to properly manage each of your custom theme’s front-end aspects. This config.json file’s functions are to:

  • Provide global context for Stencil’s CSS and Handlebars resources.
  • Provide values for the Theme Editor GUI to manage.
  • Provide metadata for your theme’s listing in the Theme Marketplace.
  • Define variations included in your theme.

Keys and Example Values

object
minProperties: 0
name
string

The theme name

example: Cornerstone
version
string

The theme’s version number

example: "2.6.0"
meta
object
price
integer
documentation_url
string
author_name
string
author_email
string
author_support_url
string
composed_image
string
features
array[string]
css_compiler
string
autoprefixer_cascade
boolean
autoprefixer_browsers
array[string]
settings
object
homepage_new_products_count
integer
homepage_featured_products_count
integer
homepage_top_products_count
integer
homepage_show_carousel
boolean
homepage_stretch_carousel_images
boolean
homepage_new_products_column_count
integer
homepage_featured_products_column_count
integer
homepage_top_products_column_count
integer
homepage_blog_posts_count
integer
productpage_videos_count
integer
productpage_reviews_count
integer
productpage_related_products_count
integer
productpage_similar_by_views_count
integer
categorypage_products_per_page
integer
shop_by_price_visibility
boolean
brandpage_products_per_page
integer
searchpage_products_per_page
integer
show_product_quick_view
boolean
show_powered_by
boolean
shop_by_brand_show_footer
boolean
show_copyright_footer
boolean
show_accept_amex
boolean
show_accept_discover
boolean
show_accept_mastercard
boolean
show_accept_paypal
boolean
show_accept_visa
boolean
show_product_details_tabs
boolean
show_product_reviews_tabs
boolean
show_product_weight
boolean
show_product_dimensions
boolean
product_list_display_mode
string
logo-position
string
logo_size
string
logo_fontSize
integer
logo-font
string
brand_size
string
gallery_size
string
productgallery_size
string
product_size
string
productview_thumb_size
string
productthumb_size
string
thumb_size
string
zoom_size
string
blog_size
string
default_image_brand
string
default_image_product
string
default_image_gift_certificate
string
body-font
string
headings-font
string
fontSize-root
integer
fontSize-h1
integer
fontSize-h2
integer
fontSize-h3
integer
fontSize-h4
integer
fontSize-h5
integer
fontSize-h6
integer
applePay-button
string
color-textBase
string
color-textBase--hover
string
color-textBase--active
string
color-textSecondary
string
color-textSecondary--hover
string
color-textSecondary--active
string
color-textLink
string
color-textLink--hover
string
color-textLink--active
string
color-textHeading
string
color-primary
string
color-primaryDark
string
color-primaryDarker
string
color-primaryLight
string
color-secondary
string
color-secondaryDark
string
color-secondaryDarker
string
color-error
string
color-errorLight
string
color-info
string
color-infoLight
string
color-success
string
color-successLight
string
color-warning
string
color-warningLight
string
color-black
string
color-white
string
color-whitesBase
string
color-grey
string
color-greyDarkest
string
color-greyDarker
string
color-greyDark
string
color-greyMedium
string
color-greyLight
string
color-greyLighter
string
color-greyLightest
string
button--default-color
string
button--default-colorHover
string
button--default-colorActive
string
button--default-borderColor
string
button--default-borderColorHover
string
button--default-borderColorActive
string
button--primary-color
string
button--primary-colorHover
string
button--primary-colorActive
string
button--primary-backgroundColor
string
button--primary-backgroundColorHover
string
button--primary-backgroundColorActive
string
button--disabled-color
string
button--disabled-backgroundColor
string
button--disabled-borderColor
string
icon-color
string
icon-color-hover
string
button--icon-svg-color
string
icon-ratingEmpty
string
icon-ratingFull
string
carousel-bgColor
string
carousel-title-color
string
carousel-description-color
string
carousel-dot-color
string
carousel-dot-color-active
string
carousel-dot-bgColor
string
carousel-arrow-color
string
carousel-arrow-bgColor
string
carousel-arrow-borderColor
string
card-title-color
string
card-title-color-hover
string
card-figcaption-button-background
string
card-figcaption-button-color
string
card--alternate-backgroundColor
string
card--alternate-borderColor
string
card--alternate-color--hover
string
form-label-font-color
string
input-font-color
string
input-border-color
string
input-border-color-active
string
input-bg-color
string
input-disabled-bg
string
select-bg-color
string
select-arrow-color
string
checkRadio-color
string
checkRadio-backgroundColor
string
checkRadio-borderColor
string
alert-backgroundColor
string
alert-color
string
alert-color-alt
string
storeName-color
string
body-bg
string
header-backgroundColor
string
footer-backgroundColor
string
navUser-color
string
navUser-color-hover
string
navUser-dropdown-backgroundColor
string
navUser-dropdown-borderColor
string
navUser-indicator-backgroundColor
string
navPages-color
string
navPages-color-hover
string
navPages-subMenu-backgroundColor
string
navPages-subMenu-separatorColor
string
dropdown--quickSearch-backgroundColor
string
dropdown--wishList-backgroundColor
string
blockquote-cite-font-color
string
container-border-global-color-base
string
container-fill-base
string
container-fill-dark
string
label-backgroundColor
string
label-color
string
overlay-backgroundColor
string
loadingOverlay-backgroundColor
string
pace-progress-backgroundColor
string
spinner-borderColor-dark
string
spinner-borderColor-light
string
hide_content_navigation
boolean
optimizedCheckout-header-backgroundColor
string
optimizedCheckout-show-backgroundImage
boolean
optimizedCheckout-backgroundImage
string
optimizedCheckout-backgroundImage-size
string
optimizedCheckout-show-logo
string
optimizedCheckout-logo
string
optimizedCheckout-logo-size
string
optimizedCheckout-logo-position
string
optimizedCheckout-headingPrimary-color
string
optimizedCheckout-headingPrimary-font
string
optimizedCheckout-headingSecondary-color
string
optimizedCheckout-headingSecondary-font
string
optimizedCheckout-body-backgroundColor
string
optimizedCheckout-colorFocus
string
optimizedCheckout-contentPrimary-color
string
optimizedCheckout-contentPrimary-font
string
optimizedCheckout-contentSecondary-color
string
optimizedCheckout-contentSecondary-font
string
optimizedCheckout-buttonPrimary-font
string
optimizedCheckout-buttonPrimary-color
string
optimizedCheckout-buttonPrimary-colorHover
string
optimizedCheckout-buttonPrimary-colorActive
string
optimizedCheckout-buttonPrimary-backgroundColor
string
optimizedCheckout-buttonPrimary-backgroundColorHover
string
optimizedCheckout-buttonPrimary-backgroundColorActive
string
optimizedCheckout-buttonPrimary-borderColor
string
optimizedCheckout-buttonPrimary-borderColorHover
string
optimizedCheckout-buttonPrimary-borderColorActive
string
optimizedCheckout-buttonPrimary-borderColorDisabled
string
optimizedCheckout-buttonPrimary-backgroundColorDisabled
string
optimizedCheckout-buttonPrimary-colorDisabled
string
optimizedCheckout-formChecklist-backgroundColor
string
optimizedCheckout-formChecklist-color
string
optimizedCheckout-formChecklist-borderColor
string
optimizedCheckout-formChecklist-backgroundColorSelected
string
optimizedCheckout-buttonSecondary-font
string
optimizedCheckout-buttonSecondary-color
string
optimizedCheckout-buttonSecondary-colorHover
string
optimizedCheckout-buttonSecondary-colorActive
string
optimizedCheckout-buttonSecondary-backgroundColor
string
optimizedCheckout-buttonSecondary-borderColor
string
optimizedCheckout-buttonSecondary-backgroundColorHover
string
optimizedCheckout-buttonSecondary-backgroundColorActive
string
optimizedCheckout-buttonSecondary-borderColorHover
string
optimizedCheckout-buttonSecondary-borderColorActive
string
optimizedCheckout-link-color
string
optimizedCheckout-link-font
string
optimizedCheckout-discountBanner-backgroundColor
string
optimizedCheckout-discountBanner-textColor
string
optimizedCheckout-discountBanner-iconColor
string
optimizedCheckout-orderSummary-backgroundColor
string
optimizedCheckout-orderSummary-borderColor
string
optimizedCheckout-step-backgroundColor
string
optimizedCheckout-step-textColor
string
optimizedCheckout-form-textColor
string
optimizedCheckout-formField-borderColor
string
optimizedCheckout-formField-textColor
string
optimizedCheckout-formField-shadowColor
string
optimizedCheckout-formField-placeholderColor
string
optimizedCheckout-formField-backgroundColor
string
optimizedCheckout-formField-errorColor
string
optimizedCheckout-formField-inputControlColor
string
optimizedCheckout-step-borderColor
string
optimizedCheckout-header-borderColor
string
optimizedCheckout-header-textColor
string
optimizedCheckout-loadingToaster-backgroundColor
string
optimizedCheckout-loadingToaster-textColor
string
optimizedCheckout-link-hoverColor
string
product_sale_badges
string
color_badge_product_sale_badges
string
color_text_product_sale_badges
string
color_hover_product_sale_badges
string
restrict_to_login
boolean
swatch_option_size
string
social_icon_placement_top
boolean
social_icon_placement_bottom
string
geotrust_ssl_common_name
string
geotrust_ssl_seal_size
string
navigation_design
string
price_ranges
boolean
pdp-price-label
string
pdp-sale-price-label
string
pdp-non-sale-price-label
string
pdp-retail-price-label
string
read_only_files
array[string]
resources
object
cart
boolean
bulk_discount_rates
boolean
shop_by_brand
object
variations
array[object]
name
string
id
string
meta
object
images
object
settings
object

Requirements and Restrictions

Your theme’s config.json file must meet the following requirements:

  • It must be named config.json, must reside in the root of your theme-name top level subdirectory (e.g.: /cornerstone/config.json or /stencil/config.json), and must be valid JSON.
  • The maximum allowable size for a theme’s config.json file is 64 KB. Exceeding this limit will trigger an error upon uploading the theme to BigCommerce.
  • Each key’s value is restricted to 64 characters. Exceeding this limit will similarly trigger an upload error.
  • Other than these size constraints, there is no limit on the number of keys and values that you can place in a theme’s config.json.

Carefully check your theme against all the requirements listed here – including the required keys within the meta object and variations array. While some requirements are not enforced in local development, they will be validated (and will trigger errors) when you later upload your theme to BigCommerce.

Required Themewide Keys

The config.json file must contain at least the following keys, with appropriate values (as outlined above):

*name

  • version
  • settings (which must itself be a valid JSON object)
  • variations (an array of at least one, and at most four, variation objects)
  • meta (an object; see specific requirements below)

Required meta Keys

The meta object must contain at least the following keys, with appropriate values:

  • price
  • author_name
  • author_email
  • author_support_url
  • documentation_url

For illustration, here is a commented excerpt:

{
  ...
  "meta": {
    "price": 15000, // in cents; non-negative integer, minimum 0
    "author_name:" "eCommerce Themes, Inc.", // Must be a string, not null
    "author_email": "support@example.com", // Must be a string, should be a valid email address, not null
    "author_support_url": "http://example.com/contactus", //  Must be a string, should be a valid URL, not null
    "documentation_url": "http://example.com/guide", // Must be a string, limit of 255 characters,
          not null
    "composed_image": "path/to/composed.png", // Must be a string path to the composed-image file
    "features": [ // Array of feature strings, all of which must be in the list enumerated here: 
          https://github.com/bigcommerce/theme-registry/blob/master/app/schemas/theme_config.json#L33
      "fully_responsive" // Must include at least one feature, and no duplicate entries
    ]
  },
  ...
}

Required variation Keys

For each variation that you choose to include in your theme (at least one is required), you must provide at least the following keys and sub-element, with appropriate values:

  • name
  • id
  • meta (an object, containing at least:)
  • description

For illustration, here is a redacted excerpt from Cornerstone:

"variations": [
    {
      "name": "Light",
      "id": "light",
      "meta": {
        "desktop_screenshot": "desktop_light.png",
        "mobile_screenshot": "mobile_light.png",
        "description": "Ideal for a wide range of businesses and brands, this design is fully responsive, simple, and ready for you to add your branding, logo, and products. ....",
    ...
    }
  ]

Video Demo