Chat - State and store

Manage chat state with controlled and uncontrolled props on ChatProvider and a normalized internal store.

ChatProvider is the single entry point for the core runtime. It creates the chat store, wires the adapter, and makes hooks and selectors available to every descendant component.

The following demo shows controlled state in action:

Configuring the runtime

Required

Controlled and uncontrolled state

Each public state model supports both controlled and uncontrolled modes. Use default* props to let the runtime own the value, or pass the value directly to control it from React state.

Callbacks

Configuration

Controlled vs uncontrolled

Start uncontrolled

When prototyping or when the runtime can own the data, use default* props:

<ChatProvider
  adapter={adapter}
  initialActiveConversationId="support"
  initialMessages={initialMessages}
>
  <MyChat />
</ChatProvider>

The runtime manages the state internally and feeds it to hooks automatically.

Move to controlled

When you need to own the data externally—for example, to sync with a global store or persist across navigation—pass the state directly:

const [messages, setMessages] = React.useState<ChatMessage[]>([]);
const [activeId, setActiveId] = React.useState<string | undefined>('support');

<ChatProvider
  adapter={adapter}
  messages={messages}
  onMessagesChange={setMessages}
  activeConversationId={activeId}
  onActiveConversationChange={setActiveId}
>
  <MyChat />
</ChatProvider>;

The runtime still streams, normalizes, and derives selectors—you own the source of truth.

You can switch from uncontrolled to controlled at any time without changing the runtime model.

Normalized internal state

The store keeps data in a normalized shape for efficient streaming and updates:

This normalization is why streaming updates are efficient—updating one message does not require rebuilding the entire thread array.

Error model

Runtime errors use the ChatError type:

interface ChatError {
  code: string; // machine-readable error code
  message: string; // human-readable description
  source: ChatErrorSource; // where the error originated
  recoverable: boolean; // whether the runtime can continue
  retryable?: boolean; // whether the failed operation can be retried
  details?: Record<string, unknown>; // additional context
}

type ChatErrorSource = 'send' | 'stream' | 'history' | 'render' | 'adapter';

Errors surface through:

• useChat().error
• useChatStatus().error
• onError callback on ChatProvider

Callbacks

onToolCall

Fires when a tool invocation state changes during streaming. Use it for side effects outside the message list—logging, analytics, or triggering external workflows.

interface ChatOnToolCallPayload {
  toolCall: ChatToolInvocation | ChatDynamicToolInvocation;
}

onFinish

Fires when a stream reaches a terminal state (success, abort, disconnect, or error).

interface ChatOnFinishPayload {
  message: ChatMessage; // the assistant message
  messages: ChatMessage[]; // all messages after the stream
  isAbort: boolean; // user stopped the stream
  isDisconnect: boolean; // stream disconnected unexpectedly
  isError: boolean; // stream ended with an error
  finishReason?: string; // backend-provided reason
}

onData

Fires when a data-* chunk arrives. Use it for transient data that should trigger app-level side effects without being persisted in the message.

Registering part renderers

Register custom renderers for message part types through the partRenderers prop:

const renderers: ChatPartRendererMap = {
  'ticket-summary': ({ part }) => <div>Ticket: {part.ticketId}</div>,
};

<ChatProvider adapter={adapter} partRenderers={renderers}>
  <MyChat />
</ChatProvider>;

Registered renderers are available through useChatPartRenderer(partType) inside any descendant component.

Providing a custom store class

For advanced use cases, pass a custom store class via the storeClass prop. The class must satisfy ChatStoreConstructor<Cursor>:

interface ChatStoreConstructor<Cursor = string> {
  new (parameters: ChatStoreParameters<Cursor>): ChatStore<Cursor>;
}

Use this when you need to override internal normalization, add computed state, or integrate with an external store.

See also

• Hooks for the full hook API reference.
• Selectors for store selectors and advanced subscriptions.
• Controlled state for the controlled model pattern in action.
• Streaming lifecycle for send, stream, stop, and retry callbacks.

API

• ChatRoot