Component Override SDK

The Component Override SDK gives a storefront a way to replace the widget’s built-in product and agent-action rendering with its own markup. It’s a messaging-mode capability. Overrides use a framework-agnostic contract based on standard custom elements, so you don’t need React to author them.

An override is the tag name of a custom element you’ve registered (a string, such as "product-card"), not a function. You register the element with customElements.define before the widget renders, then map an override key to the tag name. When the widget needs to render that slot, it calls document.createElement(tagName) and assigns a single props object to the element’s props setter.

You provide overrides as one flat map, ComponentOverrides, from an override key to a tag name:

1window.CimulateOverrides = {
2  // Standard built-in slots
3  ProductTile: "product-card",
4  ProductCarousel: "product-carousel",
5  ProgressSteps: "progress-steps",
6  // Custom agent-action block, matched by output_name
7  recentOrders: "cx-recent-orders",
8};

ProductTile, ProductCarousel, ProductDetailCard, ProductComparison, and ProgressSteps are the named keys the widget consults for its built-in UI. Every other key, such as recentOrders above, is a custom key matched against a streaming tool_results block by its top-level output_name (see Custom agent-action blocks). If you leave a built-in key unset, the widget renders its built-in default.

A tag name must be a valid custom element name: lowercase and containing a hyphen. Anything else (for example, "ProductTile" or "div") is rejected with a console error, and that slot renders blank.

Overriding ProductDetailCard replaces the entire built-in card, including its express-checkout section. When express checkout is enabled on the storefront, the built-in card renders Apple Pay and Google Pay buttons in an iframe served from a Salesforce Payments URL on your storefront. Your override receives that URL at payload.data.expressPaymentUrl and must build its own checkout UI from it (the built-in card loads it in an iframe). If expressPaymentUrl is absent, the product isn’t express-checkout eligible and you should render no payment button.

If you override ProductCarousel, your ProductTile override is not used inside it; you own everything the carousel renders.

Every override, whether a product slot or a custom block, receives the same props object on its element’s props setter:

1{ name, payload, api }

• name is the override key that matched ("ProductTile", "ProductCarousel", "ProductDetailCard", "ProductComparison", "ProgressSteps", or your custom block’s output_name).
• payload is the raw agent block data, untouched. The widget does not normalize it, so its shape depends on name. For products, the data lives at payload.data (name, price, discountPrice, currencyCode, imageUrl, productPageUrl), and your custom catalog fields arrive at payload.customProperties.c_*. For a carousel, iterate payload.products, where each entry has that same product shape. For progress steps, payload.steps is the list of step messages received so far, in order; the last entry is the active step.
• api gives the override a way to interact with the agent and adapt to the widget’s presentation.

sendMessage accepts one option, silent. Pass { silent: true } to suppress the outgoing user bubble for a machine-readable payload (such as a form’s final JSON) that would be noise in the transcript:

1api.sendMessage(JSON.stringify(record), { silent: true });

Only the outgoing bubble is suppressed; the agent’s reply still arrives and renders as a normal message. Your override isn’t notified of that reply, and isLoading stays false for a silent send, so you can’t wait on one. Render your own confirmation from data you already hold, or have the agent emit a tool_results block that an override renders.

When more than one override source is present, the widget resolves them in this order:

1. overridesUrl (a hosted script the widget loads)
2. overrides (an inline map passed to the injection function)
3. window.CimulateOverrides (a global set before the widget loads)
4. none (built-in rendering)

Override resolution never blocks the widget. The widget renders its built-in UI and opens the messaging connection immediately, then swaps in your custom elements once the map resolves. A hosted script that errors or times out resolves to an empty map, so the widget can never stall waiting on your override script.

Author each override as a custom element with a props setter that drives rendering. The messaging entry exports an optional OverrideElement base class that implements the props setter, getter, and lifecycle for you:

1import { OverrideElement } from "@cimulate/copilot-widget/messaging";
2
3class ProductCard extends OverrideElement {
4  render() {
5    const { payload, api } = this.props || {};
6    // Build your DOM here. Escape every agent-supplied value.
7  }
8}
9customElements.define("product-card", ProductCard);

Script-tag consumers reach the same class as CimulateMessaging.OverrideElement on the UMD bundle. You can also implement the contract directly on HTMLElement: a props setter that stores the value and calls your render, a matching getter, and a connectedCallback that renders.

The widget persists your element instance across its own re-renders. connectedCallback fires once; on later renders, the widget assigns to your props setter in place, so instance state, listeners, and focus survive. (An unregistered tag name is rebuilt on every commit instead, which is why registering the element matters.)

The widget does no sanitization of payload data. You own the DOM your override produces, so escape every value that comes from the agent or catalog before you insert it into markup. Build structure as author-constant strings and pass data through an escaping helper; never drop an unescaped value into innerHTML. Guard against script and other unsafe URL schemes before assigning to href or src.

customElements.define throws if the tag is already registered, and an uncaught throw aborts the whole script before your window.CimulateOverrides assignment runs, so every override silently falls back. Always guard the define:

1function defineOnce(tag, ctor) {
2  if (!customElements.get(tag)) customElements.define(tag, ctor);
3}
4defineOnce("product-card", ProductCard);

Beyond the named product slots, any other key in the map renders a custom agent-action payload: order tracking, option pickers, warranty forms, surveys, and so on. The agent emits a single tool_results block:

