Skip to main content
Use this page when you are using @opencx/widget-react and want specific AI action results to render as custom React UI.
Need the broader concept first? Start with Custom Components.

​
How React Component Mapping Works

For the default React widget, you register an array of components on . Each entry needs:
  • a key
  • a React component
The key must match the action in camelCase.

​
Step 1: Build The Component

Use so your component is typed to the action result you expect.
AccountBalanceCard.tsx
import { WidgetComponentProps } from '@opencx/widget-react-headless';

type AccountBalancePayload = {
  balance: number;
  currency: string;
};

export function AccountBalanceCard({
  data,
}: WidgetComponentProps<AccountBalancePayload>) {
  const result = data?.action?.data;

  if (!result) {
    return <div>Balance details are not available right now.</div>;
  }

  return (
    <div>
      <strong>Available balance</strong>
      <div>
        {result.balance} {result.currency}
      </div>
    </div>
  );
}

​
Step 2: Register It On The Widget

WidgetWrapper.tsx
import { Widget } from '@opencx/widget-react';
import { AccountBalanceCard } from './AccountBalanceCard';

export function WidgetWrapper() {
  return (
    <Widget
      options={{
        token: '<WIDGET_TOKEN>',
      }}
      components={[
        {
          key: 'getAccountBalance',
          component: AccountBalanceCard,
        },
      ]}
    />
  );
}

​
What To Watch For

If the component key does not match the action operation_id, the widget will not use your custom component.
Always render a fallback when data?.action?.data is missing or incomplete.
Focus each component on one action result. If a component tries to handle many unrelated actions, it becomes hard to trust and maintain.

​
Good React Use Cases

Account and order summaries

Show balances, plans, shipments, invoices, or usage totals as structured UI.

Status and confirmation cards

Show action outcomes like refunds, appointment bookings, or case updates in a clearer format.

Mini workflows

Collect a few related inputs or guide the visitor through the next step after a successful action.

Rich fallback states

Give visitors a clear next step when the action returns partial data or nothing useful.

Custom Components

Decide when custom UI is worth the added complexity.

Headless

Build fully custom rendering when the default widget is not enough.

Configuration

Use widget behavior and mode configuration alongside custom UI.

Headless

Build fully custom rendering when the default widget is not enough.