Docs
Storefront
Widgets
Input configuration reference
UI settings

alignment

Allows you to display alignment controls for your widget. Depending on the use case, you are able to display horizontal, vertical, or both alignments simultaneously.

Widget Configuration Output

{
  "contentAlignment": {
    "horizontal": "center",
    "vertical": "middle"
  }
}

Depending on the alignment control type, certain values are possible:

Content alignment settingAllowed values
horizontal"left", "right", "center"
vertical"top", "bottom", "middle"

Widget Configuration Output"

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "alignment"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Image alignment"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "imageAlignment"

  • default    object

    The default value to use when rendering the widget for the first time.

  • typeMeta    object

    Additional information needed based on the selected setting type.

boolean

Allows you to display boolean controls for your widget. The control displays as a checkbox.

Widget Configuration Output

{
  "displayControls": true
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "boolean"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Display video controls"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "displayControls"

  • default    boolean

    The default value to use when rendering the widget for the first time.

    Default: true

box-model

Allows you to display box model controls for your widget.

Widget Configuration Output

{
  "productCardMargin": {
    "top": {
      "value": "0",
      "type": "px"
    },
    "right": {
      "value": "10.5",
      "type": "px"
    },
    "bottom": {
      "value": "0",
      "type": "px"
    },
    "left": {
      "value": "10.5",
      "type": "px"
    }
  }
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "boxModel"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Margin"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "productCardMargin"

  • default    object

    The default value to use when rendering the widget for the first time.

code

Allows you to display HTML editor controls for your widget.

Widget Configuration Output

{
  "html": "<div>html code can go here</div>"
}

User Interface Output

output

JSON Schema

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "htmlCode"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "HTML Code"

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: "<div>html code can go here</div>"

  • type    string

    The type of setting component to display.
    Example: "code"

  • typeMeta    object

    Additional information needed based on the selected setting type.

color

Allows you to display color controls for your widget.

Widget Configuration Output

{
  "backgroundColor": "#444444"
}

Note

  • The resulting color picker supports RGBA.
  • You can select transparent as a color. The returned value is the string “transparent”.

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "color"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Background color"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "backgroundColor"

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: "#444444"

element-settings

Element settings are a way of grouping together settings intended to modify one element of a widget, complete with the option to show or hide the element.

The controls attribute can contain the following optional objects:

AttributeDescription
visibilityDisplays an eyeball icon similar to the Visibility setting type
advancedDisplays a brush icon that reveals a list of settings when clicked

Widget Configuration Output

"textBox": {
  "visibility": "show",
  "backgroundColor": "#FFFFFF"
}

User Interface Output

output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "element"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Box"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "textBox"

  • typeMeta    object

    Additional information needed based on the selected setting type.

image-manager

Allows you to display image manager controls for your widget. All uploaded images go to the store’s Image Manager.

Widget Configuration Output

{
  "imageUrl": "https://images.unsplash.com/photo-1548768041"
}

Note

The “My Images” button allows the user to select from previously uploaded images.

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "imageManager"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "imageUrl"

  • default    object

input

Allows you to display input controls for your widget.

Widget Configuration Output

{
  "altText": "A cool grey shirt"
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: input

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Alt text"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "altText"

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: "A cool grey shirt"

number

Allows you to display number controls for your widget. The setting supports Both “integer” and “float” parse types.

Widget Configuration Output

{
  "fontSize": {
    "value": 24,
    "type": "px"
  }
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: number

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Font size"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "fontSize"

  • default    object

    The default value to use when rendering the widget for the first time.

  • typeMeta    object

    Additional information needed based on the selected setting type.

product-id

Allows you to display product search controls for your widget.

Widget Configuration Output

{
  "productId": "80"
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "productId"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: Product

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "productId"

  • typeMeta    object

    Additional information needed based on the selected setting type.

product-image

Allows you to display product image controls for your widget. The setting looks up product images based on the desired reference attribute.

Widget Configuration Output

{
  "src": "https://cdn11.bigcommerce.com/s-iu88q6epfh/products/121/images/377/850x850__74338.1591376249.386.513.png?c=1",
  "type": "PRODUCT_IMAGE"
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "productImage"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Product Image"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "productImage"

  • typeMeta    object

    Additional information needed based on the selected setting type.

range

Allows you to display input controls for your widget.

Widget Configuration Output

{
  "lineWidth": 100
}

Note

Units are not currently stored in the widget configuration.

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: "range"

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Line width"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "lineWidth"

  • default    integer

    The default value to use when rendering the widget for the first time.
    Example: 100

  • typeMeta    object

    Additional information needed based on the selected setting type.

regex-input

Allows you to display regex input controls for your widget. Regex setting can capture and provide conditional state to other schema settings.

Widget Configuration Output

{
  "videoUrl": {
    "value": "https://www.youtube.com/watch?v=-5EQIiabJvk",
    "parts": {
      "type":"youtube"
    }
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: regexInput

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Video URL (YouTube or Vimeo)"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: videoUrl

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: ""

  • typeMeta    object

    Additional information needed based on the selected setting type.

select

Allows you to display select controls for your widget.

Widget Configuration Output

{
  "imageHeight": "auto"
}

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: select

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: "Image height (px)"

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "imageHeight"

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: auto

  • typeMeta    object

    Additional information needed based on the selected setting type.

text

Allows you to display text box controls for your widget.

Widget Configuration Output

{
  "bodyText": "This is some text."
}

Note

New line characters are not supported.

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: text

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: Body text

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: bodyText

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: "This is some text."

typography

Typography allows users to select between either a default widget appearance or a custom appearance.

Widget Configuration Output

{
  "textStyle": "default"
}

Note

We recommend exposing custom typography settings via the conditionalSettings attribute when “custom” is selected.

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: typography

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: Text style

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: textStyle

  • default    string

    The default value to use when rendering the widget for the first time.
    Example: default

  • typeMeta    object

    Additional information needed based on the selected setting type.

visibility

Visibility allows the user to toggle between showing or hiding an element.

Widget Configuration Output

{
  "buttonVisibility": "show"
}

Output values are “show” or “hide”.

User Interface Output

output

JSON Schema

  • type    string

    The type of setting component to display.
    Example: visibility

  • label    string

    The user friendly message to inform the user how this setting will be used.
    Example: Button

  • id    string

    The variable name where the setting value will be available in the widget template.
    Example: "buttonVisibility"

  • default    string

    The default value to use when rendering the widget for the first time. Default values are "show or “hide”.
    Example: show
Did you find what you were looking for?
schema.jsonalignment