1{ "type": "tool_results", "index": 0, "output_name": "recentOrders", "data": {} }

The widget recognizes the block by its top-level type, routes on output_name alone (never a field inside data, so agent JSON can’t hijack routing), and renders the element registered for that key. An unmatched output_name renders nothing.

Your override receives only the raw data as payload; the widget strips its own bookkeeping fields first. Because data streams in token by token, the widget withholds it until the JSON is complete, so your render always receives one fully formed payload rather than a half-built object.

For example, an agent action that returns a shopper’s recent orders emits a block with output_name: "recentOrders" and an orders array in data. Register a custom element for that key and render the array:

1import { OverrideElement } from "@cimulate/copilot-widget/messaging";
2
3class RecentOrders extends OverrideElement {
4  render() {
5    const { payload } = this.props || {};
6    const orders = payload?.orders ?? [];
7    // Build rows from `orders`. Escape every agent-supplied value.
8  }
9}
10defineOnce("cx-recent-orders", RecentOrders);
11
12window.CimulateOverrides = {
13  ...window.CimulateOverrides,
14  recentOrders: "cx-recent-orders",
15};

The data the agent sent (here, { orders: [...] }) arrives as payload, so payload.orders is the array to render. The key in the map (recentOrders) must match the block’s output_name exactly.

Failure is contained per slot. If creating the element or assigning its props throws, that one slot renders blank and the widget logs a warning prefixed with [CimulateOverrides]. The rest of the transcript is unaffected and the widget never crashes.

At the widget level, you supply overrides two ways:

• Hosted URL (primary). Host a script on HTTPS that defines your custom elements and assigns window.CimulateOverrides. Point overridesUrl at it. The widget injects the script (HTTPS only, crossOrigin="anonymous", with a 5-second timeout), and reads the global once it runs.
• Inline object. If your app has already defined the custom elements, pass the map directly to the injection function. overridesUrl takes precedence when both are set.

1injectMessagingWidget({
2  elementId: "messaging-widget",
3  messagingConfig: {
4    scrt2Url: "https://your-org.my.salesforce-scrt.com",
5    orgId: "00Dxx0000000000",
6    esDeveloperName: "Your_Messaging_Channel",
7  },
8  overrides: {
9    ProductTile: "product-card",
10    recentOrders: "cx-recent-orders",
11  },
12});

Because window.CimulateOverrides is a plain object, you can assign to it from multiple files. Merge rather than replace so the files coexist, and make sure each runs synchronously at the top level before the widget’s first render.

On a framework storefront, you don’t call injectMessagingWidget yourself, so you deploy overrides through the framework’s configuration instead of the injection function.

The plugin_commerce_client cartridge loads overrides from a static script inside the cartridge. Place your script at cartridge/static/default/jscript/cimulate/overrides.js, define your custom elements, and assign window.CimulateOverrides there. Then upload the cartridge and point the widget at the script:

1. Add the script to the cartridge at cartridge/static/default/jscript/cimulate/overrides.js.

2. Upload the cartridge with npm run uploadCartridge (same command and dw.json you used to install it; see Install the Agentforce Commerce Client on SFRA).

3. Set the cc_overridesUrl key in the cc_config Site Preference to the relative path:

   1{
   2  "cc_overridesUrl": "/jscript/cimulate/overrides.js"
   3}

A relative path avoids a cross-origin request, and the cartridge derives the script-src CSP entry from the preference automatically. For the full cartridge install, dw.json, and site-path steps, see Install the Agentforce Commerce Client on SFRA.

The retail-react-app template accepts overrides through COMMERCE_AGENT_SETTINGS, either as an inline cc_overrides map or as a hosted cc_overridesUrl script. Set only one: the template forwards cc_overrides and drops the URL when both are present. For the inline map route:

1. Author the custom element as a class that extends OverrideElement from @cimulate/copilot-widget/messaging, escaping every agent-supplied value.

2. Register the element from the browser entry point (app/main.jsx), because customElements isn’t available during server-side rendering.

3. Map the override key to the element’s tag name in cc_overrides:

   1{
   2  "provider": "commerce-client",
   3  "cc_overrides": {
   4    "ProductTile": "cx-product-tile"
   5  }
   6}

For a hosted script instead, set cc_overridesUrl to an HTTPS script that defines your elements and assigns window.CimulateOverrides. For the full route detail, the Content Security Policy setup, and complete code, see Install the Agentforce Commerce Client on PWA Kit.

• Configure the Agentforce Commerce Client
• Style and Theme the Widget
• Choose a Customization Approach

j

Announcements

Choose Your B2C Commerce Storefront Type

Universal Commerce Protocol (UCP) Integration

B2C Commerce

SCAPI

Storefront Next

Composable Storefront

Storefront Reference Architecture (SFRA)

Agentforce Commerce Client

Install the Agentforce Commerce Client

Install the Agentforce Commerce Client on SFRA

Install the Agentforce Commerce Client on PWA Kit

Configure the Agentforce Commerce Client

Style and Theme the Widget

Choose a Customization Approach

Component Override SDK

Commerce Apps ISV Developer Guide

B2C Commerce Solutions

B2C Commerce Release Notes

B2C Commerce Reference Information

Ask the Community