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

# Widgets

Plan: Stencil Developer

Lesson 17 of 23 · 30 min

[Widgets](/developer/api-reference/rest/admin/content/widgets/widget/get-widgets) are units of content placed on specific pages in a Stencil theme. Widgets consist of a widget configuration and a widget template UUID and render as part of the storefront's HTML. Once created, a widget can be placed and configured in Page Builder.

![Widgets overview](/_fern-files/_img/6213c067a374de96d043ba861b851d5017eee092d750ce7c38f386cc77559a9c.webp)

> **Info**
>
> There is a limit of 10,000 widgets per store.

For the endpoints used to create, retrieve, update, and delete widgets, see the [Widgets API reference](/developer/api-reference/rest/admin/content/widgets).

## Widget Configuration

A widget configuration is the JSON payload that defines the content you can render with a given widget template. Recall the Static Image + Content widget template you built in Module 4, which defines `heading_text`, `image`, `width`, and `text_block` settings in its schema, and references them in its markup using Handlebars expressions such as *\{\{heading_text}}* and *\{\{image.src}}*.

In the following example, we supply values for each of those settings. Since you create the template separately from the configuration, you can use the same template UUID multiple times with different configurations.

```json showLineNumbers={false}
{
  "heading_text": "Welcome to Our Store",
  "image": {
    "src": "https://images.unsplash.com/photo-1523275335684-37898b6baf30",
    "type": "IMAGE_MANAGER"
  },
  "width": "400",
  "text_block": "Shop our new arrivals before they sell out."
}
```

```json showLineNumbers={false}
{
  "heading_text": "Free Shipping on Orders Over $50",
  "image": {
    "src": "https://images.unsplash.com/photo-1472851294608-062f824d29cc",
    "type": "IMAGE_MANAGER"
  },
  "width": "400",
  "text_block": "No code needed — the discount applies automatically at checkout."
}
```

## Reusing Widget Configuration

You can reuse a widget template's UUID to create multiple widgets, each with its own widget configuration. When reusing a widget template, the configuration's keys must exactly match the setting ids defined in the template's schema — such as `heading_text`, `image`, `width`, and `text_block` from the Static Image + Content template. Otherwise, you will create the widget, but the mismatched value will have no data and nothing will display for it.

In the following example, the configuration uses `heading_txt` instead of `heading_text`. Because the key doesn't match the schema setting id exactly, the heading will not render, even though the request succeeds.

```json showLineNumbers={false}
{
  "name": "Mismatched Widget",
  "widget_configuration": {
    "heading_txt": "This heading will not appear",
    "width": "400",
    "text_block": "This text will still appear."
  },
  "widget_template_uuid": "7bfb9a46-75cc-45bc-bf39-a6a43b77111f"
}
```

Below, the configuration correctly uses `heading_text`, matching the schema setting id, so the heading renders as expected.

```json showLineNumbers={false}
{
  "name": "Correct Widget",
  "widget_configuration": {
    "heading_text": "This heading will appear",
    "width": "400",
    "text_block": "This text will still appear."
  },
  "widget_template_uuid": "7bfb9a46-75cc-45bc-bf39-a6a43b77111f"
}
```

## Widget Versioning

Widget versioning allows developers to release updates to widget templates without impacting existing widgets created using those templates.

A single widget template can have multiple versions, each with its own *template* and *schema* properties. The widget template's `current_version_uuid` property points to the most recent version of the widget template. When you create a widget, it automatically uses the most current version of the widget template and saves it as the `version_uuid` property.

To update a widget template without impacting existing widgets, set the `create_new_version` property to *true* when sending a *PUT* request to [*/v3/content/widget-templates/\{uuid}*](/developer/api-reference/rest/admin/content/widgets/widget-template/update-widget-template). This will create a new widget template version, but it will not impact the widgets created before the update.

Updating the widget template with `create_new_version` set to *true* will change the value of the `current_version_uuid` in the widget and the widget template, but it will not change the value of the widget's `version_uuid`.

> **Info**
>
> It is possible to update your widget template without creating a new version. To do so, exclude the create_new_version field or set it to false when making a PUT request to [**update the widget template**](/developer/api-reference/rest/admin/content/widgets/widget-template/update-widget-template).