> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Elements

Theme settings element types used in `schema.json` to configure the Theme Editor UI.

## checkbox

Used to toggle on theme settings (boolean value).

**`checkbox: theme settings`**

```json title="checkbox: theme settings" showLineNumbers={false}
{
  "type": "checkbox",
  "label": "i18n.HideBreadcrumbs",
  "force_reload": true,
  "id": "hide_breadcrumbs"
},
```

Required fields: `type`, `label`, and `id`.

Optional field: `force_reload`.

![Theme styles checkbox](/_fern-img/865226633c4192e5fce29e6fb2d1b20ba8d79c4863c0c799a81ff87b0bbf1d64.webp)

## color

Used to set color value on theme setting (hex value).

**`color: theme settings`**

```json title="color: theme settings" showLineNumbers={false}
{
  "type": "color",
  "label": "i18n.BannerBackground",
  "id": "color-primary"
},
```

Required fields: `type`, `label`, and `id`.

![Theme styles color](/_fern-img/dc0b99825465144175844ff8fa1656dcd23bccae089f8a5f15649f185a5c689f.webp)

## font

Used to select font value on theme setting.

**`font: theme settings`**

```json title="font: theme settings" showLineNumbers={false}
{
	"type": "font",
	"label": "i18n.BodyTextFontFamily",
	"id": "body-font",
	"options": [
		{
			"group": "i18n.Karla",
			"label": "i18n.Karla",
			"value": "Google_Karla_400"
		},
		{
			"group": "i18n.Roboto",
			"label": "i18n.Roboto",
			"value": "Google_Roboto_400"
		},
		{
			"group": "i18n.SourceSansPro",
			"label": "i18n.SourceSansPro",
			"value": "Google_Source+Sans+Pro_400"
		}
	]
}
```

Required fields: `type`, `label`, `id`, and `options`.

Optional field: `force_reload`.

![Theme styles font](/_fern-img/ece5997b7784dbb39242fd9830e0d83e279b6e2b60d548898337f4a3daadadac.webp)

## heading

**`heading`**

```json title="heading" showLineNumbers={false}
{
  "type": "heading",
  "content": "i18n.BackgroundAndLines"
},
```

Required fields: `type` and `content`.

![Theme style heading](/_fern-img/25b9da128c2586e7f69561cf73415364415cfef98f21eebd6baded01a0b18205.webp)

## imageDimension

Used to set image ratio on theme setting.

**`imageDimension`**

```json title="imageDimension" showLineNumbers={false}
{
  "type": "imageDimension",
  "id": "blog_size",
  "force_reload": true,
  "label": "i18n.SizeOfImages",
  "options": [
    {
      "value": "190x250",
      "label": "i18n.OptimizedForTheme"
    },
    {
      "value": "custom",
      "label": "i18n.SpecifyDimensions"
    }
  ]
},
```

Required fields: `type`, `label`, `id`, and `options`.

> **Note**
>
> "custom" value option will allow users to specify the width/height. Else, use
> values set by the theme developer. An example image follows

![Theme styles image dimension](/_fern-img/754773934ba74fb1e1de55151fb1e8dfb9239c43c7ae78aa8e05591d2ddabb1b.webp)

## optimizedCheckout-image

Upload a custom logo to checkout when using optimized one-page checkout.

**`optimizedCheckout-image`**

```json title="optimizedCheckout-image" showLineNumbers={false}
{
  "type": "optimizedCheckout-image",
  "label": "i18n.250X100pxRecommended",
  "reference": "optimizedCheckout-show-logo",
  "reference_default": "none",
  "force_reload": true,
  "id": "optimizedCheckout-logo"
},
```

## reference

The reference field on a setting can show additional settings based on the value of another setting. For example, we may want to hide the `Product Sale Badge Label` setting if `Show product sale badges` setting equals none.

**`ShowProductSaleBadges setting`**

```json title="ShowProductSaleBadges setting" showLineNumbers={false}
{
  "type": "select",
  "label": "i18n.ShowProductSaleBadges",
  "id": "product_sale_badges",
  "force_reload": true,
  "options": [
    {
      "value": "none",
      "label": "i18n.None"
    },
    {
      "value": "topleft",
      "label": "i18n.TopLeft"
    },
    {
      "value": "sash",
      "label": "i18n.Diagonal"
    },
    {
      "value": "burst",
      "label": "i18n.Burst"
    }
  ]
},
```



**`ProductSaleBadgeLabel setting`**

```json title="ProductSaleBadgeLabel setting" showLineNumbers={false}
{
  "type": "text",
  "label": "i18n.ProductSaleBadgeLabel",
  "force_reload": true,
  "id": "pdp_sale_badge_label",
  "reference": "product_sale_badges",
  "reference_default": "none"
},
```

In this example, you can see that when `ShowProductSaleBadges` equals none, the `ProductSaleBadgeLabel` text setting is hidden. But when `ShowProductSaleBadges` has a value other than none, `ProductSaleBadgeLabel` text setting displays.

The `reference` field is added to the setting you want to toggle the display of based on a value (so in this example `ProductSaleBadgeLabel`). The value for `reference` should be the `id` of whichever setting you are referencing (so in this example `product_sale_badges`).

The `reference_default` field should be set to the value the setting wants to reference. In this case, `none` will set the `ProductSaleBadgeLabel` hidden until `ShowProductSaleBadges` changes in value.

![Theme styles reference](/_fern-img/4fe9d72147b13e91436af341fe23b08bcb01bb7dd04d2662d25ecd21ef2ed844.webp)

## select

Used to select custom value on theme settings.

> **Note**
>
> Option types should all be the same (i.e., string, number, etc.).

**`select: add option type`**

```json title="select: add option type" showLineNumbers={false}
{
  "type": "select",
  "label": "i18n.BodyTextFontSize",
  "id": "fontSize-root",
  "options": [
    {
      "value": 12,
      "label": "12px"
    },
    {
      "value": 13,
      "label": "13px"
    },
    {
      "value": 14,
      "label": "14px"
    },
    {
      "value": 16,
      "label": "16px"
    }
  ]
},
```

Required fields: `type`, `label`, `id`, and `options`.

Optional field: `force_reload`.

![Theme styles select](/_fern-img/0e74637cece4654ca414e2865fdbab3ac7ce8c1985b27276c6033f1ed8c39da4.webp)

## text

Used to set string value for theme settings.

**`text: set string value`**

```json title="text: set string value" showLineNumbers={false}
{
  "type": "text",
  "label": "i18n.ProductPriceLabelSale",
  "force_reload": true,
  "id": "pdp-sale-price-label"
},
```

Required fields: `type`, `label`, and `id`.

Optional field: `force_reload`.

![Theme styles text](/_fern-img/3f6fb704da236ba71b2f2faa0f6ced59c907fb62e8d53c4b04d1d92e2970c132.webp)