assistant-ui: Composable chat primitives for React, backed by the AI SDK

The problem: every chat UX is different, and the default is hard to escape

Most chat libraries ship a single, opinionated component that looks and behaves like a stock chatbot. That works for a demo, but production teams usually need a specific layout, a particular way to render tool calls, or a brand that does not match the library's theme. assistant-ui addresses this by breaking the chat interface into primitives: Thread, Message, Composer, ThreadList, ActionBar, and others. The README says you can build any chat UX from these parts and style every pixel yourself. It is aimed at React developers who want the functionality of a ChatGPT-like interface, streaming, auto-scroll, retries, attachments, markdown, code highlighting, voice dictation, keyboard shortcuts, and accessibility, without being locked into a single visual design. The library is not a drop-in widget; it is a toolkit for constructing the interface you actually need.

How the runtime adapter layer works

The central mechanism is the runtime abstraction. The README shows a Chat component that creates a runtime with useChatRuntime from @assistant-ui/ai-sdk and passes it to AssistantRuntimeProvider. That runtime connects to the Vercel AI SDK out of the box. The same pattern extends to other backends: you swap useChatRuntime for useLangGraphRuntime, useDataStreamRuntime, or a custom runtime. The provider then feeds that runtime into the Thread component. This separation means the UI primitives do not care where the messages come from. The data flow is straightforward: the runtime handles the connection to the backend, manages message state, and exposes it to the React tree via the provider. The library also includes typed runtime APIs, tool schemas, and message parts, so the contract between the UI and the backend is explicit. If your backend is not one of the listed integrations, you must implement a custom runtime, which is a real cost but also the source of the flexibility.

Getting started: CLI scaffolding and direct package install

The README gives two installation paths. The fastest is the CLI: npx assistant-ui@latest create for a new Next.js project, or npx assistant-ui@latest init to add the styled components to an existing project. The CLI copies a starter theme into your project, in either Base UI (the default) or Radix UI flavor. Alternatively, you can install the packages directly with npm install @assistant-ui/react @assistant-ui/ai-sdk. The usage example shows a minimal setup: a client component that creates a runtime with useChatRuntime, wraps it in AssistantRuntimeProvider, and renders a Thread component. The Thread component is imported from a local path, @/components/assistant-ui/elements/thread.aui, which suggests the CLI generates a project-specific file. That is a notable detail: the starter is not a black-box library component but generated source code in your project, so you can modify it directly. The trade-off is that upgrades to the starter may not apply automatically to your customized copy.

Generative UI and safe frontend actions

Beyond plain text chat, assistant-ui claims support for generative UI: rendering tool calls and JSON as React components, collecting inline human approvals, and exposing safe frontend actions to the model. This is the most distinctive feature. Instead of showing raw tool output as text, you can register React components that render the results in a structured way. The phrase safe frontend actions implies a mechanism to let the model trigger UI actions without giving it arbitrary code execution. The README does not detail the security model, but the existence of a separate package called safe-content-frame in the releases suggests there is a sandboxing or isolation layer for rendering untrusted content. That is a point to verify before relying on it, because generative UI with model-controlled actions is exactly where security bugs appear. The library's approach is more flexible than a plain markdown renderer, but it also demands that you design and maintain those component mappings.

Backend support and the adapter matrix

The README lists integrations as separate packages: @assistant-ui/ai-sdk for Vercel AI SDK, @assistant-ui/react-langgraph and @assistant-ui/react-langchain for LangGraph and LangChain, @assistant-ui/react-ag-ui and @assistant-ui/react-a2a for AG-UI and A2A protocols, @assistant-ui/react-google-adk and @assistant-ui/react-opencode for Google ADK and OpenCode, and @assistant-ui/react-data-stream for custom data-stream backends. This is a wide net. Broad model support is claimed for OpenAI, Anthropic, Google Gemini, Mistral, Perplexity, AWS Bedrock, Azure, Fireworks, and Ollama, plus community providers via the AI SDK. The practical implication is that your choice of backend determines which package you install and which runtime hook you use. If you use a backend not covered by an adapter, you are on your own to write a custom runtime. The existence of a separate data-stream package suggests there is a documented protocol you can implement, but the README does not explain its format. That is a gap you need to fill by reading the docs.

A real limitation: the starter is a starting point, not a final product

The CLI copies a styled theme into your project, which is convenient but also a maintenance concern. Once you modify that generated code, which the library encourages, you own it. Upstream changes to the starter theme will not merge into your project automatically. You will need to track releases and manually reconcile changes if you want them. Another limitation is the complexity of the runtime abstraction. For a simple chat box with one backend, the adapter layer is overhead. The README's example is minimal, but the actual integration for a custom backend requires understanding the runtime contract, message parts, and tool schemas. That is not trivial. The library also has a commercial component, Assistant Cloud, for managed thread history, telemetry, and file storage. The README does not state pricing or the exact boundary between the open source and cloud features. If you need persistent thread history, you may be pushed toward a paid service or have to build that yourself. The MIT license covers the core, but the cloud offering is separate.

Alternatives and how they differ

The most direct alternative is to use the Vercel AI SDK alone, without assistant-ui. The AI SDK provides the model access and streaming primitives, but it does not ship a full chat UI. You would build the Thread, Composer, and message list yourself, which is exactly the problem assistant-ui solves. Another alternative is a monolithic chat widget like ChatUI or a commercial component library that gives you a complete, styled chat box with minimal configuration. Those are easier to start with but harder to customize deeply. LangChain's own UI offerings are less mature. The key difference in approach is that assistant-ui sits on top of the AI SDK and provides the UI layer, whereas the AI SDK alone leaves the UI entirely to you. If you want to avoid the adapter layer and own every component, the AI SDK plus your own components is simpler. If you want a head start on the UX without surrendering control, assistant-ui is the middle ground.

Maintenance, licensing, and what to check before adopting

The repository is under the MIT license, which permits commercial use and modification. The README mentions optional Assistant Cloud for managed persistence, so the open source core and the cloud service are distinct. Recent releases include safe-content-frame@0.0.28 and heat-graph@0.0.16, separate packages that suggest a modular ecosystem with its own release cadence. The main library is actively pushed as of August 2026, but the README does not specify a versioning policy or a migration guide for breaking changes. Before adoption, you should verify the current state of the docs for the custom runtime protocol, the exact security guarantees of the safe content frame, and how the generated starter code is meant to be upgraded. The CLI's init command is a one-time scaffold, not a package manager, so plan for manual updates to your customized components. The library is a solid choice for teams that want to build a distinctive chat interface without starting from zero, but it is not a zero-maintenance dependency.

Editorial conclusion

Adopt assistant-ui if you are building a React chat interface that must match your own design system, needs generative UI with tool calls, or requires streaming and attachments without writing them from scratch. Skip it if you want a single, ready-made chat widget with minimal integration effort, or if your team is not comfortable with the composable primitive model and the adapter layer it introduces. Before committing, verify that your backend fits one of the documented adapters, or that you are willing to write a custom runtime for the data-stream protocol. Check the current version of the CLI and the Base UI/Radix UI flavor it generates, since the starter code is copied into your project and will not auto-update.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes