# assistant-ui: a React chat UI toolkit built from composable primitives

> assistant-ui is an MIT-licensed TypeScript/React library for building chat interfaces, shipped as composable primitives plus runtime adapters. It fits teams that want ChatGPT-grade UX without inheriting a fixed component.

**assistant-ui/assistant-ui** — Project brief: Typescript/React Library for AI Chat. What you get Composable primitives: build any chat UX from Thread, Message, Composer, ThreadList, ActionBar, and friends.

- Repository: https://github.com/assistant-ui/assistant-ui
- Website: https://www.assistant-ui.com
- Stars: 12,362 · Forks: 1,216
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/assistant-ui-assistant-ui

## The problem assistant-ui solves: chat UX is repetitive and every product wants it slightly different

Streaming, auto-scroll, retries, attachments, markdown rendering, code highlighting, voice dictation, keyboard shortcuts and accessibility all have to exist before a chat panel feels finished. The README lists exactly those as production UX that ships out of the box. Most teams either rebuild them per project or adopt a monolithic chat widget and then fight it when the design changes.

assistant-ui takes the second path apart. Instead of one chat component, it exposes primitives: Thread, Message, Composer, ThreadList, ActionBar. You assemble the interface from those parts and style it yourself. The README frames the choice as "build any chat UX from Thread, Message, Composer, ThreadList, ActionBar, and friends", and the CLI copies a shadcn/ui theme into your project rather than importing a black-box one.

The audience is React and Next.js product teams that treat the chat surface as part of their own design system. If a drop-in widget is acceptable, the composition model is overhead you do not need.

## How the runtime and provider split keeps the backend out of the components

The architecture separates three layers. A runtime object holds conversation state and talks to your backend. AssistantRuntimeProvider puts that runtime into React context. The visual primitives read from the context, so Thread and Composer never know which server produced the messages.

The README shows the wiring in one snippet: useChatRuntime from @assistant-ui/ai-sdk creates a runtime that connects to the Vercel AI SDK, and the provider wraps a Thread component. Swapping backends means swapping the hook, not rewriting the UI. The README names useLangGraphRuntime and useDataStreamRuntime as drop-in alternatives, and lists separate packages for AG-UI, A2A, Google ADK, OpenCode, LangChain and LangGraph.

That split is why the same primitives can serve a plain HTTP endpoint and a graph-based agent. It also means the runtime adapter is the integration point to inspect first: if your backend does not match one of the listed adapters, you are writing a custom runtime, and the README only says that extension is possible, not how much work it is.

## Installing assistant-ui and rendering a first Thread

The README gives two CLI paths. One scaffolds a new Next.js app, the other adds the styled components to a project you already have. Run the create command in an empty directory when you want the full starter:

```bash
npx assistant-ui@latest create   # new project
```

The CLI prompts for a template and copies the styled components into your source tree, so the chat elements become files you own and can edit. For an existing project, the init command adds those components without scaffolding an app:

```bash
npx assistant-ui@latest init     # add to existing project
```

If you prefer to wire packages by hand, the README lists the two core installs:

```bash
npm install @assistant-ui/react @assistant-ui/ai-sdk
```

With the packages in place, a minimal chat component needs the provider and a thread. The README example imports Thread from the path the CLI generates, which is why running the CLI first matters:

```tsx
"use client";

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { Thread } from "@/components/assistant-ui/elements/thread.aui";

export function Chat() {
  const runtime = useChatRuntime();
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
}
```

After this renders, you should see the styled thread with a composer at the bottom. The monorepo's package.json sets engines.node to >=24, so check your local Node version before running the CLI if you plan to build from the repository rather than consume the published packages.

## Where assistant-ui is the wrong tool

The library is React-first, and the README's platform list is narrow. React Native and terminal (Ink) have their own packages, but there is no Angular or Vue entry. Teams searching for those integrations will not find them here, and nothing in the README suggests a framework-agnostic core you could wrap.

The second constraint is the CLI's ownership model. It copies a theme into your project, which is good for control and bad for upgrades: once those files are yours, pulling in a redesigned theme means diffing generated code against your edits. The README does not document a rollback or re-sync path for that.

