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

# Lab - Using an Array in a Schema

Plan: Stencil Developer

Lesson 13 of 23 · 60 min

**Summary**

In the previous sections, you created widget template schemas with a single tab element. In this section, you will create a widget template that allows the content creator to select multiple products from the catalog, and display their product images in a grid. To allow the user to select multiple products, you will write a schema with an array containing multiple schemas, each with their own tab. In the end, you should be able to use Page Builder or Makeswift to create content that looks like this:

![Product grid widget](/_fern-files/_img/dd6be8bd6457491be76a1dbeb34e11f38f43120c12016e478636f009f20f2242.webp)

**In this lab you will**

* Write a widget template with an array of schemas, each including
  * a product ID input to select a product from the catalog
  * a product Image input to select a product image from the catalog
* Create a widget with the new widget template

**Prerequisites**

* BigCommerce store
* Stencil theme with at least one region
* BigCommerce API credentials
* Widget Builder installed and configured, with the blank `product-grid` template created, from Lab - Widget Builder Setup

## Create a Widget Template with an Array

In this lab, you will begin to build a product card grid. In more advanced applications, you could build on this template to create a functional "add all to cart" widget, but for now, the template is quite simple and only displays the product ID and a product image on each card. For an example of a more complex widget template utilizing arrays, look at the Carousel widget template available by default.

1. **Open** a terminal in your `~/widget-templates` directory. The `product-grid` directory you created in the previous lab contains `schema.json`, `config.json`, and `widget.html`.
2. If the live preview isn't already running, **start** it:

```shell showLineNumbers={false}
widget-builder start product-grid
```

The preview opens in your browser at `http://localhost:8080` and refreshes automatically each time you save a file.

## Write the Widget Template Schema

The widget template's schema defines the inputs a content creator can use to configure a widget. Widget templates use Handlebars to access the configured values to determine the content, markup, and styles to display. In this section, you will write an array of schemas containing:

* a product ID input to select a product from the catalog
* a product Image input to select a product image from the catalog

