Developers / Throttle Builder

Widget guideline

A widget is a definition (data) plus a React component. The Builder editor, the Worker and the MCP tools read only the definition. The store renders the component. This page is for the person writing a widget. To add a widget without writing code, use a custom widget.

Three kinds of widget

KindType prefixWritten asWho adds one
Basicbasic.*Definitions in @usethrottle/builder-schema, components in @usethrottle/builder-react: heading, text, image, button, spacer, divider, video, logo, menu, announcement, copyright. Every renderer carries them.The Builder.
Packcatalog.* commerce.*Definitions, data sources and components in @usethrottle/storefront-react/builder. The Builder bundles the data half (builder-pack.json).Throttle, in a release of the package.
Customcustom.*A template or composite definition stored with the Widget API. Rendered by the Builder's own template runtime.A merchant or an agent, no deploy.
Codecustom.*A custom widget of kind: "code": markup, CSS and a script that runs on the store page. Off unless a person turned code on. See Code widgets.A merchant, or an agent with the code switch.
Which widgets the editor offers
The Worker validates against the builder-pack.json of one pinned version of @usethrottle/storefront-react, plus the store's custom widgets. A widget appears in the editor only if it is in that manifest. A pack you write in your own store can render widgets that are already in a page, but it cannot add a new one to the library.

A widget definition

The data half
import type { WidgetDefinition } from '@usethrottle/builder-schema';
import { COMMON_WIDGET_SETTINGS } from '@usethrottle/builder-schema';

export const featuredShelfDefinition: WidgetDefinition = {
  type: 'catalog.featured-shelf',
  v: 1,
  title: 'Featured shelf',
  group: 'catalog',
  icon: 'grid',
  description: 'A short row of featured products.',
  settings: [
    { key: 'title', label: 'Title', tab: 'content', output: 'markup', control: 'text',
      translatable: true, default: { en: 'Featured' }, maxLength: 100 },
    { key: 'columnsDesktop', label: 'Columns on desktop', tab: 'style', output: 'markup',
      control: 'number', min: 1, max: 6, default: 4 },
    ...COMMON_WIDGET_SETTINGS,
  ],
  data: {
    products: {
      accepts: ['product[]'],
      required: true,
      label: 'Products',
      default: { source: 'catalog.products', params: { source: 'featured', limit: 8 } },
    },
  },
};
  • type is basic., catalog., commerce. or custom. followed by a lower-case name. v starts at 1. group is layout, basic, catalog, commerce or custom.
  • Each setting has a tab (content, style, advanced), an output (markup reaches the component as a prop, css reaches the stylesheet as a custom property) and a control. A css setting must use a control whose value is a token, number, colour or enum (color, spacing, font-size, alignment, number, toggle, select), never free text.
  • At most 40 settings of your own. The common settings (hidden, anchor, spacingTop, spacingBottom, entrance, entranceDelayMs) are appended and do not count. entrance is drawn by the renderer around every widget, so your component needs no code for it.
  • data names the inputs: what result types each accepts, whether it is required, a label and an optional default binding.
  • placement may say slotsOnly, notIn (header, footer, slot) or topLevelOnly (not inside an inner section).

Every setting reaches the component already prepared: defaults filled in, translatable text resolved to the page locale, and an image setting replaced by its frozen asset with its width variants.

The component

A component
import type { WidgetRenderProps } from '@usethrottle/builder-react';

export function FeaturedShelfWidget({ props, data, editMode }: WidgetRenderProps) {
  const products = Array.isArray(data.products) ? (data.products as ProductItem[]) : undefined;
  if (products === undefined || products.length === 0) {
    // Nothing in a store; a hint in the editor.
    return editMode ? <p>No products to show yet.</p> : null;
  }
  return (
    <section>
      <h2>{String(props.title)}</h2>
      <ul>
        {products.map((product) => (
          <li key={product.handle}>
            <a href={product.url}>{product.title}</a>{' '}
            <span>{product.price.display}</span>
          </li>
        ))}
      </ul>
    </section>
  );
}

The component gets WidgetRenderProps: node, props, data, editMode, locale, mediaOrigin, resolveLink, inlineEdit (editor only) and budget (custom widgets).

Rules every widget keeps:

  • Money is printed through display only. A price is { amount, currency, display }. Never format an amount yourself.
  • Images go through AssetImage with the mediaOrigin you were given: https, on exactly that origin, or no image.
  • Links use resolveLink for a link target, and every href is checked again with safeUrl from @usethrottle/builder-schema.
  • No raw HTML. No dangerouslySetInnerHTML or innerHTML. Rich text is parsed into React elements.
  • No data, no noise. With nothing to show, render the hint when editMode is on and nothing in a store. A widget that throws blanks only itself.
  • Own properties only (Object.hasOwn) when you look up anything keyed by document or settings data.
  • Shopper data is browser-only. A source with perShopper: true is never read on the server; the widget draws nothing until it arrives, so the server and first browser render match.
  • Do not set a revalidate time or call a cache API. Reads go through the client, which keeps them for at least an hour and clears them when something changes.

