Skip to main content
The Char agent is a web component that works with any JavaScript framework. Pass your user’s ID token and the agent handles the rest.

​
How It Works

Every framework follows the same pattern:
  1. Import or load the web component
  2. Add <char-agent> to your template
  3. Call connect({ idToken, clientId }) or connect({ ticketAuth }) to authenticate
The agent is framework-agnostic because it’s a standard web component. If your framework can render custom HTML elements, it can use Char.

​
Vanilla JavaScript

No framework? No problem: 
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@mcp-b/char/dist/web-component-standalone.iife.js" defer></script>
</head>
<body>
  <h1>My App</h1>
  <char-agent id="chat-widget"></char-agent>

  <script>
    // Get your ID token from your auth provider
    const idToken = getIdTokenFromYourAuthProvider();

    document.getElementById('chat-widget').connect({ idToken, clientId: 'your-oidc-client-id' });
  </script>
</body>
</html>

​
React Ecosystem

React (Next.js, TanStack Start, Remix)

Comprehensive guide covering SPA and SSR patterns for Next.js (App Router & Pages Router), TanStack Start, and Remix

​
Other Frameworks

Vue

Vue 3 Composition API with Nuxt SSR

Angular

Standalone components with CUSTOM_ELEMENTS_SCHEMA

Svelte

Svelte 4/5 with SvelteKit SSR

Solid

SolidJS with SolidStart SSR

​
Partial Page Update Frameworks

For frameworks that do partial page updates, place the agent outside the swap target to preserve conversation state across navigations.

HTMX

HTMX with Flask, Django, Go

Hotwire

Rails Turbo with Stimulus

Livewire

Laravel Livewire with Alpine.js

LiveView

Phoenix LiveView with HEEx

​
Key Concepts

​
SPA vs SSR Authentication

ArchitectureAuth MethodWhen to Use
SPAconnect({ idToken, clientId })Client-side auth (IDP SDK returns JWT to browser)
SSRconnect({ ticketAuth })Server-side auth (session cookies, server-rendered pages)

​
Using connect() vs Attributes

Always prefer the connect() method over HTML attributes: 
// Recommended - keeps token out of DOM
agent.connect({ idToken, clientId: 'your-oidc-client-id' });

// Avoid - never set auth tokens as DOM attributes
The connect() method stores tokens as JavaScript properties, protecting them from session replay tools and DOM inspection.

​
Persisting Across Navigation

For partial page update frameworks (HTMX, Hotwire, Livewire, LiveView), place the agent outside the swap target: 
<!-- Content that swaps -->
<div id="content">
  <%= yield %>
</div>

<!-- Agent persists outside swap target -->
<char-agent id="chat-widget"></char-agent>

​
See Also