@mcp-b/char-react

React adapters over @mcp-b/char custom elements.

This package keeps React ergonomics (props, refs, auth convenience, event callbacks) while delegating runtime behavior to custom elements.

Install

npm i @mcp-b/char-react

react and react-dom are peer dependencies.

Exports

• CharAgent: thin wrapper over <char-agent>
• CharAgentShell: thin wrapper over <char-agent-shell>

CharAgent (low-level)

import { CharAgent } from '@mcp-b/char-react'

export function SupportWidget({ idToken }: { idToken?: string }) {
  return (
    <CharAgent
      publishableKey="pk_live_your_key_here"
      idToken={idToken}
      displayMode="inline"
      onCharError={(detail) => {
        console.error(detail.code, detail.message)
      }}
    />
  )
}

CharAgentShell (opinionated)

import { CharAgentShell } from '@mcp-b/char-react'

export function SupportShell({ idToken }: { idToken?: string }) {
  return (
    <CharAgentShell
      publishableKey="pk_live_your_key_here"
      idToken={idToken}
      panelWidth={420}
      fullscreenBreakpoint={1024}
      pipPosition="bottom-center"
    />
  )
}

CharAgentShell behavior is owned by <char-agent-shell>:

• pip: iframe-owned compact composer surface
• inline: desktop push panel
• fullscreen: narrow viewport expanded mode
• upstream unavailable: fail-closed (shell hides fully and emits char-error)

Auth convenience

Both wrappers call element methods automatically:

• publishableKey is required; idToken is optional
• auth props present -> setAuth(...) (delegates to connect(...))
• auth props removed -> setAuth(null) (delegates to disconnect())