> 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.

# Widget UI Schema

This document outlines the different schema settings you can use in your custom widget template. For a tutorial on creating widget templates, see [Widgets Tutorial](/developer/docs/admin/widgets-and-scripts/guide).

## Tabs and sections

Within the `schema` property of the [Create a Widget Template](/developer/api-reference/rest/admin/content/widgets/widget-template/create-widget-template) endpoint, settings are grouped into `tabs` and `sections`.

### Tabs

Tabs are a part of the Page Builder schema structure. The schema requires using a single root-level `tab` to contain all visible sections.

> **Note**
>
> Sections render in the same order they are listed within a tab.

**`Tab schema example`**

```json title="Tab schema example" showLineNumbers={false}
[{
  "type": "tab",
  "label": "Content",
  "sections": [...]
}]
```

### Sections

Sections are groups of related settings. Each section will have a title that the user can collapse. Section labels are optional but are not collapsible without a label.

Settings render in the same order they are listed within a section.

**`Section schema example`**

```json title="Section schema example" showLineNumbers={false}
[{
  "type": "tab",
  "label": "Content",
  "sections": [
    {
      "label": "Text",
      "settings": [...]
    }
  ]
}]
```

## Array type

Arrays allow for building collections of elements within the widget. Array elements live at the top level of the schema. Each element in the array can contain an entire schema.

Elements in the list have settings defined by the array’s schema, which you can build using tabs, sections, and settings.

**`Array schema example`**

```json title="Array schema example" showLineNumbers={false}
{
  "type": "array",
  "label": "Carousel",
  "id": "slides",
  "defaultCount": 2,
  "entryLabel": "Slide",
  "thumbnail": {
    "type": "image",
    "valueKey": "imageUrl.src"
  },
  "schema": [
    {
      "type": "tab",
      "label": "Content",
      "sections": [
        {
          "label": "Text",
          "settings": []
        },
        {
          "type": "imageManager",
          "id": "imageUrl",
          "default": {
            "src": "https://example.com/example.png",
            "type": "IMAGE_MANAGER"
          }
        },
      ]
    }
  ]
}

```

> **Note**
>
> * Each element in the list can have tabs and sections included.
> * The `defaultCount` attribute is the number of elements that are displayed in the list by default.
> * Use the `thumbnail` attribute to display an image stored at the specified attribute name.
> * Use the `entryLabel` attribute to set a name for each element in the list.

## Hidden settings

You can use hidden settings to set up controls which have no user interface drawn in Page Builder. Hidden settings live at the schema's top level because they are not grouped into any other tabs or arrays. You can use them in advanced widgets with complex interactions in the preview pane, such as inline editing.

**`Hidden settings schema example`**

```json title="Hidden settings schema example" showLineNumbers={false}
{
  "type": "hidden",
  "settings": [
    {
      "id": "title",
      "default": "Sample title text"
    },
    {
      "id": "subtitle",
      "default": "Description text goes here"
    }
  ]
}
```

## Schema settings fields

The following table contains fields common between schema settings. For additional details, see the [Create a Widget Template](/developer/api-reference/rest/admin/content/widgets/widget-template/create-widget-template) endpoint.

| Setting       | Description                                                                                                                                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | The type of setting component to display. You can view the list of elements below to discover which are available to use.                                                                                                           |
| `label`       | The user-friendly message to inform the user how they can use this setting.                                                                                                                                                         |
| `id`          | The variable name where the setting value will be available in the widget template.                                                                                                                                                 |
| `default`     | The default value to use when rendering the widget for the first time.                                                                                                                                                              |
| `typeMeta`    | Additional information needed based on the selected setting type.                                                                                                                                                                   |
| `conditional` | An optional property that can be added to each setting to control whether it should be displayed to the user while editing in Page Builder. This does not clear the value in the setting, just controls the display of the setting. |

For examples of different schema settings you can use in your custom widget template, see [Widget UI Input Types](/developer/docs/admin/widgets-and-scripts/input-reference/schema).

## Resources

* [Widgets API](/developer/docs/admin/widgets-and-scripts)
* [Widgets Code Samples](/developer/docs/admin/widgets-and-scripts/examples)
* [Widget UI Input Types](/developer/docs/admin/widgets-and-scripts/input-reference/ui-settings/alignment)
* [Widgets Tutorial](/developer/docs/admin/widgets-and-scripts/guide)