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. Want to try widget options live without installing anything? Open the Playground.

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

Step 2: Register It On The Widget

WidgetWrapper.tsx

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.

Playground

Try widget options in a live form and copy the generated snippet.