Open History to see the last commit
@tanstack/ai-react#
React hooks for building AI chat interfaces with TanStack AI.
Installation#
npm install @tanstack/ai-react @tanstack/ai
useChat Hook#
The useChat hook manages chat state, handles streaming responses, and provides a complete chat interface in a single hook.
Design Philosophy (v5 API):
- You control input state
- Just call
sendMessage()when ready - No form-centric API - use buttons, keyboard events, or any trigger
- More flexible and less opinionated
Basic Usage#
import { useChat } from "@tanstack/ai-react";
import { useState } from "react";
function ChatComponent() {
const { messages, sendMessage, isLoading } = useChat({
api: "/api/chat",
});
const [input, setInput] = useState("");
const handleSend = () => {
sendMessage(input);
setInput("");
};
return (
<div>
{messages.map((m) => (
<div key={m.id}>
<strong>{m.role}:</strong> {m.content}
</div>
))}
<input
value={input}
onChange={(e) => setInput(e.target.value)}
onKeyDown={(e) => e.key === "Enter" && handleSend()}
disabled={isLoading}
/>
<button onClick={handleSend} disabled={isLoading || !input.trim()}>
Send
</button>
</div>
);
}
API#
Options#
interface UseChatOptions {
api?: string; // API endpoint (default: "/api/chat")
initialMessages?: ChatMessage[]; // Starting messages
id?: string; // Unique chat ID
onResponse?: (response: Response) => void;
onChunk?: (chunk: StreamChunk) => void;
onFinish?: (message: ChatMessage) => void;
onError?: (error: Error) => void;
headers?: Record<string, string> | Headers;
body?: Record<string, any>; // Extra data to send
credentials?: "omit" | "same-origin" | "include";
fetch?: typeof fetch; // Custom fetch implementation
}
Return Value#
interface UseChatReturn {
messages: ChatMessage[]; // Current conversation
sendMessage: (content: string) => Promise<void>; // Send a message
append: (message) => Promise<void>; // Add message programmatically
reload: () => Promise<void>; // Reload last response
stop: () => void; // Stop current generation
isLoading: boolean; // Is generating a response
error: Error | undefined; // Current error
setMessages: (messages) => void; // Set messages manually
clear: () => void; // Clear all messages
}
Backend Endpoint#
Your backend should:
- Receive POST requests with this body:
{
messages: Message[];
data?: Record<string, any>;
}
- Stream back
StreamChunkobjects as newline-delimited JSON or Server-Sent Events:
data: {"type":"content","delta":"Hello","content":"Hello",...}
data: {"type":"content","delta":" world","content":"Hello world",...}
data: {"type":"done","finishReason":"stop","usage":{...}}
Advanced Usage#
With Callbacks#
const { messages, sendMessage } = useChat({
api: "/api/chat",
onChunk: (chunk) => {
if (chunk.type === "content") {
console.log("New token:", chunk.delta);
}
},
onFinish: (message) => {
console.log("Final message:", message);
// Save to database, log analytics, etc.
},
onError: (error) => {
console.error("Chat error:", error);
// Show toast notification, log error, etc.
},
});
// Send messages programmatically
await sendMessage("Tell me a joke");
Flexible Triggering#
const { sendMessage, isLoading } = useChat({ api: "/api/chat" });
const [input, setInput] = useState("");
// Button click
<button onClick={() => sendMessage(input)}>Send</button>
// Enter key
<input onKeyDown={(e) => e.key === "Enter" && sendMessage(input)} />
// Voice input
<button onClick={async () => {
const transcript = await voiceToText();
sendMessage(transcript);
}}>π€ Speak</button>
// Predefined prompts
<button onClick={() => sendMessage("Explain quantum computing")}>
Ask about quantum computing
</button>
With Custom Headers#
const chat = useChat({
api: "/api/chat",
headers: {
Authorization: `Bearer ${token}`,
"X-Custom-Header": "value",
},
body: {
userId: "123",
sessionId: "abc",
},
});
Programmatic Control#
const { messages, sendMessage, append, reload, stop, clear } = useChat();
// Send a simple message
await sendMessage("Hello!");
// Add a message with more control
await append({
role: "user",
content: "Hello!",
id: "custom-id",
});
// Reload the last AI response
await reload();
// Stop the current generation
stop();
// Clear all messages
clear();
Multiple Chats#
function App() {
const chat1 = useChat({ id: "chat-1", api: "/api/chat" });
const chat2 = useChat({ id: "chat-2", api: "/api/chat" });
// Each hook manages independent state
}
Example Backend (Node.js/Express)#
import express from "express";
import { AI, toStreamResponse } from "@tanstack/ai";
import { OpenAIAdapter } from "@tanstack/ai-openai";
const app = express();
app.use(express.json());
const ai = new AI(new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }));
app.post("/api/chat", async (req, res) => {
const { messages } = req.body;
// One line to create streaming response!
const stream = ai.streamChat({
model: "gpt-3.5-turbo",
messages,
});
const response = toStreamResponse(stream);
// Copy headers and stream to Express response
response.headers.forEach((value, key) => {
res.setHeader(key, value);
});
const reader = response.body?.getReader();
if (reader) {
while (true) {
const { done, value } = await reader.read();
if (done) break;
res.write(value);
}
}
res.end();
});
app.listen(3000);
Example Backend (Next.js App Router)#
// app/api/chat/route.ts
import { AI, toStreamResponse } from "@tanstack/ai";
import { OpenAIAdapter } from "@tanstack/ai-openai";
export const runtime = "edge";
const ai = new AI(new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }));
export async function POST(req: Request) {
const { messages } = await req.json();
// One line!
return toStreamResponse(
ai.streamChat({
model: "gpt-3.5-turbo",
messages,
})
);
}
Example Backend (TanStack Start)#
import { createFileRoute } from "@tanstack/react-router";
import { AI, toStreamResponse } from "@tanstack/ai";
import { AnthropicAdapter } from "@tanstack/ai-anthropic";
const ai = new AI(
new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY })
);
export const Route = createFileRoute("/api/chat")({
server: {
handlers: {
POST: async ({ request }) => {
const { messages } = await request.json();
// One line with automatic tool execution!
return toStreamResponse(
ai.streamChat({
model: "claude-3-5-sonnet-20241022",
messages,
tools, // Tools with execute functions
maxIterations: 5,
})
);
},
},
},
});
TypeScript Types#
All types are fully exported:
import type {
ChatMessage,
UseChatOptions,
UseChatReturn,
ChatRequestBody,
} from "@tanstack/ai-react";
Features#
- β Automatic message state management
- β Streaming response handling
- β Loading and error states
- β
Simple
sendMessage()API (v5 style) - β You control input state (flexible)
- β Abort/stop generation
- β Reload last response
- β Clear conversation
- β Custom headers and body data
- β Callback hooks for lifecycle events
- β Multiple concurrent chats
- β Full TypeScript support
License#
MIT