Widget components

The iframe embed is zero-code but fixed-function. With the React SDK (@colossal-sh/chat-react) you host the widget inside your own app and extend it with custom component renderers: when an automation returns an output with a type you’ve registered, the widget renders your component instead of plain text. The flow has two halves:

In your app — define a component type and register a renderer for it.
In the automation builder — ask for automations to return their result in the output format that type needs.

1. Register a component renderer

npm install @colossal-sh/chat-react @colossal-sh/chat-client

import { createChatClient } from "@colossal-sh/chat-client";
import { ChatProvider, ChatWidget } from "@colossal-sh/chat-react";
import type { ComponentOutputProps } from "@colossal-sh/chat-react";
import "@colossal-sh/chat-react/styles.css";

const chatClient = createChatClient({
  agentUid: "<agent-uid>",
  adapter: { baseUrl: "https://<your-workspace-host>" },
});

function WarrantyCard({ payload }: ComponentOutputProps) {
  return (
    <div className="warranty-card">
      <strong>{String(payload.productTitle)}</strong>
      <span>{payload.active ? "Under warranty" : "Expired"}</span>
      <span>until {String(payload.expiresAt)}</span>
    </div>
  );
}

export function SupportChat() {
  return (
    <ChatProvider
      client={chatClient}
      componentRenderers={{ warranty_check: WarrantyCard }}
    >
      <ChatWidget />
    </ChatProvider>
  );
}

Create the client at module level and pass it via the client prop. With the config prop the provider creates the client after the first render, so components that read the chat context on mount (including ChatWidget) throw “must be inside <ChatProvider>” unless you gate them with useHasChatClient(). componentRenderers maps a type string to a React component. The renderer receives the whole output object as payload, plus the raw tool part and message if you need them.

2. Ask the builder for that output format

An output is matched to a renderer when the step result the agent responds with is a JSON object carrying your type. When building the automation, tell the builder the exact shape your component expects:

When a customer asks about warranty, look up the order and finish with an output of the form { "type": "warranty_check", "productTitle": ..., "active": true/false, "expiresAt": ... }.

The builder wires the automation’s final step to produce that object. At runtime the widget sees type: "warranty_check", finds your renderer, and renders the card in the conversation. If no renderer matches a type, the widget falls back to its default output rendering — so shipping the automation before the frontend (or vice versa) degrades gracefully.

Built-in component types

These types are rendered out of the box, and you can override any of them by registering your own renderer under the same key. All amounts are in minor units (cents).

Product List

Type: product_list — a horizontally scrollable list of product cards. Each card shows an Add button, which turns into a quantity stepper once the item is in the cart:Payload

array

required

The products to show. Renders nothing when empty. Each item:

Show product

string

Product identifier.

string

Product title.

number

Price in minor units, formatted with currency.

string

Currency code, e.g. USD.

string

Product image URL.

string

Link target for the card.

Cart Updated

Types: cart_add, cart_remove — a confirmation chip reading “Cart updated” for cart_add, “Item removed” for cart_remove.PayloadNo fields beyond type; the label is chosen from the type itself.

Cart View

Type: cart_view — a summary card of the customer’s current cart, or an empty-cart state. Quantity steppers adjust items in place; on Shopify embeds the cart bridge keeps this in sync with the real storefront cart:PayloadNo fields beyond type; the card reads the live cart from the widget’s cart state rather than the payload.

Order Details

Type: order_details — an order summary card with line items, total, addresses, and status, plus a tracking link when available:Payload

object

required

Renders nothing without an order.number.

Show order

string

required

Order number, shown as #number.

string

Status label, e.g. fulfilled.

string

ISO date, shown as the order date.

string

Customer display name.

number

Order total in minor units, formatted with currency.

string

Currency code for the total and line prices.

array

Line items: { name, quantity, price_amount }.

string

Shipping address as a comma-separated string.

string

Billing address as a comma-separated string.

string

Shipment tracking link.

Button Link

Type: button_link — a single link styled as a button.Payload

string

required

Button text.

string

required

Link target; must be an http(s) URL or nothing is rendered.

Get started

Platform

Agents

Automations

Storefront

Dev Tools

Widget components

1. Register a component renderer

2. Ask the builder for that output format

Built-in component types

​1. Register a component renderer

​2. Ask the builder for that output format

​Built-in component types

1. Register a component renderer

2. Ask the builder for that output format

Built-in component types