Throughout this section, you will edit the `schema.json` file in your `product-grid` directory. You may reference the completed [schema.json](https://github.com/bigcommerce-edu/lab-widget-templates/blob/main/product-grid/schema.json) to check your work.

1. **Open** `schema.json` in your text editor and **replace** its contents with an array containing a single array object:

```json showLineNumbers={false}
[
       {
           "type": "array",
           "label": "Products",
           "id": "products",
           "defaultCount": 3,
           "entryLabel": "Product",
           "schema": []
       }
   ]
```

2. **Add** a tab object with a type, label, and sections to the schema array.

```json showLineNumbers={false}
[
    {
        "type": "array",
        "label": "Products",
        "id": "products",
        "defaultCount": 3,
        "entryLabel": "Product",
        "schema": [
            {
                "type": "tab",
                "label": "Product Settings",
                "sections": []
            }
        ]
    }
]
```

3. **Add** a [section](/developer/docs/admin/widgets-and-scripts/guide) object with a label string and an empty settings array to the sections array.

```json showLineNumbers={false}
[
       {
           "type": "array",
           "label": "Products",
           "id": "products",
           "defaultCount": 3,
           "entryLabel": "Product",
           "schema": [
               {
                   "type": "tab",
                   "label": "Product Settings",
                   "sections": [
                       {
                           "label": "Configure the Product",
                           "settings": []
                       }
                   ]
               }
           ]
       }
   ]
```

4. In the settings array, **add** a Product ID setting. This setting's value will be used to populate other information about a product in the catalog, so the default text and the label should reflect that usage:

![Select product setting](/_fern-files/bigcommerce.docs.buildwithfern.com/488a92fbb0e23582bce36f02e8e70af09e223dcd7ad02cd67270459cb7b9b4a3/assets/learn/widgets-rest-api/selectProd.png)

Example:

```json showLineNumbers={false}
{
    "type": "productId",
    "label": "Select a Product",
    "id": "productId"
}
```

5. In the settings array, **add** a [Product Image](/developer/docs/admin/widgets-and-scripts/input-reference/ui-settings/product-image) setting. This setting is dependent on the productId defined by the previous setting, so the previous setting's id is referenced from the typeMeta of this setting. This setting's value will be used to populate the src attribute of an img tag in the template.

![Product image setting](/_fern-files/_img/01c9748be9e75194a1dc0e408948b4df435b28601a1d1f2310d8f1b89272c399.webp)

Example:

```json showLineNumbers={false}
{
    "type": "productImage",
    "label": "Image",
    "id": "image",
    "typeMeta": {
        "reference": "productId"
    }
}
```

At this point, your `schema.json` should contain the same array, schema, and settings as the [completed schema.json](https://github.com/bigcommerce-edu/lab-widget-templates/blob/main/product-grid/schema.json).

## Write the Widget Template Markup

Just as in the previous example, you will use Handlebars to access the widget's data in the template markup. Unlike the previous example, the data is available as an array rather than a single object. To iterate through the array and access the data for each of the productId and image settings, the template will use the \{\{#each}} Handlebars block helper to render some content for each element in the array. For more information on the \{\{#each}} helper, see the official [Handlebars documentation](https://handlebarsjs.com/guide/builtin-helpers.html#each).

In this example, you will use a CSS flexbox layout to create a grid that displays three products per row. Feel free to spruce up the markup, but bear in mind that future examples may reference the template you create in this section. For a CSS flexbox quick reference, see a resource like [css-tricks.com](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).

You'll write this markup directly in `widget.html`, as plain HTML and Handlebars — no JSON escaping required, since Widget Builder reads this file as-is when you publish.

1. **Open** `widget.html` and **write** a div tag with inline styles to define a flex container. Example:

```html showLineNumbers={false}
<div style="display: flex; flex-wrap: wrap">
</div>
```

2. Inside the div, **add** an \{\{#each}} block helper to iterate over the products array and render one div with inline styles to define a flex item for each element in the array. Example:

```jsx showLineNumbers={false}
<div style="display: flex; flex-wrap: wrap">
   {{#each products}}
       <div style="flex-grow: 1; width: 33%">
       </div>
   {{/each}}
</div>
```

3. Inside the flex item div, **add** an img tag with a src attribute that references the image setting with Handlebars.

Example:

```jsx showLineNumbers={false}
<img src="{{image.src}}" width="200px"/>
```

4. Inside the flex item div and under the img tag, **add** a new div containing text to display the selected product's ID.

Example:

```jsx showLineNumbers={false}
<div>Product ID: {{productId}}</div>
```

You should now have 8 lines of HTML:

```jsx showLineNumbers={false}
<div style="display: flex; flex-wrap: wrap">
   {{#each products}}
       <div style="flex-grow: 1; width: 33%">
           <img src="{{image.src}}" width="200px"/>
           <div>Product ID: {{productId}}</div>
       </div>
   {{/each}}
</div>
```

5. **Save** `widget.html`.

At this point, your `widget.html` should match the [completed widget.html](https://github.com/bigcommerce-edu/lab-widget-templates/blob/main/product-grid/widget.html).

## Add Sample Data to the Preview

The local preview renders your markup using the values in `config.json`. Widget Builder generated this file from your schema, and because the array has a `defaultCount` of 3 and its settings have no default values, it contains three empty product entries. You may reference the completed [config.json.example](https://github.com/bigcommerce-edu/lab-widget-templates/blob/main/product-grid/config.json.example) to check your work.

1. **Open** `config.json` and **add** sample values for the `productId` and `image` settings of each entry. For example:

```json showLineNumbers={false}
{
  "products": [
    {
      "productId": 1,
      "image": { "src": "https://placeholder.photo/200x200" }
    },
    {
      "productId": 2,
      "image": { "src": "https://placeholder.photo/200x200" }
    },
    {
      "productId": 3,
      "image": { "src": "https://placeholder.photo/200x200" }
    }
  ]
}
```

2. **Save** `config.json` and check the live preview in your browser. You should see a row of three products, each with an image and its product ID.

The values in `config.json` only affect the local preview. When you publish the template, store users supply their own values through the settings you defined in the schema.

## Create and Use the Widget Template

Having written the schema and markup, you are now ready to publish your widget template to the store and use it in Makeswift or Page Builder.

1. **Run** the following command from your `~/widget-templates` directory to publish the template:

```shell showLineNumbers={false}
widget-builder publish product-grid
```

> **Warning**
>
> Don't add a trailing slash to the directory name, as in `widget-builder publish product-grid/`. In Makeswift, a trailing slash creates a component with an empty name inside a sub-folder.

Widget Builder reads `schema.json` and `widget.html` and sends them to the Widgets API for you — no manual request body or REST client needed. The first time you publish a given template directory, Widget Builder creates a new widget template; if you publish again after making changes, it updates that same widget template in place.

After the command succeeds, your widget template is available in both visual editors. Use it in whichever editor you're working in.

### Use it in Makeswift

Makeswift needs a Makeswift-connected channel. If you haven't set one up, see [Lab - Navigate Makeswift](/developer/learn/courses/widgets-rest-api/overview/lab-makeswift).

1. **Open** the store control panel and go to the **Channel Manager**
2. **Select** the Makeswift-connected channel and click **Edit in Makeswift**
3. **Navigate** to a page in the editor that has an available region, such as the home page
4. **Open** the component drawer and **find** the component for your widget template
5. **Drag** the component into a region on the page
6. **Configure** the settings in the panel that opens. They are the product settings you defined in your schema, one set for each product in the array.
7. **Save** your changes

### Use it in Page Builder

1. **Open** Page Builder by navigating to Storefront > Customize in the BigCommerce. Look below the default list of basic widgets to find the Custom section.
2. **Drag** your custom widget onto the page. Assuming the schema is structured correctly, you should be able to modify the settings in the left sidebar.

### What if I can't edit my widget schema settings?

If Page Builder shows a warning instead of the widget's settings, there is an issue with the widget template schema. Examine your schema and review the [BigCommerce Dev Docs](/developer/docs/admin/widgets-and-scripts/guide). Specifically, ensure your schema has exactly one root element with type 'array', and that element has its own "schema" array with exactly one root tab element. All configurable settings should be contained in a section inside the tab.

## Section Challenge

For an extra challenge, try sprucing up the markup and CSS, or implement new settings to control the typography and styling of the widget.

* Try making the number of columns in the flex container configurable.
* Consider use cases like text alignment, changing the font in the text block or adding some copy under each product list.
* Consider using other [schema settings](/developer/docs/storefront/stencil/themes/context/object-reference/elements) types like select or color:
* Query the [Get All Widget Templates API](/developer/api-reference/rest/admin/content/widgets) to examine the basic widget templates for more ideas.