Skip to content
API

@tanstack/ai-preact

Preact hooks for TanStack AI. To build your first chat, start with the Quick Start. For a typed chat layout, see Preact Chat UI.

Installation

shell
npm i @tanstack/ai-preact

useChat(options)

Holds the messages and the run state of one chat, and talks to your server route.

tsx
import { useState } from "preact/hooks";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-preact";

export function Chat() {
  const [input, setInput] = useState("");
  const { messages, sendMessage, isLoading } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
  });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          <strong>{message.role}:</strong>
          {message.parts.map((part, idx) =>
            part.type === "text" ? <span key={idx}>{part.content}</span> : null,
          )}
        </div>
      ))}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (input.trim() && !isLoading) {
            sendMessage(input);
            setInput("");
          }
        }}
      >
        <input
          value={input}
          onInput={(e) => setInput(e.currentTarget.value)}
        />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
    </div>
  );
}

Options

You must pass threadId. You must also pass connection or fetcher, not both.

OptionWhat it does
connectionConnection adapter, for example fetchServerSentEvents("/api/chat"). See Transports.
fetcherA function that returns a Response or a stream. Use it with server functions.
toolsClient tools from .client(). They run when the model calls them. See Client Tools.
threadIdRequired. The id of this chat. Use a stable id for each conversation, for example the id from your route.
initialMessagesThe messages to show first.
forwardedPropsJSON sent to the server in the AG-UI forwardedProps field, for example { model: "gpt-6.1-sol" }.
persistencetrue to load the thread from the server, or a storage adapter. See Chat Persistence.
outputSchemaA Standard Schema. In Preact it only labels the chat in devtools. Read structured output from the structured-output part in messages.
contextClient-only runtime context for client tools. It is not sent to the server.
liveSubscribe on mount and unsubscribe on unmount.
queueWhat sendMessage does while a run is busy. Default: queue the message. See Queueing.
interruptsDefinitions from defineInterrupt(). See Interrupts.
byok, byokProviderA keyring from defineByok(). See Bring Your Own Key.
devtoolsDisplay options for TanStack AI Devtools.

The hook also takes the ChatClient callbacks (onResponse, onChunk, onFinish, onError, onInterruptStateChange, onCustomEvent) and the other client options. See ChatClient options.

When forwardedProps, tools, context, or queue change, the hook updates the current chat.

Returns

State values are plain Preact values. The hook renders again when they change.

FieldWhat it is
messagesThe UIMessage array of the chat.
sendMessage(content, options?)Sends a user message. content is a string or { content, id?, metadata? }. options takes whenBusy and body.
isLoadingtrue while a response streams.
errorThe last error, or undefined.
status"ready", "submitted", "streaming", or "error".
stop()Stops the current response.
reload()Runs the last user message again.
append(message)Adds a UIMessage or ModelMessage and starts a run.
addToolResult(result)Gives the result of a client tool by hand: { toolCallId, tool, output, state?, errorText? }.
setMessages(messages), clear()Replace or clear the messages.
queue, cancelQueued(id)Messages that wait while a run is busy. See Queueing.
runIdThe id of the run in flight, or null.
interruptsPending interrupts. Each item has resolveInterrupt(...). See Interrupts.
resolveInterrupts, cancelInterrupts, retryInterrupts, resumeInterruptsUnsafeAct on all pending interrupts at once.
interruptErrors, resumingErrors from the last resume, and true while a resume runs.
isHydratingtrue while the chat loads from persistence.
hasOlderMessages, loadOlderMessages()Page in older messages. See Chat Persistence.
isSubscribed, connectionStatus, sessionGeneratingState of the live subscription.

Example: tool approval

A tool with needsApproval: true pauses the run. The pending call shows up in interrupts.

tsx
import { toolDefinition } from "@tanstack/ai";
import { useChat, fetchServerSentEvents } from "@tanstack/ai-preact";
import { z } from "zod";

const deleteFileTool = toolDefinition({
  name: "delete_file",
  description: "Delete a file",
  needsApproval: true,
  inputSchema: z.object({ path: z.string() }),
});

export function ChatWithApproval() {
  const { interrupts } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
    threadId: "support-chat",
    tools: [deleteFileTool],
  });

  return (
    <div>
      {interrupts.map((interrupt) =>
        interrupt.kind === "tool-approval" ? (
          <div key={interrupt.id}>
            <p>Approve: {interrupt.toolName}</p>
            <button onClick={() => interrupt.resolveInterrupt(true)}>
              Approve
            </button>
            <button onClick={() => interrupt.resolveInterrupt(false)}>
              Deny
            </button>
          </div>
        ) : null,
      )}
    </div>
  );
}

