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

# <char-agent>

> Custom element API reference for <char-agent>.

# `<char-agent>`

`<char-agent>` custom element.

Creates an iframe pointing to the SaaS app's /embed/ entrypoint and relays
auth, styles, dark mode, display mode, and MCP messages via postMessage.

Uses a unified `char-context` message with diffing (only changed fields
are sent) instead of separate messages per concern.

## Registration and import

```ts theme={null}
import '@mcp-b/char/web-component'
```

```ts theme={null}
import { registerChar } from '@mcp-b/char/web-component'
registerChar()
```

## Auth and connection helpers

```ts theme={null}
const agent = document.querySelector('char-agent')

agent?.setAuth({ publishableKey, idToken }) // convenience wrapper
agent?.connect({ publishableKey, idToken }) // explicit connect
agent?.setHostContext({ displayMode: 'inline' })
agent?.disconnect()
```

* [`setAuth`](#method-setauth)
* [`connect`](#method-connect)
* [`disconnect`](#method-disconnect)
* [`setHostContext`](#method-sethostcontext)

## Attributes

| Attribute            | Type                                | Default                  | Description                                      |
| -------------------- | ----------------------------------- | ------------------------ | ------------------------------------------------ |
| `api-base`           | `string`                            | `https://app.usechar.ai` | Overrides the Char API base URL.                 |
| `display-mode`       | `"inline" \| "fullscreen" \| "pip"` | `pip`                    | Requested display mode for the embedded surface. |
| `enable-debug-tools` | `boolean`                           | `false`                  | Enables iframe debug tools when supported.       |
| `publishable-key`    | `string`                            | n/a                      | Publishable key used to resolve org context.     |

## Properties

| Property         | Type                  | Description                                                                                 |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------- |
| `apiBase`        | `string \| undefined` | React-friendly property form of `api-base`.                                                 |
| `publishableKey` | `string \| undefined` | Publishable key for org identification. Set via `publishable-key` attribute or JS property. |

## Methods

| Method                                       | Returns | Summary                                                                                                                                                                               |
| -------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`setAuth()`](#method-setauth)               | `void`  | Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.                                                                                       |
| [`connect()`](#method-connect)               | `void`  | Connect to the Char agent with authentication. The token is stored as a JavaScript property (not as a DOM attribute), preventing exposure to DOM inspection and session replay tools. |
| [`disconnect()`](#method-disconnect)         | `void`  | Disconnect from the Char agent. Clears pending auth state and posts a disconnect message to the iframe.                                                                               |
| [`setHostContext()`](#method-sethostcontext) | `void`  | Update the host context sent to the iframe. Only changed fields are transmitted (diffing pattern).                                                                                    |

<a id="method-setauth" />

### `setAuth(options: ConnectOptions | null): void`

Convenience method for declarative wrappers.
Applies auth when provided, otherwise clears auth.

Parameters:

* `options` (`ConnectOptions | null`): Auth payload to connect, or `null` to disconnect.

Returns: `void`

<a id="method-connect" />

### `connect(options: ConnectOptions): void`

Connect to the Char agent with authentication.

The token is stored as a JavaScript property (not as a DOM attribute),
preventing exposure to DOM inspection and session replay tools.

Parameters:

* `options` (`ConnectOptions`): Authentication payload.

Returns: `void`

<a id="method-disconnect" />

### `disconnect(): void`

Disconnect from the Char agent.
Clears pending auth state and posts a disconnect message to the iframe.

Returns: `void`

<a id="method-sethostcontext" />

### `setHostContext(hostContext: CharHostContext): void`

Update the host context sent to the iframe.
Only changed fields are transmitted (diffing pattern).

Parameters:

* `hostContext` (`CharHostContext`): Partial host context patch to merge and emit.

Returns: `void`

## Events

| Event                       | Detail                         | Description                                          |
| --------------------------- | ------------------------------ | ---------------------------------------------------- |
| `char-initialized`          | `void`                         | Emitted when the embedded runtime has initialized.   |
| `char-close`                | `void`                         | Emitted when the embedded UI asks the host to close. |
| `char-error`                | `CharErrorDetail`              | Emitted on host/runtime bridge errors.               |
| `char-size-changed`         | `CharSizeChangedDetail`        | Reports embedded content sizing updates.             |
| `char-request-display-mode` | `CharRequestDisplayModeDetail` | Requests a host-side display mode change.            |
| `char-open-link`            | `CharOpenLinkDetail`           | Requests the host to open an external URL.           |

## Slots

*None.*

## CSS Custom Properties

Supports the full Char design-token surface documented in [CSS Variables Reference](/reference/css-variables).

## CSS Parts

*None.*