> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget overview

> Decide when to replace plain text widget replies with custom UI, and choose the right path for React or headless implementations.

Use <Tooltip tip="React or headless components that replace plain text chat bubbles with richer UI for specific AI action results.">custom components</Tooltip> when a normal chat bubble is not enough. Common examples include account summaries, order status cards, onboarding steps, appointment pickers, and other action results that are easier to use as UI than as plain text.

<Tip>
  If you have not installed the widget yet, start with **[Install Widget](/widget/install-widget)** first.
</Tip>

<Info>
  Custom components sit on top of the default widget UI — use the **[Playground](/widget/playground)** to dial in the widget's look first, then layer your action components on top.
</Info>

## When Custom Components Are Worth It

<AccordionGroup>
  <Accordion title="Structured action results" icon="bolt">
    Use custom components when your AI action returns data that should be presented as a card, table, summary, or interactive block.
  </Accordion>

  <Accordion title="Guided flows" icon="sliders">
    Use custom components or <Tooltip tip="Widget components that take over the full chat area to drive a structured flow — like onboarding, qualification, or multi-step forms.">`modesComponents`</Tooltip> when a visitor should move through a richer flow than normal back-and-forth chat.
  </Accordion>

  <Accordion title="Safer fallback UI" icon="shield">
    Use a component with a clear fallback state when an action may return incomplete or unexpected data.
  </Accordion>
</AccordionGroup>

## Choose Your Path

<CardGroup cols={2}>
  <Card title="React Components" icon="react" href="/widget/custom-components-react">
    Best when you use the default React widget and want to register components by action key.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Best when you own the renderer, routing, or storage layer and need full control over message UI.
  </Card>
</CardGroup>

## Two Kinds Of Advanced Widget UI

Do not mix these concepts together:

<CardGroup cols={2}>
  <Card title="Action result components" icon="bolt" href="/widget/custom-components-react">
    Render a custom UI after the AI calls an action and gets structured data back.
  </Card>

  <Card title="Conversation mode components" icon="rectangle-list" href="/widget/configuration#advanced-ui-conversation-modes">
    Render a dedicated UI for an active mode or canvas flow with `modesComponents`.
  </Card>
</CardGroup>

Both are valid. Pick the one that matches whether you are rendering a **result** or driving a **flow**.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="React Components" icon="react" href="/widget/custom-components-react">
    Register action-specific UI in the default React widget.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build custom rendering with the headless widget packages.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Use `modesComponents`, styling, and behavior options together.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build custom rendering with the headless widget packages.
  </Card>
</CardGroup>