React Integration

Overview

The SDK's React adapter gives you hooks and pre-built components for building chat experiences. Everything imports from gecx-chat/react.

There are two ways to use it:

1. Hooks only -- wire useChatSession into your own markup.
2. Pre-built components -- drop in ChatSurface, MessageList, Composer, and friends for a working UI out of the box.

Both approaches work together. Start with the pre-built components, then replace individual pieces as your design requires.

ChatProvider

ChatProvider is the root context provider. Wrap your app (or the chat subtree) with it so that hooks like useChatClient, useIdentity, and useConversations can access the client.

import { ChatProvider } from 'gecx-chat/react';
import { createChatClient } from 'gecx-chat';

const client = createChatClient({
  auth: tokenEndpointAuth({ endpoint: '/api/gecx-chat-token' }),
});

function App() {
  return (
    <ChatProvider client={client}>
      {/* your chat UI */}
    </ChatProvider>
  );
}

Props

ChatProvider is not required if you pass config or client directly to useChatSession. But it is required for useChatClient, useIdentity, and useConversations.

useChatSession

The main hook. It manages the full chat lifecycle: session creation, streaming, message state, errors, input, and cleanup.

import { useChatSession, MessagePart } from 'gecx-chat/react';

function SupportChat() {
  const {
    messages,
    status,
    error,
    canSend,
    isStreaming,
    input,
    sendText,
    stop,
  } = useChatSession();

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          {msg.parts.map((part) => (
            <MessagePart key={part.id} part={part} />
          ))}
        </div>
      ))}

      {error && <p>{error.message}</p>}

      <form onSubmit={(e) => { e.preventDefault(); sendText(input.value); }}>
        <input
          value={input.value}
          onChange={(e) => input.set(e.currentTarget.value)}
          disabled={!canSend}
        />
        <button type="submit" disabled={!canSend}>Send</button>
        {isStreaming && <button type="button" onClick={stop}>Stop</button>}
      </form>
    </div>
  );
}

Options

Pass an options object to configure behavior:

const chat = useChatSession({
  client,              // optional -- uses ChatProvider context if omitted
  config,              // optional -- creates a client internally
  autoStart: true,     // default true; set false to defer session creation
  onMessage: (msg) => console.log(msg),
  onError: (err) => reportError(err),
  onStatusChange: (status) => analytics.track(status),
});

Return value

useChatClient

Access the ChatClient instance from ChatProvider context. Useful when you need to create sessions manually, inspect capabilities, or access identity and conversation APIs outside of useChatSession.

import { useChatClient } from 'gecx-chat/react';

function DebugPanel() {
  const client = useChatClient();
  const caps = client.getCapabilities();

  return <pre>{JSON.stringify(caps, null, 2)}</pre>;
}

Throws if called outside a <ChatProvider>.

useIdentity

Access and manage the current user's identity state.

import { useIdentity } from 'gecx-chat/react';

function UserBadge() {
  const { identity, upgradeToAuthenticated, signOut } = useIdentity();

  if (identity.type === 'guest') {
    return <button onClick={() => upgradeToAuthenticated({ jwt: token })}>Sign in</button>;
  }

  return (
    <div>
      <span>{identity.identityId}</span>
      <button onClick={() => signOut()}>Sign out</button>
    </div>
  );
}

Return value

useConversations

List, create, and manage conversation history. Requires <ChatProvider>.

import { useConversations } from 'gecx-chat/react';

function ConversationList() {
  const { conversations, create, remove } = useConversations();

  return (
    <ul>
      {conversations.map((c) => (
        <li key={c.id}>
          {c.title ?? 'Untitled'}
          <button onClick={() => remove(c.id)}>Delete</button>
        </li>
      ))}
      <button onClick={() => create()}>New conversation</button>
    </ul>
  );
}

Return value

Hooks reference

All hooks are imported from gecx-chat/react unless noted.

useSentiment and useIntent example

Pure selectors over chat.messages that surface sentiment and intent signals streamed by the signal subsystem. They re-run on every messages update and memoize internally.

import { useChatSession, useSentiment, useIntent } from 'gecx-chat/react';

function SentimentAwareUI() {
  const chat = useChatSession();
  const { latest: sentiment, byCategory } = useSentiment(chat.messages);
  const { byIntent } = useIntent(chat.messages);

  const polarity = sentiment?.polarity ?? 'neutral';
  return (
    <div data-polarity={polarity}>
      {byIntent.refund_request && <RefundCta />}
      {byCategory.frustration?.score && byCategory.frustration.score > 0.7 && <CalmDownBanner />}
    </div>
  );
}

Both hooks accept { historyLimit } (default 50). See sentiment-and-intent.md for adapter configuration and escalation rules.

Pre-built components

These are unstyled, accessible building blocks. Add your own CSS or wrap them in styled wrappers.

Wiring components to the hook

import {
  ChatSurface,
  MessageList,
  Composer,
  HandoffBanner,
} from 'gecx-chat/react';
import { useChatSession } from 'gecx-chat/react';

function Chat() {
  const chat = useChatSession();

  return (
    <ChatSurface brand="Acme" title="Support" status={chat.status}>
      <MessageList messages={chat.messages} emptyState="Ask us anything." />
      {chat.handoffStatus !== 'none' && (
        <HandoffBanner status={chat.handoffStatus} />
      )}
      <Composer
        input={chat.input}
        canSend={chat.canSend}
        isStreaming={chat.isStreaming}
        onSend={(text) => chat.sendText(text)}
        onStop={chat.stop}
      />
    </ChatSurface>
  );
}

What's next

• Custom Renderers -- override how any message part type renders.
• Messages & Parts -- every part type and its shape.
• Generative UI -- let the agent produce dynamic UI surfaces.
• Voice Integration -- voice: 'auto' and the React voice surface.
• Sentiment and Intent -- the signal hooks in practice.
• Memory -- useMemory and MemoryList.