Data sources

A data source
import type { PackDataSource } from '@usethrottle/builder-react';

export const newestProducts: PackDataSource = {
  id: 'catalog.newest',
  provider: 'catalog',
  title: 'Newest products',
  description: 'The most recently added products.',
  params: [
    { key: 'limit', label: 'How many', tab: 'content', output: 'markup', control: 'number',
      min: 1, max: 48, default: 8 },
  ],
  result: 'product[]',
  fields: [
    { name: 'handle', type: 'string', example: 'linen-shirt' },
    { name: 'title', type: 'string', example: 'Linen shirt' },
    { name: 'url', type: 'url', example: '/p/linen-shirt' },
    { name: 'price', type: 'money' },
  ],
  perShopper: false,
  cacheKind: 'listings',
  async resolve(params, ctx) {
    // ctx: { locale, currency?, preview, context?, signal }
    // Answer plain data. A price is { amount, currency, display }; print display.
    return loadNewest({ limit: Number(params.limit), locale: ctx.locale, signal: ctx.signal });
  },
};
  • id is provider.name, lower case. provider is catalog or commerce. result is one of product[], product, collection, category[], review[], customer, cart.
  • fields is the allow-list of what a template may read, by dotted name, with a type (string, number, boolean, money, image, url, date, list). A money field is printed only as .display or .currency.
  • cacheKind is listings, product, reviews or none. Params are checked by the resolver, because they come from a document: clamp numbers, default what is missing.
  • A binding is { source, params }, or { source: 'context.product' } inside a slot, which takes what the page knows. The catalog pack ships catalog.products, catalog.product, catalog.collection, catalog.categories, catalog.reviews, catalog.cart, context.product, context.listing and, in the commerce pack, throttle.customer.

Packs, link targets and slots

A pack
import type { WidgetPack } from '@usethrottle/builder-react';

export function shelvesPack(): WidgetPack {
  return {
    id: 'shelves',
    version: '1.0.0',                 // the npm version that ships it
    widgets: [{ ...featuredShelfDefinition, Component: FeaturedShelfWidget }],
    dataSources: [newestProducts],
    // linkTargets: { resolve(target) { ... } },
    // slots: [{ name: 'product.below', context: 'product' }],
  };
}

// <BuilderProvider packs={[shelvesPack()]} site={site}> and loadSite({ packs: [shelvesPack()], ... })
  • Link targets. A pack may give linkTargets.resolve(target), which turns a menu or link target it owns (a category, collection, product or search) into an href, or null when it cannot. null means no link, never a wrong one. A catalog target holds the catalog id, so call warmCatalogLinks on the server before rendering menus.
  • Slots. A pack lists the places its pages render a slot ({ name, context: 'product' | 'listing' | 'none' }). The catalog pack's are CATALOG_SLOT_POINTS. A slot's widgets read the context through context.* bindings.
  • Registration. createRendererRegistry puts the built-in pack first. A pack cannot replace a basic.* type, and the first definition of a type and version wins.

catalogPack({ catalogKey, cartStorage?, onLocaleChange?, onCurrencyChange? }) and commercePack({ auth? }) are the two packs in @usethrottle/storefront-react/builder. The language and currency switches render nothing in a store without their handlers.

Versions and migrations

A new version
// Version 2 renames "title" to "heading". Props of v1 become props of v2.
export const featuredShelfV2: WidgetDefinition = {
  ...featuredShelfDefinition,
  v: 2,
  settings: featuredShelfDefinition.settings.map((field) =>
    field.key === 'title' ? { ...field, key: 'heading' } : field,
  ),
  migrations: {
    1: (props) => {
      const { title, ...rest } = props;
      return title === undefined ? rest : { ...rest, heading: title };
    },
  },
};
// Keep v1 registered too: a published page still holds v1 nodes, and they are lifted when they render.
  • A released definition is never edited in a breaking way. Change a setting incompatibly by bumping v.
  • A new version needs a forward migration from the one before it (migrations[fromV], or PACK_MIGRATIONS in the storefront package) and a test fixture for it.
  • Migrations go forward only. A page document holding an older node is lifted when it renders. A node whose type or version the store does not know renders nothing in the store, and the editor says to update @usethrottle/storefront-react.
  • A migration also runs on the tablet and phone overrides, which hold partial props. A migration that invents keys out of nothing cannot, so keep it a rename or a conversion of an existing key.

Interactions, countdown, saved sections and code

Stores need builder-react 0.4.0 and builder-schema 0.2.1
Everything in this section needs a store on @usethrottle/builder-react 0.4.0 or later and @usethrottle/builder-schema 0.2.1 or later. On 0.3.x, interactions degrade to a plain row of columns, a countdown is empty, custom CSS is ignored, and a page that holds a saved-section reference fails to render. Upgrade the store before a merchant or an agent uses any of it.

