Assistant UI

assistant-ui — React components for building AI chat interfaces. Use when building a chat UI (thread list, message composer, markdown rendering, tool-call parts, streaming), wiring it to a model runtime (Vercel AI SDK, LangChain, custom), using the CLI to scaffold and add components, adapting a shadcn/Radix/Base UI style, or running it on web, React Native, or the terminal. Published by HardGraph, a curated graph of provenance-backed knowledge for AI agents.

aichatreactuistreaming

Understand Assistant UI before using it

WHAT IT COVERS

START HERE WHEN

Your work repeatedly involves one or more of these concepts. Open the full procedure below when the current task matches them.

aichatreactuistreaming

Compare related skills

SKILL	CATEGORY	SHARED CONCEPTS	EXPLANATION
Assistant UI	AI and agents	Current skill	assistant-ui — React components for building AI chat interfaces. Use when building a chat UI (thread list, message composer, markdown rendering, tool-call parts, streaming), wiring it to a model runtime (Vercel AI SDK, LangChain, custom), using the CLI to scaffold and add components, adapting a shadcn/Radix/Base UI style, or running it on web, React Native, or the terminal. Published by HardGraph, a curated graph of provenance-backed knowledge for AI agents.
AI SDK	AI and agents	aistreaming	Vercel AI SDK — provider-agnostic TypeScript toolkit for building streaming AI applications and agents. Use when generating or streaming text with LLMs, wiring model providers (OpenAI, Anthropic, Google), implementing tool calling, producing structured output with Zod, building chat UIs with useChat, or composing multi-step agents with ToolLoopAgent. Published by HardGraph, a curated graph of provenance-backed knowledge for AI agents.
Composio	AI and agents	Same category	Composio — a tool-calling platform that sits between an LLM/agent framework and external apps, giving an agent connected tools, managed authentication, tool search, triggers, a sandboxed workbench, and an MCP bridge. Use when an agent needs to take real actions in 1000+ SaaS/developer apps (Gmail, GitHub, Slack, Notion, Linear, etc.) without hand-writing each integration, when you want OAuth/API-key auth handled per connected account, when you need the same tools reachable over Model Context Protocol, or when wiring tools into OpenAI, Anthropic, LangChain, Autogen, CrewAI, LlamaIndex, Mastra, or the Vercel AI SDK.
Mastra	AI and agents	Same category	TypeScript framework for building AI agents, deterministic workflows, and RAG pipelines on a shared storage and observability layer. Use when choosing between an agent loop and a workflow graph, wiring memory or retrieval into an agent, picking a storage or vector backend, or deploying a Mastra app to a serverless target or standalone server.

assistant-ui

What is HardGraph? HardGraph publishes curated, provenance-backed agent skills grounded in reproducible vendor documentation.

assistant-ui is a set of React components and runtimes for building AI chat interfaces. It gives you the hard parts of a chat UI — a thread of messages, composer, streaming, markdown, code blocks, tool-call rendering, attachments — as primitives you compose, styled to match a shadcn / Radix UI / Base UI design.

Mental model

Three layers:

| Layer | What it is | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Components | <Thread>, <Composer>, message parts, and the registry. Copied into your project and owned by you. | | Runtime | The adapter that feeds messages to the UI. useExternalStoreRuntime, useChatRuntime, or an AI SDK / LangChain runtime. | | Cloud services (optional) | Hosted services for assistants, evals, and sync. Not required to run locally. |

The UI is a consumer of a runtime. Swap the runtime to change the model or transport; the components stay the same.

Resolving versions

Resolve the current version from the registry, not memory.

npm view @assistant-ui/react version

Components are added via the CLI and live in your codebase, so the registry version is the runtime/primitives package; the components themselves move with your project.

Scaffolding

Use the CLI to create a project and add components:

npx assistant-ui init
npx assistant-ui add thread composer

add copies the component source into your repo (like shadcn), so you can edit it directly. Re-running add for the same component overwrites your local copy — review the diff before accepting.

Runtimes

A runtime implements the message-store protocol the components read. The most flexible entry point is useExternalStoreRuntime, which lets you drive messages from any source:

import { useExternalStoreRuntime, Thread } from "@assistant-ui/react";

const runtime = useExternalStoreRuntime({
  messages: myMessages,
  onNew: async (message) => sendToModel(message),
});

return <Thread runtime={runtime} />;

For Vercel AI SDK integrations, use the AI SDK runtime so useChat-style streaming maps directly onto assistant-ui's message parts.

Message parts

Messages are part-based, mirroring the AI SDK UIMessage model. Render by part type — text, tool-call, image, file — rather than treating a message as one string. Tool-call parts have states (input-available, output-available, running) so the UI can show progress.

Styling

The registry serves components in shadcn, Radix UI, and Base UI flavors. Pick the flavor that matches your design system; the CLI wires the correct primitives. All styling is Tailwind-based and editable in place.

Current vs deprecated

.md is the canonical docs URL suffix; .mdx is a backwards-compatible alias for agents that request source-style URLs — both return the same markdown.
Prefer the AI SDK runtime over hand-rolled streaming adapters when integrating with useChat.
Use the DevTools to inspect runtime state, context, and events during development.