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

# Widget

> Every TruGen agent ships with a drop-in widget — the React component or iframe that renders your agent inside any web app.

Every agent you create in TruGen comes with a **widget** — a React component (also available as an iframe) that renders the agent inside your web app. The widget picks up its appearance, position, buttons, branding, and domain restrictions directly from the agent's `widget` configuration on the agent itself.

That means: change the widget in the Studio or via the API, and every embed of the widget everywhere picks up the change on the next session. Your app doesn't redeploy.

## What lives on the widget config

When you create or edit an agent in the [Studio](https://app.trugen.ai), the **Widget** section lets you configure:

* **Position** — `left`, `right`, `center`, `center-mini`, or `full`
* **Widget type** — dual (Talk + Chat), Talk-only, or Chat-only
* **Colors** — solid or gradient, plus theme (dark/light)
* **Branding** — company logo, company name, agent display name
* **Buttons** — custom text for Start Chat, Talk, and Chat
* **Suggested topics** — starter prompts to nudge users toward useful conversations
* **Allowed domains** — restrict which origins can embed the agent

These settings live on the agent's `widget` object. See the [Widget Customization](/docs/integrations/widget-customization) reference for every field and how it renders.

## Where to ship it

Pick the embed path that matches your stack:

<CardGroup cols={2}>
  <Card title="React widget" icon="react" href="/docs/integrations/widget-integration">
    Install `@aiteammate/agent-widget` and render with your agent ID.
  </Card>

  <Card title="iFrame" icon="code" href="/docs/integrations/embed-via-iFrame">
    Drop the iframe into any HTML page — no npm install.
  </Card>
</CardGroup>

For no-code platforms (Framer, Shopify, WordPress, Wix, Squarespace) see the dedicated [Site Builder guides](/docs/deploy/platforms/framer).

## Widget vs iFrame

Both paths render the same underlying widget with the same agent config. The difference is how it lives inside your app.

|                      | React widget                       | iFrame                      |
| -------------------- | ---------------------------------- | --------------------------- |
| **Setup**            | `npm install`, render component    | Paste one HTML tag          |
| **Styling**          | Renders in a Shadow DOM (isolated) | Rendered inside an iframe   |
| **Framework fit**    | React / Next.js apps               | Any framework, plain HTML   |
| **Bundle size cost** | Small — widget is code-split       | Zero                        |
| **Custom UI hooks**  | Widget props for user context      | URL params for user context |

The React widget is slightly more powerful — you can pass `userName`, `userId`, and `context` as typed props. The iframe accepts the same via query params.

## Next steps

<CardGroup cols={2}>
  <Card title="Widget Customization" icon="palette" href="/docs/integrations/widget-customization">
    Every widget config field — position, colors, buttons, branding, domain restrictions.
  </Card>

  <Card title="Widget SDK Reference" icon="react" href="/docs/integrations/widget-reference">
    Every prop the React widget accepts.
  </Card>
</CardGroup>