assistant-ui
Always consult assistant-ui.com/llms.txt for latest API.
React library for building AI chat interfaces with composable primitives.
References
- •./references/architecture.md -- Core architecture and layered system
- •./references/packages.md -- Package overview and selection guide
When to Use
| Use Case | Best For |
|---|---|
| Chat UI from scratch | Full control over UX |
| Existing AI backend | Connects to any streaming backend |
| Custom message types | Tools, images, files, custom parts |
| Multi-thread apps | Built-in thread list management |
| Production apps | Cloud persistence, auth, analytics |
Architecture
code
┌─────────────────────────────────────────────────────────┐
│ UI Components (Primitives) │
│ ThreadPrimitive, MessagePrimitive, ComposerPrimitive │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────┐
│ Context Hooks │
│ useAssistantApi, useAssistantState, useAssistantEvent │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────┐
│ Runtime Layer │
│ AssistantRuntime → ThreadRuntime → MessageRuntime │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────┐
│ Adapters/Backend │
│ AI SDK · LangGraph · Custom · Cloud Persistence │
└─────────────────────────────────────────────────────────┘
Pick a Runtime
code
Using AI SDK? ├─ Yes → useChatRuntime (recommended) └─ No ├─ External state (Redux/Zustand)? → useExternalStoreRuntime ├─ LangGraph agent? → useLangGraphRuntime ├─ AG-UI protocol? → useAgUiRuntime ├─ A2A protocol? → useA2ARuntime └─ Custom API → useLocalRuntime
Core Packages
| Package | Purpose |
|---|---|
@assistant-ui/react | UI primitives & hooks |
@assistant-ui/react-ai-sdk | Vercel AI SDK v6 adapter |
@assistant-ui/react-langgraph | LangGraph adapter |
@assistant-ui/react-markdown | Markdown rendering |
@assistant-ui/styles | Pre-built CSS |
assistant-stream | Streaming protocol |
assistant-cloud | Cloud persistence |
Quick Start
tsx
import { AssistantRuntimeProvider, Thread } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
function App() {
const runtime = useChatRuntime({
transport: new AssistantChatTransport({ api: "/api/chat" }),
});
return (
<AssistantRuntimeProvider runtime={runtime}>
<Thread />
</AssistantRuntimeProvider>
);
}
State Access
tsx
import { useAssistantApi, useAssistantState } from "@assistant-ui/react";
const api = useAssistantApi();
api.thread().append({ role: "user", content: [{ type: "text", text: "Hi" }] });
api.thread().cancelRun();
const messages = useAssistantState(s => s.thread.messages);
const isRunning = useAssistantState(s => s.thread.isRunning);
Related Skills
- •
/setup- Installation and configuration - •
/primitives- UI component customization - •
/runtime- State management deep dive - •
/tools- Tool registration and UI - •
/streaming- Streaming protocols - •
/cloud- Persistence and auth - •
/thread-list- Multi-thread management - •
/update- Version updates and migrations