The third is the runtime adapter. If your backend is a bespoke protocol, you are on the custom-runtime path. The README states that extension is easy but does not enumerate the runtime interface, so budget time for reading the API surface in the repository before assuming a weekend integration.

Finally, if you want a single component that renders a complete chat and you never intend to restyle it, the primitive model gives you nothing that a simpler widget would not.

## assistant-ui compared with the Vercel AI SDK and CopilotKit

People search for assistant-ui against the Vercel AI SDK, and the comparison is a category error worth clearing up. The AI SDK is the transport and model layer: it streams tokens and tool calls. assistant-ui is the rendering layer, and its @assistant-ui/ai-sdk package is an adapter that consumes what the AI SDK produces. The README's own example uses both at once, with useChatRuntime sitting on top of the AI SDK. They compose; they do not compete.

The CopilotKit comparison is closer to a real fork in the road. CopilotKit targets in-app copilots that act inside an existing product surface, with its own conventions for how the assistant reaches into application state. assistant-ui stays at the chat interface: primitives, a runtime, and adapters. If your product needs an assistant embedded across many screens with shared context, the copilot framing may fit better. If you are building a chat panel and want the markup to be yours, assistant-ui's composition model is the more direct answer. The README does not position itself against CopilotKit, so treat this as a design distinction rather than a claim from the project.

## Maintenance, release cadence and the MIT licence

The repository is not archived, and the last push was on 2026-08-27. Recent releases on the same date include safe-content-frame@0.0.28, heat-graph@0.0.16 and create-assistant-ui@0.0.76, which indicates a changesets-driven monorepo where individual packages version independently. The 0.0.x version numbers on those packages are worth reading literally: the CLI and the smaller helpers are still pre-1.0, so expect churn in their APIs even if the core React package is stable.

The monorepo's package.json shows the tooling around releases: changeset version for versioning, a changeset-semver check script, an api-surface check that generates and diffs the public API, and size budgets. Those checks suggest the maintainers treat public API changes as something to gate in CI, which is a reasonable signal for teams that pin versions.

Licensing is MIT, which permits commercial use, modification and redistribution with the licence text preserved. The README notes that Assistant Cloud is optional and covers managed thread persistence, telemetry and file storage. That is a separate commercial service, not part of the MIT grant, so if you enable it you are accepting its terms alongside the library's. Nothing here is legal advice; read the LICENSE file and the cloud terms before shipping.

## Conclusion

Adopt assistant-ui if you are building a React chat surface and want to own the markup and styling rather than accept a fixed widget, and if your backend already speaks the Vercel AI SDK, LangGraph, AG-UI, A2A, Google ADK or a plain data stream. Do not adopt it if you need a framework-agnostic chat component: the README lists React Native and Ink packages for other platforms, but there is no Angular or Vue package, so those related searches point at a gap rather than a feature. Before committing, verify that the runtime adapter you need exists for your backend, check whether the CLI's copied theme matches your design system, and read the MIT licence text plus the terms of any Assistant Cloud usage if you plan to store threads or telemetry there.

## FAQ

### What is assistant-ui?

It is an open-source TypeScript and React library for building AI chat interfaces. Rather than one chat component, it ships composable primitives such as Thread, Message, Composer, ThreadList and ActionBar, plus runtime adapters for different backends.

### How do I use assistant-ui in a React app?

Run npx assistant-ui@latest create for a new project or npx assistant-ui@latest init to add the styled components to an existing one, then wrap a Thread in AssistantRuntimeProvider with a runtime from a hook such as useChatRuntime.

### How does assistant-ui compare with the Vercel AI SDK?

They operate at different layers. The AI SDK handles model calls and streaming, while assistant-ui renders the chat interface and connects to the AI SDK through the @assistant-ui/ai-sdk package. The README's example uses both together.

### What is the best chat UI?

That depends on how much control you want. assistant-ui ships primitives such as Thread, Message and Composer plus production UX like streaming, retries and attachments, so you compose the interface instead of adopting a fixed widget.

## Sources

- [Official documentation](https://www.assistant-ui.com)
- [Official README](https://github.com/assistant-ui/assistant-ui#readme)
- [Project repository](https://github.com/assistant-ui/assistant-ui)
- [Release notes](https://github.com/assistant-ui/assistant-ui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/assistant-ui-assistant-ui