Guide · Open source

How to use assistant-ui: install, compose chat UI and connect a backend

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

assistant-ui is an open-source TypeScript and React library for building chat interfaces, like ChatGPT, inside your own web app. It is aimed at developers, mainly those working with React or Next.js, who want to add an AI chat panel to an existing product. After this guide you will know how to install it, how the main pieces fit together, and how to connect it to a backend.

assistant-uiassistant-ui/assistant-ui · ★ 12.9k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Node.js and npm, or another JavaScript package manager, are installed.
2Create or initialise the project. Run npx assistant-ui@latest create for a new project, or npx assistant-ui@latest init inside an existing one.
3Install the packages. If you are not using the CLI, run npm install @assistant-ui/react @assistant-ui/ai-sdk ai.
4Add the Thread component. Create a client component that calls useChatRuntime and wraps Thread in AssistantRuntimeProvider.
5Choose a backend. Keep the Vercel AI SDK adapter, or swap in the LangGraph, data-stream or custom runtime for your own server.
6Customise the UI. Restyle the copied components or compose your own from primitives such as Message and Composer.

Check the prerequisites before you install

You need Node.js and npm or another JavaScript package manager. The library is built for React and TypeScript, so a project that does not use React is not a good fit.

Node.js installed
npm or another JavaScript package manager
A React project, or a new Next.js app created by the CLI

Install assistant-ui in a new or existing project

The fastest path is the CLI. It can scaffold a Next.js app, or add the styled components to a project you already have.

If you prefer, you can install the packages directly with npm. The source lists these three packages for the core setup: the React library, the Vercel AI SDK adapter, and the ai package.

New project: run the create command
Existing project: run the init command
Manual install: install @assistant-ui/react, @assistant-ui/ai-sdk and ai

npx assistant-ui@latest create   # new project
npx assistant-ui@latest init     # add to existing project

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

Understand the building blocks

assistant-ui does not give you one monolithic chat component. You compose primitives such as Thread, Message, Composer, ThreadList and ActionBar into the chat UX you want.

The CLI copies a starter theme into your project in your choice of Base UI (the default) or Radix UI flavor. You can restyle it or replace it with your own design system or shadcn/ui components.

Thread: the conversation view
Message: a single message
Composer: the input box for sending messages
ThreadList and ActionBar: thread navigation and per-message actions

Wire up a runtime and render a chat

Your chat component gets a runtime and passes it to AssistantRuntimeProvider, which wraps the Thread. The example below uses useChatRuntime, which connects to the Vercel AI SDK out of the box.

To use a different backend, swap useChatRuntime for useLangGraphRuntime, useDataStreamRuntime, or a custom runtime. The source notes that LangGraph and LangChain, AG-UI and A2A, Google ADK, OpenCode, and custom data-stream backends each have their own package.

"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>
  );
}

Add tool-call rendering and approvals

The library can render tool calls and JSON as React components, collect inline human approvals, and expose safe frontend actions to the model. The source gives a get_weather example where a tool call is shown as a weather card.

Typed runtime APIs, tool schemas, message parts and adapters are typed end to end, which helps when your tools return structured data.

Render tool calls as custom components
Ask a user to approve an action inside the chat
Expose frontend actions to the model

What people use it for

Adding an AI chat panel to an existing React or Next.js product
Building a chat UI that matches a team's shadcn/ui or custom design system
Rendering a weather card or other tool output inside a chat reply
Asking a user to approve an action inline before the model continues
Connecting a chat UI to a LangGraph agent

Frequently asked questions

Is assistant-ui free to use?

assistant-ui is released under the MIT licence, as shown on its repository. Check the licence file in the repository for the full terms before you ship a product.

What do I need to run assistant-ui?

You need Node.js and npm or another JavaScript package manager. The project is a React and TypeScript library, so your app should use React.

How do I install assistant-ui?

Run npx assistant-ui@latest create for a new project or npx assistant-ui@latest init for an existing one. You can also run npm install @assistant-ui/react @assistant-ui/ai-sdk ai.

Can I use assistant-ui with LangGraph?

Yes. The source lists @assistant-ui/react-langgraph and @assistant-ui/react-langchain as backend packages, and useLangGraphRuntime is named as a swap-in option.

Is assistant-ui a finished chat app I can deploy without code?

No. It is a library for developers. You write a component that composes the primitives and connects them to a backend.

What are the alternatives to assistant-ui?

The source lists CopilotKit, Vercel AI SDK UI and chatscope/chat-ui-kit-react as comparable projects. Compare them on whether you need composable primitives or a single ready-made component.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose assistant-ui if you are a React or Next.js developer who wants a chat interface you can style with your own design system and connect to the Vercel AI SDK, LangGraph or your own backend. Pick something else if you want a finished chat app with no coding, if your project does not use React, or if you need a single drop-in component with no customisation.

Install options & downloads