Widgets & Page Builder

Page Builder is BigCommerce's visual, drag-and-drop page editor. What a merchant actually drags and drops are widgets — self-contained, configurable template fragments a developer defines once and a merchant can then place and configure without touching code.

Anatomy of a widget

A widget is a Handlebars template paired with a schema describing its configurable fields, conceptually parallel to a Shopify section's {% schema %} block:

<div class="promo-banner" style="background:{{settings.background_color}}">
  <p>{{settings.message}}</p>
</div>

[
  {
    "type": "text",
    "label": "Message",
    "id": "message",
    "default": "Free shipping over $50"
  },
  {
    "type": "color",
    "label": "Background color",
    "id": "background_color",
    "default": "#f5f5f5"
  }
]

Whatever a merchant sets for "Message" and "Background color" in Page Builder becomes available in the template as settings.message and settings.background_color — the schema's id fields are the bridge, exactly the same pattern as a Shopify section's settings.

Placing widgets on a page

Once registered, a widget shows up in Page Builder's widget panel, where a merchant drags it onto any region a page defines, reorders it relative to other widgets, and fills in its settings through generated form controls — no code editing involved on the merchant's side.

Global vs. page-specific widgets

A widget can be placed as global (appearing identically on every page — a promo bar or footer signup form) or scoped to one specific page, like a homepage-only hero banner. This distinction is set when the widget is placed, not when it's built — the same widget template can be used both ways depending on where a merchant drops it.

Widget templates vs. page templates

A widget is deliberately more constrained than a full page template — it can't assume anything about surrounding page structure, since it might be placed on the homepage, a category page, or anywhere else a widget region exists. Keeping a widget self-contained (its own markup, its own scoped styles) is what makes it safely reusable across contexts.

Visual page building on Catalyst

Page Builder is a Stencil-specific tool tied to Handlebars widgets. A storefront built with Catalyst (lesson 13) instead uses Makeswift, a visual page-building tool BigCommerce acquired and integrates with Catalyst — conceptually the same merchant-facing idea of dragging, dropping, and configuring content, but built for a React/Next.js frontend rather than Handlebars. Worth knowing this exists so you don't assume Page Builder is the only visual editing option across the whole platform.