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
| Kind | Type prefix | Written as | Who adds one |
|---|---|---|---|
| Basic | basic.* | 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. |
| Pack | catalog.* 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. |
| Custom | custom.* | 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. |
| Code | custom.* | 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. |
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
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 } },
},
},
}; -
typeisbasic.,catalog.,commerce.orcustom.followed by a lower-case name.vstarts at 1.groupislayout,basic,catalog,commerceorcustom. -
Each setting has a
tab(content,style,advanced), anoutput(markupreaches the component as a prop,cssreaches the stylesheet as a custom property) and acontrol. Acsssetting 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.entranceis drawn by the renderer around every widget, so your component needs no code for it. -
datanames the inputs: what result types each accepts, whether it is required, a label and an optional default binding. -
placementmay sayslotsOnly,notIn(header,footer,slot) ortopLevelOnly(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
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
displayonly. A price is{ amount, currency, display }. Never format an amount yourself. - Images go through
AssetImagewith themediaOriginyou were given: https, on exactly that origin, or no image. - Links use
resolveLinkfor a link target, and every href is checked again withsafeUrlfrom@usethrottle/builder-schema. - No raw HTML. No
dangerouslySetInnerHTMLorinnerHTML. Rich text is parsed into React elements. - No data, no noise. With nothing to show, render the hint when
editModeis 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: trueis 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
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 });
},
}; -
idisprovider.name, lower case.provideriscatalogorcommerce.resultis one ofproduct[],product,collection,category[],review[],customer,cart. -
fieldsis 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.displayor.currency. cacheKindislistings,product,reviewsornone. 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 shipscatalog.products,catalog.product,catalog.collection,catalog.categories,catalog.reviews,catalog.cart,context.product,context.listingand, in the commerce pack,throttle.customer.
Packs, link targets and slots
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, ornullwhen it cannot.nullmeans no link, never a wrong one. A catalog target holds the catalog id, so callwarmCatalogLinkson 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 areCATALOG_SLOT_POINTS. A slot's widgets read the context throughcontext.*bindings. - Registration.
createRendererRegistryputs the built-in pack first. A pack cannot replace abasic.*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
// 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], orPACK_MIGRATIONSin 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
@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, withentranceDelayMs) 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
BuilderProviderin a layout that also wraps your checkout, account and sign-in pages and pass itpathname. 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
jsis called asrun(root, input)once for each copy of the widget on the page, whereinputis{ props, data }. It is at most 64 KB and must parse. The markup and CSS follow the template widget rules (no script element, noon*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-reactare the only source. Its build writesbuilder-pack.jsonfrom 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-schemacomes first,builderreads on it,builder-reactrenders with both, andstorefront-react/builderis 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).