Skip to main content

​
<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

import '@mcp-b/char/web-component'

import { registerChar } from '@mcp-b/char/web-component'
registerChar()

​
Auth and connection helpers

const agent = document.querySelector('char-agent')

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

​
Attributes

AttributeTypeDefaultDescription
api-basestringhttps://app.usechar.aiOverrides the Char API base URL.
display-mode"inline" | "fullscreen" | "pip"pipRequested display mode for the embedded surface.
enable-debug-toolsbooleanfalseEnables iframe debug tools when supported.
publishable-keystringn/aPublishable key used to resolve org context.

​
Properties

PropertyTypeDescription
apiBasestring | undefinedReact-friendly property form of api-base.
publishableKeystring | undefinedPublishable key for org identification. Set via publishable-key attribute or JS property.

​
Methods

MethodReturnsSummary
setAuth()voidConvenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.
connect()voidConnect 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()voidDisconnect from the Char agent. Clears pending auth state and posts a disconnect message to the iframe.
setHostContext()voidUpdate the host context sent to the iframe. Only changed fields are transmitted (diffing pattern).

​
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

​
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

​
disconnect(): void

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

​
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

EventDetailDescription
char-initializedvoidEmitted when the embedded runtime has initialized.
char-closevoidEmitted when the embedded UI asks the host to close.
char-errorCharErrorDetailEmitted on host/runtime bridge errors.
char-size-changedCharSizeChangedDetailReports embedded content sizing updates.
char-request-display-modeCharRequestDisplayModeDetailRequests a host-side display mode change.
char-open-linkCharOpenLinkDetailRequests the host to open an external URL.

​
Slots

None.

​
CSS Custom Properties

Supports the full Char design-token surface documented in CSS Variables Reference.

​
CSS Parts

None.