assistant-ui

assistant-ui (@assistant-ui/react) is an open-source TypeScript/React library for building the kind of chat UX users expect from ChatGPT-style products, without locking you into a single monolithic chat widget. Instead of one big component, it ships composable primitives — Thread, Message, Composer, ThreadList, ActionBar, BranchPicker, and more — that you assemble and restyle however you like, backed by a headless runtime that handles streaming, auto-scroll, retries, attachments, markdown rendering, and generative UI (rendering tool calls as real React components with inline human approval).

A CLI (assistant-ui@latest create / init) scaffolds a Next.js app or drops styled shadcn/ui components into an existing project, while the runtime itself is backend-agnostic: @assistant-ui/react connects to the Vercel AI SDK, LangGraph, LangChain, AG-UI/A2A protocols, Google ADK, or any custom HTTP/data-stream backend through swappable adapter packages. It is used in production by teams like Mastra, LangChain, and Browser Use, and is backed by Y Combinator.

What You Get

• A full set of composable chat primitives (Thread, Message, Composer, ThreadList, ActionBar, BranchPicker, Attachment) you compose and restyle rather than a single fixed widget
• A backend-agnostic runtime layer with first-party adapters for the Vercel AI SDK, LangGraph, LangChain, AG-UI/A2A, Google ADK, and custom data-stream backends
• Production chat UX handled for you: streaming responses, auto-scroll, retries, file/image attachments, markdown rendering with syntax highlighting, and keyboard shortcuts
• Generative UI support — render tool calls and structured JSON as real React components, including inline human-in-the-loop approval flows
• A CLI that scaffolds a new Next.js app or adds a styled shadcn/ui-based starter (Base UI or Radix flavor) into an existing project

Common Use Cases

• Adding a ChatGPT-style assistant UI to an existing React or Next.js product
• Building a custom internal AI tool where the team wants full control over chat styling and layout
• Wiring a chat frontend to an agentic backend (LangGraph, LangChain, or a custom tool-calling API) via a purpose-built runtime adapter
• Building generative-UI experiences where the model’s tool calls render as interactive React components instead of raw text
• Prototyping AI product UX quickly with the CLI-scaffolded starter, then progressively restyling individual primitives

Under The Hood

Architecture assistant-ui is a pnpm/Turborepo monorepo that separates a framework-agnostic runtime core (@assistant-ui/core, @assistant-ui/store) from framework bindings (@assistant-ui/react, plus Vue, Svelte, and React Native packages) and a layer of headless UI primitives (src/primitives/* — thread, composer, message, actionBar, branchPicker, attachment) built on top of that runtime. The react package itself is mostly a re-export surface over @assistant-ui/store and @assistant-ui/core, plus a legacy-runtime directory that preserves backward compatibility for older runtime APIs, and adapter integrations (LangGraph, LangChain, AI SDK, AG-UI, Google ADK) live as separate packages that plug into the same runtime contract rather than being hardcoded into the core. This separation means swapping backends is a matter of swapping the runtime adapter, not rewriting UI code, and the primitives can be restyled or replaced independently of the state layer they read from.

Tech Stack The project is TypeScript-first across a large pnpm workspace of 40+ packages, built with a custom internal build tool (@assistant-ui/x-buildutils, invoked as aui-build) and orchestrated by Turborepo. Linting and formatting run through oxlint/oxfmt rather than ESLint/Prettier, tests run on Vitest (with a dedicated Vite plugin, @assistant-ui/vite), and the docs site is a Next.js app under apps/docs. The runtime integrates with the Vercel AI SDK, LangChain/LangGraph, and multiple model providers (OpenAI, Anthropic, Google Gemini, Mistral, AWS Bedrock, Azure, Fireworks, Ollama) without hardcoding any of them into the core package.

Code Quality The monorepo carries an extensive Vitest test suite spread across nearly every package (runtime adapters, message conversion helpers, streaming/timing logic, and UI primitives all have colocated *.test.ts(x) files), plus dedicated CI workflows for code quality, performance regression (perf.yaml, perf-nightly.yaml), and per-ecosystem publishing (npm and PyPI). Source is strictly typed TypeScript with oxlint enforcement, changesets-driven versioning, and a size-budget check (size-budgets.json) that guards bundle size in CI — the kind of guardrails expected of a library with a very high release cadence.

API Design The public API favors composable primitives over configuration objects — consumers import Thread.Root, Composer.Input, Message.Content, etc. and assemble their own component tree, which keeps the surface area explicit and typed end-to-end (runtime state, tool schemas, message parts, and adapters all share consistent typed contracts). The tradeoff is more upfront assembly than a single drop-in <ChatWidget />, offset by the CLI-scaffolded starter that gives new users a working, styled reference implementation to start customizing from immediately.