Interactions

Interactions are a property of a section or inner section, not a widget you write. Set interaction to tabs, accordion, carousel or toggle (show and hide), and its columns (1 to 6) become the panels. A column's panelTitle is the tab or accordion title. Because the columns are ordinary columns, any widget, including yours, goes inside a panel and nothing about the widget changes. The mode can differ per device (tabs on desktop, an accordion on a phone). The props, defaults and how each mode draws without script are in the document schema and Rendering.

  • Accessible and light. Tabs use the tab roles with arrow, Home and End keys; an accordion and a toggle are native details; a carousel never autoplays unless asked and never under reduced motion, and shows a Pause button while it plays. One script of about 1.5 KB ticks the countdown and wires these up.
  • Server-rendered. No panel is hidden and nothing is invisible until the script runs.
  • Entrance animation (entrance: fade, slide-up, slide-left, zoom, with entranceDelayMs) is a common setting of every node. It is off under reduced motion, and a widget you write gets it from the renderer with no code of its own.

Countdown

basic.countdown counts down to target, an ISO 8601 instant with an offset (for example 2026-12-24T18:00:00+01:00), and shows days, hours, minutes and seconds as chosen. At zero it shows its expiredText or hides itself (expiredBehavior). The page renders the same on the server and in the browser, so a cached page is never wrong: the time left is filled in by the browser.

Custom CSS

The site's theme.customCss (20,000 characters at most) goes through the same sanitizer as a custom widget's CSS (no url(, no @import, only allow-listed properties) and is scoped to Builder content, so it cannot restyle the rest of the store.

Saved sections

A saved section is one section kept once and used on many pages, the header, the footer or a slot. A page holds a saved-section reference at its root, and the store draws the saved section's published content where the reference stands. Publish the saved section once and every page that uses it updates (an update to the pages that use it is announced as one change notice per document: no site-wide purge). Rules that follow from this:

  • A reference counts as one section. A saved section is exactly one section and cannot hold another reference.
  • A page cannot be published while a saved section it uses has never been published (SAVED_SECTION_UNPUBLISHED).
  • A saved section cannot be deleted while any page, header, footer or slot uses it (SAVED_SECTION_IN_USE, with the list). To keep the content on a page and stop sharing it, detach the reference: it becomes a copy.
  • Publishing a saved section changes every page that uses it, so it needs the Full level when an AI agent does it. See Levels.
  • Reading it from a store: Rendering. Shape: document schema.

Code widgets

A code widget is a custom widget whose script runs on the store page. Code can read and change anything on your store pages. Use a template widget or a pack widget when one will do.

  • Off by default. Code is off for every site until a person turns it on in Throttle Builder under Code, and a person can turn all of it off in one click, which takes effect on the very next request even for a cached page. Neither is available to an API key or an AI agent.
  • Route allow-list. The store's renderer never emits a code widget on checkout, cart, account or sign-in pages (nor orders and payment pages, or the same words on any path segment). This is built into builder-react; no setting changes it. Details and the one limit for root-level page routes: Rendering.
  • The provider must cover those routes. Put BuilderProvider in a layout that also wraps your checkout, account and sign-in pages and pass it pathname. When a visitor moves from a page that loaded code to one of those pages, the provider reloads the page from the server so no loaded script survives there.
  • Content-Security-Policy. The script is served from the Builder, so a store with a strict policy adds script-src https://builder.usethrottle.dev.
  • Every save is a version with its author (a person or an agent key), and an earlier version can be rolled back as a new one.
  • Authoring. The body of js is called as run(root, input) once for each copy of the widget on the page, where input is { props, data }. It is at most 64 KB and must parse. The markup and CSS follow the template widget rules (no script element, no on* attribute). The Builder's own preview shows the markup and CSS with a "Runs on your store" badge; see it run on the store's preview link.

An AI agent needs the code switch on its key or connection, as well as a level, to write one. See Builder MCP server: code widgets.

The integration contract

  • Two copies, one source. The definitions in @usethrottle/storefront-react are the only source. Its build writes builder-pack.json from them, and a test fails when the file drifts. The Builder pins one version of the package and validates against that manifest, so a widget a merchant can place exists in the store only once the store runs that version or a later one.
  • Upgrade the store before the Builder. A store on an older package renders a newer widget as nothing. Release the package, upgrade stores, then let the Builder pin it.
  • Everything a page needs is frozen into it at publish: custom widget snapshots, media assets with their variants, and the links it holds. The store never calls Throttle for an image or a custom widget while it renders.
  • Dependency direction. builder-schema comes first, builder reads on it, builder-react renders with both, and storefront-react/builder is the only place of the catalog package that imports a Builder package.
  • Document limits apply to what a widget adds: 2,000 nodes, 100 children per column and 512 KB for a page (see the document schema).