@aiconnect/react

@aiconnect/react holds the AiConnect client for a React tree, renders the connect window, and runs chats on the visitor's AI. It needs React 19 or later.

The tables on this page are generated from the package's TypeScript source each time the docs are built. Open a row to see its full type. The types of @aiconnect/core they name are in the core reference.

import { AiConnectProvider, builtInMessages, useAiChat, useAiConnect } from '@aiconnect/react';
import type {
  AiConnectProviderProps, ChatTurn, Locale, PickerMessages, ToolActivity, UseAiChatOptions,
} from '@aiconnect/react';
import '@aiconnect/react/styles.css';

styles.cssCopy Anchor Link

import '@aiconnect/react/styles.css';

The connect window's stylesheet, with the --aic-* tokens of @aiconnect/design included. Import it once. The theming guide lists the tokens.

AiConnectProviderCopy Anchor Link

Holds the AiConnect client for a React tree and renders the connect window when it is open.

The provider reads the client's state with useSyncExternalStore. The server render and the hydration see { status: 'checking' }, and the browser's state follows. The connect window closes on its own when the state becomes connected.

AiConnectProviderPropsCopy Anchor Link

• client. The AiConnect client. Create one per page and keep it stable across renders.
• locale. The language of the built in messages: one of the locales. The default is en.
• messages. Your own copy for the window. When given, it replaces the built in messages of locale as a whole.
• children. Your app. The connect window renders right after it, inside the provider's position in the page.

const client = new AiConnect();

export function Root() {
  return (
    <AiConnectProvider client={client} locale="fr">
      <App />
    </AiConnectProvider>
  );
}

useAiConnectCopy Anchor Link

Reads the connection and controls the connect window. It throws "useAiConnect must be used inside AiConnectProvider" outside the provider.

It returns this value. Its type is not exported.

• client. The client given to the provider, for connect(), disconnect() and subscribe().
• state. The current ConnectionState.
• messages. The messages the window uses now.
• isPickerOpen, openPicker, closePicker. Whether the connect window is open, and the functions that open and close it.

The connect window shows the step that matches the state: a search for the wallet in checking, the install text and the button to the AI Wallet page in noWallet, the connect button in disconnected, a waiting step while the wallet's window is open in connecting, and the reason with a retry button in error. Its help link shows what connecting means for the visitor. Escape and a click on the backdrop close it.

function AiModeButton() {
  const { state, openPicker } = useAiConnect();
  if (state.status === 'connected') {
    return <span>Answered by your {state.providerName} account</span>;
  }
  return <button type="button" onClick={openPicker}>AI mode</button>;
}

useAiChatCopy Anchor Link

A conversation with the visitor's own model, using your tools.

It returns this value:

• turns. One entry per question, updated as the answer streams and the tools run.
• send(question). Trims the question and runs a conversation on it with the whole transcript so far, tool results included. It does nothing when the site is not connected or the question is blank. Calls are not queued, so disable your send button while busy is true. A conversation that fails or is stopped leaves the transcript as it was, and its turn stays in turns.
• stop(). Aborts the running conversation. The wallet stops the answer, the turn keeps the text streamed so far, and error stays empty.
• reset(). Aborts the running conversation, clears the turns, the error and the transcript, and starts again from the current system.
• busy. True while a conversation runs.
• error. The message of the last failed conversation, cleared by the next send and by reset.
• connected. True when the connection state is connected.

The hook must render inside AiConnectProvider. It reads system when it first renders and on reset(). Pass a tools instance that stays the same across renders, created at module level or with useMemo.

const tools = new McpToolSource('/api/mcp', 'Bookshop');

function Chat() {
  const { turns, send, stop, busy, error } = useAiChat({ system: 'You recommend books from this catalog.', tools });
  return (
    <>
      {turns.map((turn, index) => <p key={index}>{turn.answer}</p>)}
      {error ? <p role="alert">{error}</p> : null}
      <button type="button" disabled={busy} onClick={() => send('A calm book for tonight')}>Ask</button>
      {busy ? <button type="button" onClick={stop}>Stop</button> : null}
    </>
  );
}

UseAiChatOptionsCopy Anchor Link

• system. The system prompt at the head of the transcript.
• tools. The tool source, such as an McpToolSource. Without it, the model answers each question once.

const options: UseAiChatOptions = { system: SYSTEM_PROMPT, tools: new McpToolSource('/api/mcp') };

ChatTurn and ToolActivityCopy Anchor Link

ChatTurnCopy Anchor Link

ToolActivityCopy Anchor Link

• question. The visitor's question, trimmed.
• answer. The text the model streamed during the turn, across every step of the tool loop.
• tools. Each tool call of the turn in order, as a ToolActivity. Its result is null while the tool runs, then holds the raw text the tool returned, or Tool error: followed by the reason.

function ToolStatus({ turn }: { turn: ChatTurn }) {
  const running: ToolActivity | undefined = turn.tools.find((activity) => activity.result === null);
  return running ? <p role="status">Running {running.call.name}…</p> : null;
}

builtInMessagesCopy Anchor Link

The connect window's copy, one set of PickerMessages per locale:

Spread one of them to change a few strings:

const messages: PickerMessages = { ...builtInMessages.en, connectButton: 'Use my AI', title: 'AI mode' };

export function Root() {
  return (
    <AiConnectProvider client={client} messages={messages}>
      <App />
    </AiConnectProvider>
  );
}

LocaleCopy Anchor Link

The keys of builtInMessages:

const locale: Locale = document.documentElement.lang === 'he' ? 'he' : 'en';

PickerMessagesCopy Anchor Link

builtInMessages.en holds the English text of each key. In the error state the step text is the wallet's own message, which is in English.

const messages: PickerMessages = {
  ...builtInMessages.en,
  title: 'Turn on AI mode',
  connectText: 'Your AI Wallet account answers the questions you ask on this site.',
};