See Tool Approval for the server side.

createChatHook(options)

Binds chat options once at module scope and returns a useChat hook that uses them.

tsx
import { createChatHook, fetchServerSentEvents } from "@tanstack/ai-preact";

const { useChat: useSupportChat } = createChatHook({
  connection: fetchServerSentEvents("/api/chat"),
});

export function SupportScreen() {
  const chat = useSupportChat({ threadId: "support-1" });
  return <p>{chat.messages.length} messages</p>;
}

The bound hook takes these per-call overrides: threadId, initialMessages, live, and forwardedProps. Keep tools and interrupts on the factory options.

@tanstack/ai-preact/ui has its own createChatHook that also returns typed UI components. See Preact Chat UI.

Generation hooks

This package does not export generation hooks. Use GenerationClient or VideoGenerationClient, which this package re-exports. See GenerationClient.

Realtime chat

This package does not export a realtime hook. Use RealtimeClient, which this package re-exports. See Realtime Chat.

Audio recorder

This package does not export a recorder hook. Use AudioRecorder, which this package re-exports. See Audio Recording.

useByok(client)

Subscribes to a BYOK keyring and returns its snapshot. See Bring Your Own Key.

tsx
import { useByok } from "@tanstack/ai-preact";
import { byok } from "./byok";

export function KeyStatus() {
  const snapshot = useByok(byok);
  const openai = snapshot.status.openai;
  return <p>{openai && "masked" in openai ? openai.masked : "No key"}</p>;
}

The snapshot has status, locked, prompt, and storageError. Save a key from your own UI with byok.update(provider, value).

useMcpAppBridge(options)

Returns a stable MCP App bridge for one thread. It always calls the latest chat.sendMessage and onLink. Options: threadId, callEndpoint, chat, fetchImpl, onLink. See MCP Apps.

The MCPAppResource component, which renders a ui-resource part, is on the @tanstack/ai-preact/mcp-apps subpath.

useRegisterWebMCPTools(tools, options?)

Exposes client tools to the browser WebMCP API while the component is mounted. See WebMCP Tools.

tsx
import { useRegisterWebMCPTools } from "@tanstack/ai-preact";
import { searchProducts } from "./tools";

const tools = [searchProducts];

export function ProductsPage() {
  useRegisterWebMCPTools(tools, {
    onError: (error) => console.error(error),
  });
  return null;
}

Options: toolOptions, context, and onError. context is required when a tool declares a required runtime context. The hook registers the tools again when tools or options change, so keep them stable.

usePageWebMCPTools(options?)

Reads the WebMCP tools that the page registered, as client tools. The array starts empty and updates when the page adds or removes a tool. Pass it to useChat as tools. See Page WebMCP Tools in Chat.

tsx
import { usePageWebMCPTools } from "@tanstack/ai-preact";

export function useSameOriginPageTools() {
  return usePageWebMCPTools({
    filter: (tool) => tool.origin === location.origin,
  });
}

Options: filter (return false to skip a tool) and onError.

Re-exports from @tanstack/ai-client

You can import these from @tanstack/ai-preact directly. See @tanstack/ai-client for details.

GroupExports
Connection adaptersfetchServerSentEvents, fetchHttpStream, fetchJson, xhrServerSentEvents, xhrHttpStream, webSocket, stream, rpcStream
Typed optionscreateChatClientOptions, clientTools
PersistencelocalStoragePersistence, sessionStoragePersistence, indexedDBPersistence
ClientsChatClient, GenerationClient, VideoGenerationClient, RealtimeClient, AudioRecorder, InterruptManager
WebMCP and MCP AppsregisterWebMCPTools, getWebMCPTools, subscribeWebMCPTools, createMcpAppBridge
ErrorsUnsupportedResponseStreamError, StreamTruncatedError, DurableStreamIncompleteError, StreamReconnectLimitError, StorageUnavailableError
Stream helpersStreamProcessor, chunk strategies, parsePartialJSON, message converters

BYOK helpers (defineByok, defaultByokStorage, and more) are on the @tanstack/ai-preact/byok subpath.

Types

TypeWhat it is
UseChatOptions, UseChatReturnThe options and return value of useChat.
UIMessage<TTools>A chat message with typed parts.
InferChatMessages<T>The message type for a createChatClientOptions result.
SendMessageOptions, WhenBusy, QueueOption, QueuedMessageSend and queue types.
UseRegisterWebMCPToolsOptions, UsePageWebMCPToolsOptions, UseMcpAppBridgeOptionsOptions for the WebMCP and bridge hooks.

Pass a plain tools array to useChat or createChatClientOptions. Tool names, inputs, and outputs stay typed without as const. Import toolDefinition from @tanstack/ai.