# Architecture
URL: /docs/architecture

How components, runtimes, and cloud services fit together.

import { Sparkles, PanelsTopLeft, Database, Terminal } from "lucide-react";

assistant-ui is built on these main pillars: \[#assistant-ui-is-built-on-these-main-pillars]

<div className="grid grid-cols-1 md:grid-cols-3 gap-4">
  <Card title="1. Frontend components">
    Shadcn UI chat components with built-in state management
  </Card>

  <Card title="2. Runtime">
    State management layer connecting UI to LLMs and backend services
  </Card>

  <Card title="3. Assistant Cloud">
    Hosted service for thread persistence, history, and user management
  </Card>
</div>

1. Frontend components \[#1-frontend-components]

Stylized and functional chat components built on top of Shadcn components that have context state management provided by the assistantUI runtime provider. These pre-built React components come with intelligent state management. [View our components](/docs/ui/thread)

2. Runtime \[#2-runtime]

A React state management context for assistant chat. The runtime handles data conversions between the local state and calls to backends and LLMs. We offer different runtime solutions that work with various frameworks like Vercel AI SDK, LangGraph, LangChain, Helicone, local runtime, and an ExternalStore when you need full control of the frontend message state. [You can view the runtimes we support](/docs/runtimes/pick-a-runtime)

3. Assistant Cloud \[#3-assistant-cloud]

A hosted service that enhances your assistant experience with comprehensive thread management and message history. Assistant Cloud stores complete message history, automatically persists threads, supports human-in-the-loop workflows, and integrates with common auth providers to seamlessly allow users to resume conversations at any point. [Cloud Docs](/docs/cloud/overview)

There are three common ways to architect your assistant-ui application: \[#there-are-three-common-ways-to-architect-your-assistant-ui-application]

1. Direct Integration with External Providers \[#1-direct-integration-with-external-providers]

<Mermaid chart="graph TD\n    A[Frontend Components] --> B[Runtime]\n    B --> D[External Providers or LLM APIs]\n    \n    \n    classDef default color:#f8fafc,text-align:center\n    \n    style A fill:#e879f9,stroke:#2e1065,stroke-width:2px,color:#2e1065,font-weight:bold\n    style B fill:#93c5fd,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a,font-weight:bold\n    style D fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold\n    \n    class A,B,C,D,E default" />

2. Using your own API endpoint \[#2-using-your-own-api-endpoint]

<Mermaid chart="graph TD\n    A[Frontend Components] --> B[Runtime]\n    B --> E[Your API Backend]\n    E --> D[External Providers or LLM APIs]\n    \n    \n    classDef default color:#f8fafc,text-align:center\n    \n    style A fill:#e879f9,stroke:#2e1065,stroke-width:2px,color:#2e1065,font-weight:bold\n    style B fill:#93c5fd,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a,font-weight:bold\n    style D fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold\n    style E fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold\n    \n    class A,B,C,D,E default" />

3. With Assistant Cloud \[#3-with-assistant-cloud]

<Mermaid chart="graph TD\n    A[Frontend Components] --> B[Runtime]\n    B --> C[Cloud]\n    E --> C\n    C --> D[External Providers or LLM APIs]\n    B --> E[Your API Backend]\n    \n    classDef default color:#f8fafc,text-align:center\n    \n    style A fill:#e879f9,stroke:#2e1065,stroke-width:2px,color:#2e1065,font-weight:bold\n    style B fill:#93c5fd,stroke:#1e3a8a,stroke-width:2px,color:#1e3a8a,font-weight:bold\n    style C fill:#86efac,stroke:#064e3b,stroke-width:2px,color:#064e3b,font-weight:bold\n    style D fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold\n    style E fill:#fca5a5,stroke:#7f1d1d,stroke-width:2px,color:#7f1d1d,font-weight:bold\n    \n    class A,B,C,D,E default" />


# CLI
URL: /docs/cli

Scaffold projects, add components, and manage updates from the command line.

Use the `assistant-ui` CLI to quickly set up new projects and add components to existing ones.

init \[#init]

Use the `init` command to initialize configuration and dependencies for a new project.

The `init` command installs dependencies, adds components, and configures your project for assistant-ui.

```bash
npx assistant-ui@latest init
```

This will:

* Detect if you have an existing project with a `package.json`
* Use `shadcn add` to install the assistant-ui quick-start component
* Add the default assistant-ui components (thread, composer, etc.) to your project
* Configure TypeScript paths and imports

**When to use:**

* Adding assistant-ui to an **existing** Next.js project
* First-time setup in a project with `package.json`

**Options**

```bash
Usage: assistant-ui init [options]

initialize assistant-ui in a new or existing project

Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -h, --help       display help for command
```

create \[#create]

Use the `create` command to scaffold a new Next.js project with assistant-ui pre-configured.

```bash
npx assistant-ui@latest create [project-directory]
```

This command scaffolds a project from assistant-ui starter templates or examples.

**Available Templates**

| Template      | Description                          | Command                                  |
| ------------- | ------------------------------------ | ---------------------------------------- |
| `default`     | Default template with Vercel AI SDK  | `npx assistant-ui create`                |
| `minimal`     | Bare-bones starting point            | `npx assistant-ui create -t minimal`     |
| `cloud`       | Cloud-backed persistence starter     | `npx assistant-ui create -t cloud`       |
| `cloud-clerk` | Cloud-backed starter with Clerk auth | `npx assistant-ui create -t cloud-clerk` |
| `langgraph`   | LangGraph starter template           | `npx assistant-ui create -t langgraph`   |
| `mcp`         | MCP starter template                 | `npx assistant-ui create -t mcp`         |

**Available Examples**

Use `--example` to create a project from one of the monorepo examples with full feature demonstrations:

| Example                    | Description                               | Command                                                      |
| -------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| `with-ai-sdk-v6`           | Vercel AI SDK v6 integration              | `npx assistant-ui create my-app -e with-ai-sdk-v6`           |
| `with-artifacts`           | HTML artifact rendering with live preview | `npx assistant-ui create my-app -e with-artifacts`           |
| `with-langgraph`           | LangGraph agent with custom tools         | `npx assistant-ui create my-app -e with-langgraph`           |
| `with-cloud`               | Assistant Cloud persistence               | `npx assistant-ui create my-app -e with-cloud`               |
| `with-ag-ui`               | AG-UI protocol integration                | `npx assistant-ui create my-app -e with-ag-ui`               |
| `with-assistant-transport` | Custom backend via Assistant Transport    | `npx assistant-ui create my-app -e with-assistant-transport` |
| `with-chain-of-thought`    | Chain-of-thought with JS execution        | `npx assistant-ui create my-app -e with-chain-of-thought`    |
| `with-external-store`      | External message store                    | `npx assistant-ui create my-app -e with-external-store`      |
| `with-custom-thread-list`  | Custom thread list UI                     | `npx assistant-ui create my-app -e with-custom-thread-list`  |
| `with-react-hook-form`     | React Hook Form integration               | `npx assistant-ui create my-app -e with-react-hook-form`     |
| `with-ffmpeg`              | FFmpeg video processing tool              | `npx assistant-ui create my-app -e with-ffmpeg`              |
| `with-elevenlabs-scribe`   | ElevenLabs voice transcription            | `npx assistant-ui create my-app -e with-elevenlabs-scribe`   |
| `with-parent-id-grouping`  | Message part grouping                     | `npx assistant-ui create my-app -e with-parent-id-grouping`  |
| `with-react-router`        | React Router v7 integration               | `npx assistant-ui create my-app -e with-react-router`        |
| `with-tanstack`            | TanStack Start integration                | `npx assistant-ui create my-app -e with-tanstack`            |

**Examples**

```bash
# Create with default template
npx assistant-ui@latest create my-app

# Create with cloud template
npx assistant-ui@latest create my-app -t cloud

# Create with cloud + clerk template
npx assistant-ui@latest create my-app -t cloud-clerk

# Create from an example
npx assistant-ui@latest create my-app --example with-langgraph

# Create with specific package manager
npx assistant-ui@latest create my-app --use-pnpm

# Skip package installation
npx assistant-ui@latest create my-app --skip-install
```

**Options**

```bash
Usage: assistant-ui create [project-directory] [options]

create a new project

Arguments:
  project-directory         name of the project directory

Options:
  -t, --template <template>  template to use (default, minimal, cloud, cloud-clerk, langgraph, mcp)
  -e, --example <example>    create from an example (e.g., with-langgraph)
  --use-npm                  explicitly use npm
  --use-pnpm                 explicitly use pnpm
  --use-yarn                 explicitly use yarn
  --use-bun                  explicitly use bun
  --skip-install             skip installing packages
  -h, --help                 display help for command
```

add \[#add]

Use the `add` command to add individual components to your project.

```bash
npx assistant-ui@latest add [component]
```

The `add` command fetches components from the assistant-ui registry and adds them to your project. It automatically:

* Installs required dependencies
* Adds TypeScript types
* Configures imports

**Popular Components**

```bash
# Add the basic thread component
npx assistant-ui add thread

# Add thread list for multi-conversation support
npx assistant-ui add thread-list

# Add assistant modal
npx assistant-ui add assistant-modal

# Add multiple components at once
npx assistant-ui add thread thread-list assistant-sidebar
```

**Options**

```bash
Usage: assistant-ui add [options] <components...>

add a component to your project

Arguments:
  components             the components to add

Options:
  -y, --yes              skip confirmation prompt. (default: true)
  -o, --overwrite        overwrite existing files. (default: false)
  -c, --cwd <cwd>        the working directory. defaults to the current directory.
  -p, --path <path>      the path to add the component to.
  -h, --help             display help for command
```

update \[#update]

Use the `update` command to update all `@assistant-ui/*` packages to their latest versions.

```bash
npx assistant-ui@latest update
```

This command:

* Scans your `package.json` for assistant-ui packages
* Updates them to the latest versions using your package manager
* Preserves other dependencies

**Examples**

```bash
# Update all assistant-ui packages
npx assistant-ui update

# Dry run to see what would be updated
npx assistant-ui update --dry
```

**Options**

```bash
Usage: assistant-ui update [options]

update all '@assistant-ui/*' packages to latest versions

Options:
  --dry          print the command instead of running it
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -h, --help       display help for command
```

upgrade \[#upgrade]

Use the `upgrade` command to automatically migrate your codebase when there are breaking changes.

```bash
npx assistant-ui@latest upgrade
```

This command:

* Runs codemods to transform your code
* Updates import paths and API usage
* Detects required dependency changes
* Prompts to install new packages

**What it does:**

* Applies all available codemods sequentially
* Shows progress bar with file count
* Reports any transformation errors
* Automatically detects and offers to install new dependencies

**Example output:**

```bash
Starting upgrade...
Found 24 files to process.
Progress |████████████████████| 100% | ETA: 0s || Running v0-11/content-part-to-message-part...
Checking for package dependencies...
✅ Upgrade complete!
```

**Options**

```bash
Usage: assistant-ui upgrade [options]

upgrade and apply codemods for breaking changes

Options:
  -d, --dry              dry run (no changes are made to files)
  -p, --print            print transformed files to stdout
  --verbose              show more information about the transform process
  -j, --jscodeshift <options>  pass options directly to jscodeshift
  -h, --help             display help for command
```

codemod \[#codemod]

Use the `codemod` command to run a specific codemod transformation.

```bash
npx assistant-ui@latest codemod <codemod> <source>
```

This is useful when you want to run a specific migration rather than all available upgrades.

**Examples**

```bash
# Run specific codemod on a directory
npx assistant-ui codemod v0-11/content-part-to-message-part ./src

# Run with dry run to preview changes
npx assistant-ui codemod v0-11/content-part-to-message-part ./src --dry

# Print transformed output
npx assistant-ui codemod v0-11/content-part-to-message-part ./src --print
```

**Options**

```bash
Usage: assistant-ui codemod [options] <codemod> <source>

run a specific codemod transformation

Arguments:
  codemod                codemod to run
  source                 path to source files or directory to transform

Options:
  -d, --dry              dry run (no changes are made to files)
  -p, --print            print transformed files to stdout
  --verbose              show more information about the transform process
  -j, --jscodeshift <options>  pass options directly to jscodeshift
  -h, --help             display help for command
```

mcp \[#mcp]

Use the `mcp` command to install the assistant-ui MCP docs server for your IDE.

```bash
npx assistant-ui@latest mcp
```

This command configures the [Model Context Protocol](/docs/llm#mcp) server, giving your AI assistant direct access to assistant-ui documentation.

**Examples**

```bash
# Interactive - prompts to select IDE
npx assistant-ui mcp

# Install for specific IDE
npx assistant-ui mcp --cursor
npx assistant-ui mcp --windsurf
npx assistant-ui mcp --vscode
npx assistant-ui mcp --zed
npx assistant-ui mcp --claude-code
npx assistant-ui mcp --claude-desktop
```

**Options**

```bash
Usage: assistant-ui mcp [options]

install assistant-ui MCP docs server for your IDE

Options:
  --cursor          install for Cursor
  --windsurf        install for Windsurf
  --vscode          install for VSCode
  --zed             install for Zed
  --claude-code     install for Claude Code
  --claude-desktop  install for Claude Desktop
  -h, --help        display help for command
```

Common Workflows \[#common-workflows]

Starting a new project \[#starting-a-new-project]

```bash
# Create a new project with the default template
npx assistant-ui@latest create my-chatbot

# Navigate into the directory
cd my-chatbot

# Start development
npm run dev
```

Adding to existing project \[#adding-to-existing-project]

```bash
# Initialize assistant-ui
npx assistant-ui@latest init

# Add additional components
npx assistant-ui@latest add thread-list assistant-modal

# Start development
npm run dev
```

Keeping up to date \[#keeping-up-to-date]

```bash
# Check for updates (dry run)
npx assistant-ui@latest update --dry

# Update all packages
npx assistant-ui@latest update

# Run upgrade codemods if needed
npx assistant-ui@latest upgrade
```

Migrating versions \[#migrating-versions]

```bash
# Run automated migration
npx assistant-ui@latest upgrade

# Or run specific codemod
npx assistant-ui@latest codemod v0-11/content-part-to-message-part ./src

# Update packages after migration
npx assistant-ui@latest update
```

Component Registry \[#component-registry]

The CLI pulls components from our public registry at [r.assistant-ui.com](https://r.assistant-ui.com).

Each component includes:

* Full TypeScript source code
* All required dependencies
* Tailwind CSS configuration
* Usage examples

Components are added directly to your project's source code, giving you full control to customize them.

Troubleshooting \[#troubleshooting]

Command not found \[#command-not-found]

If you get a "command not found" error, make sure you're using `npx`:

```bash
npx assistant-ui@latest init
```

Permission errors \[#permission-errors]

On Linux/macOS, if you encounter permission errors:

```bash
sudo npx assistant-ui@latest init
```

Or fix npm permissions: [https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)

Conflicting dependencies \[#conflicting-dependencies]

If you see dependency conflicts:

```bash
# Try with --force flag
npm install --force

# Or use legacy peer deps
npm install --legacy-peer-deps
```

Component already exists \[#component-already-exists]

Use the `--overwrite` flag to replace existing components:

```bash
npx assistant-ui@latest add thread --overwrite
```

Configuration \[#configuration]

The CLI respects your project's configuration:

* **Package Manager**: Automatically detects npm, pnpm, yarn, or bun
* **TypeScript**: Works with your `tsconfig.json` paths
* **Tailwind**: Uses your `tailwind.config.js` settings
* **Import Aliases**: Respects `components.json` or `assistant-ui.json` configuration


# DevTools
URL: /docs/devtools

Inspect runtime state, context, and events in the browser.

Hey, the assistant-ui DevTools allows you to debug the assistant-ui state and context, and events without resorting to `console.log`. It's an easy way to see how data flows to the assistant-ui's runtime layer.

<img alt="Screenshot of the DevTools UI showing logs and state panels" src={__img0} placeholder="blur" />

Setup \[#setup]

<Steps>
  <Step>
    Install the DevTools package \[#install-the-devtools-package]

    <InstallCommand npm={["@assistant-ui/react-devtools"]} />
  </Step>

  <Step>
    Mount the DevTools modal \[#mount-the-devtools-modal]

    ```tsx
    import { AssistantRuntimeProvider } from "@assistant-ui/react";
    import { DevToolsModal } from "@assistant-ui/react-devtools";

    export function AssistantApp() {
      return (
        <AssistantRuntimeProvider>
          <DevToolsModal />
          {/* ...your assistant-ui... */}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Verify the DevTools overlay \[#verify-the-devtools-overlay]

    That's it! In development builds you should now see the DevTools in the lower-right corner of your site.

    <img alt="DevTools floating modal anchored in the lower-right corner of a page" src={__img1} placeholder="blur" />
  </Step>
</Steps>


# Introduction
URL: /docs

Beautiful, enterprise-grade AI chat interfaces for React applications.

import { Sparkles, PanelsTopLeft, Database, Terminal, Bot } from "lucide-react";

assistant-ui helps you create beautiful, enterprise-grade AI chat interfaces in minutes. Whether you're building a ChatGPT clone, a customer support chatbot, an AI assistant, or a complex multi-agent application, assistant-ui provides the frontend primitive components and state management layers to focus on what makes your application unique.

<Callout type="tip">
  Already using the AI SDK with your own UI? Add [cloud persistence with just one hook](/docs/cloud/ai-sdk), no UI library required.
</Callout>

Key Features \[#key-features]

<Cards>
  <Card icon={<PanelsTopLeft className="text-purple-300" />} title="Instant Chat UI">
    Pre-built beautiful, customizable chat interfaces out of the box. Easy to quickly iterate on your idea.
  </Card>

  <Card icon={<PanelsTopLeft className="text-blue-300" />} title="Chat State Management">
    Powerful state management for chat interactions, optimized for streaming responses and efficient rendering.
  </Card>

  <Card icon={<Database className="text-green-300" />} title="High Performance">
    Optimized for speed and efficiency with minimal bundle size, ensuring your AI chat interfaces remain responsive.
  </Card>

  <Card icon={<Terminal className="text-orange-300" />} title="Framework Agnostic">
    Easily integrate with any backend system, whether using Vercel AI SDK, direct LLM connections, or custom solutions. Works with any React-based framework.
  </Card>
</Cards>

Quick Try \[#quick-try]

The fastest way to get started:

```sh
npx assistant-ui@latest create
```

This creates a new project with everything configured. Or choose a template:

```sh
# Minimal starter
npx assistant-ui@latest create -t minimal

# Assistant Cloud - with persistence and thread management
npx assistant-ui@latest create -t cloud

# Assistant Cloud + Clerk authentication
npx assistant-ui@latest create -t cloud-clerk

# LangGraph starter template
npx assistant-ui@latest create -t langgraph

# MCP starter template
npx assistant-ui@latest create -t mcp
```

What's Next? \[#whats-next]

<Cards>
  <Card title="Installation" description="Full installation guide with CLI and manual setup options" href="/docs/installation" />

  <Card title="Agent Skills" description="Use AI tools to build with assistant-ui faster" href="/docs/llm" />

  <Card title="Pick a Runtime" description="Choose the right runtime for your needs" href="/docs/runtimes/pick-a-runtime" />

  <Card title="Examples" description="Explore full implementations and demos" href="https://github.com/assistant-ui/assistant-ui/tree/main/examples" />
</Cards>


# Installation
URL: /docs/installation

Get assistant-ui running in 5 minutes with npm and your first chat component.

Quick Start \[#quick-start]

The fastest way to get started with assistant-ui.

<img alt="animated gif showing the steps to create a new project" src={__img0} />

<Steps>
  <Step>
    Initialize assistant-ui \[#initialize-assistant-ui]

    **Create a new project:**

    ```sh
    npx assistant-ui@latest create
    ```

    Or choose a template:

    ```sh
    # Minimal starter
    npx assistant-ui@latest create -t minimal

    # Assistant Cloud - with persistence and thread management
    npx assistant-ui@latest create -t cloud

    # Assistant Cloud + Clerk authentication
    npx assistant-ui@latest create -t cloud-clerk

    # LangGraph starter template
    npx assistant-ui@latest create -t langgraph

    # MCP starter template
    npx assistant-ui@latest create -t mcp
    ```

    **Add to an existing project:**

    ```sh
    npx assistant-ui@latest init
    ```
  </Step>

  <Step>
    Add API key \[#add-api-key]

    Create a `.env` file with your API key:

    ```
    OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```
  </Step>

  <Step>
    Start the app \[#start-the-app]

    ```sh
    npm run dev
    ```
  </Step>
</Steps>

Manual Setup \[#manual-setup]

If you prefer not to use the CLI, you can install components manually.

<Steps>
  <Step>
    Add assistant-ui \[#add-assistant-ui]

    <InstallCommand shadcn={["thread", "thread-list"]} manualSetupInstructions />
  </Step>

  <Step>
    Setup Backend Endpoint \[#setup-backend-endpoint]

    Install provider SDK:

    <Tabs groupId="provider" items={["OpenAI", "Anthropic", "Azure", "AWS", "Gemini", "GCP", "Groq", "Fireworks", "Cohere", "Ollama", "Chrome AI"]}>
      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/openai"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/anthropic"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/azure"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/amazon-bedrock"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/google"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/google-vertex"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/openai"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/openai"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "@ai-sdk/cohere"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "ollama-ai-provider-v2"]} />
      </Tab>

      <Tab>
        <InstallCommand npm={["ai", "@assistant-ui/react-ai-sdk", "chrome-ai"]} />
      </Tab>
    </Tabs>

    Add an API endpoint:

    <Tabs groupId="provider" items={["OpenAI", "Anthropic", "Azure", "AWS", "Gemini", "GCP", "Groq", "Fireworks", "Cohere", "Ollama", "Chrome AI"]}>
      <>
        <Tab value="OpenAI">
          ```ts title="/app/api/chat/route.ts" 
          import { openai } from "@ai-sdk/openai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: openai("gpt-4o-mini"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Anthropic">
          ```ts title="/app/api/chat/route.ts" 
          import { anthropic } from "@ai-sdk/anthropic";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: anthropic("claude-3-5-sonnet-20240620"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Azure">
          ```ts title="/app/api/chat/route.ts" 
          import { azure } from "@ai-sdk/azure";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: azure("your-deployment-name"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="AWS">
          ```ts title="/app/api/chat/route.ts" 
          import { bedrock } from "@ai-sdk/amazon-bedrock";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: bedrock("anthropic.claude-3-5-sonnet-20240620-v1:0"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Gemini">
          ```ts title="/app/api/chat/route.ts" 
          import { google } from "@ai-sdk/google";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: google("gemini-2.0-flash"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="GCP">
          ```ts title="/app/api/chat/route.ts" 
          import { vertex } from "@ai-sdk/google-vertex";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: vertex("gemini-1.5-pro"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Groq">
          ```ts title="/app/api/chat/route.ts" 
          import { createOpenAI } from "@ai-sdk/openai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          const groq = createOpenAI({
            apiKey: process.env.GROQ_API_KEY ?? "",
            baseURL: "https://api.groq.com/openai/v1",
          });

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: groq("llama3-70b-8192"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Fireworks">
          ```ts title="/app/api/chat/route.ts" 
          import { createOpenAI } from "@ai-sdk/openai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          const fireworks = createOpenAI({
            apiKey: process.env.FIREWORKS_API_KEY ?? "",
            baseURL: "https://api.fireworks.ai/inference/v1",
          });

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: fireworks("accounts/fireworks/models/firefunction-v2"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Cohere">
          ```ts title="/app/api/chat/route.ts" 
          import { cohere } from "@ai-sdk/cohere";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: cohere("command-r-plus"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Ollama">
          ```ts title="/app/api/chat/route.ts" 
          import { ollama } from "ollama-ai-provider-v2";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: ollama("llama3"),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>

        <Tab value="Chrome AI">
          ```ts title="/app/api/chat/route.ts" 
          import { chromeai } from "chrome-ai";
          import { convertToModelMessages, streamText } from "ai";

          export const maxDuration = 30;

          export async function POST(req: Request) {
            const { messages } = await req.json();
            const result = streamText({
              model: chromeai(),
              messages: convertToModelMessages(messages),
            });
            return result.toUIMessageStreamResponse();
          }
          ```
        </Tab>
      </>
    </Tabs>

    Define environment variables:

    <Tabs groupId="provider" items={["OpenAI", "Anthropic", "Azure", "AWS", "Gemini", "GCP", "Groq", "Fireworks", "Cohere", "Ollama", "Chrome AI"]}>
      <>
        <Tab value="OpenAI">
          ```sh title="/.env.local" 
          OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Anthropic">
          ```sh title="/.env.local" 
          ANTHROPIC_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Azure">
          ```sh title="/.env.local" 
          AZURE_RESOURCE_NAME="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          AZURE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="AWS">
          ```sh title="/.env.local" 
          AWS_ACCESS_KEY_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          AWS_REGION="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Gemini">
          ```sh title="/.env.local" 
          GOOGLE_GENERATIVE_AI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="GCP">
          ```sh title="/.env.local" 
          GOOGLE_VERTEX_PROJECT="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          GOOGLE_VERTEX_LOCATION="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          GOOGLE_APPLICATION_CREDENTIALS="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Groq">
          ```sh title="/.env.local" 
          GROQ_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Fireworks">
          ```sh title="/.env.local" 
          FIREWORKS_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Cohere">
          ```sh title="/.env.local" 
          COHERE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
          ```
        </Tab>

        <Tab value="Ollama">
          ```sh
          <none>
          ```
        </Tab>

        <Tab value="Chrome AI">
          ```sh
          <none>
          ```
        </Tab>
      </>
    </Tabs>

    If you aren't using Next.js, you can also deploy this endpoint to Cloudflare Workers, or any other serverless platform.
  </Step>

  <Step>
    Use it in your app \[#use-it-in-your-app]

    <Tabs items={["Thread", "AssistantModal"]}>
      <>
        <Tab value="Thread">
          ```tsx title="/app/page.tsx" 
          import { AssistantRuntimeProvider } from "@assistant-ui/react";
          import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
          import { ThreadList } from "@/components/assistant-ui/thread-list";
          import { Thread } from "@/components/assistant-ui/thread";

          const MyApp = () => {
            const runtime = useChatRuntime({
              transport: new AssistantChatTransport({
                api: "/api/chat",
              }),
            });

            return (
              <AssistantRuntimeProvider runtime={runtime}>
                <div>
                  <ThreadList />
                  <Thread />
                </div>
              </AssistantRuntimeProvider>
            );
          };
          ```
        </Tab>

        <Tab value="AssistantModal">
          ```tsx title="/app/page.tsx" 
          // run `npx shadcn@latest add https://r.assistant-ui.com/assistant-modal.json`

          import { AssistantRuntimeProvider } from "@assistant-ui/react";
          import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
          import { AssistantModal } from "@/components/assistant-ui/assistant-modal";

          const MyApp = () => {
            const runtime = useChatRuntime({
              transport: new AssistantChatTransport({
                api: "/api/chat",
              }),
            });

            return (
              <AssistantRuntimeProvider runtime={runtime}>
                <AssistantModal />
              </AssistantRuntimeProvider>
            );
          };
          ```
        </Tab>
      </>
    </Tabs>
  </Step>
</Steps>

What's Next? \[#whats-next]

<Cards>
  <Card title="Pick a Runtime" description="Choose the right runtime for your needs" href="/docs/runtimes/pick-a-runtime" />

  <Card title="Generative UI" description="Create rich UI components for tool executions" href="/docs/guides/tool-ui" />

  <Card title="Add Persistence" description="Save and restore chat conversations" href="/docs/cloud/overview" />

  <Card title="Examples" description="Explore full implementations and demos" href="https://github.com/assistant-ui/assistant-ui/tree/main/examples" />
</Cards>


# Agent Skills
URL: /docs/llm

Use AI tools to build with assistant-ui faster. AI-accessible documentation, Claude Code skills, and MCP integration.

import { FileText } from "lucide-react";

Build faster with AI assistants that understand assistant-ui. This page covers all the ways to give your AI tools access to assistant-ui documentation and context.

AI Accessible Documentation \[#ai-accessible-documentation]

Our docs are designed to be easily accessible to AI assistants:

<Cards>
  <Card icon={<FileText className="text-blue-300" />} title="/llms.txt" href="/llms.txt" external>
    Structured index of all documentation pages. Point your AI here for a quick overview.
  </Card>

  <Card icon={<FileText className="text-green-300" />} title="/llms-full.txt" href="/llms-full.txt" external>
    Complete documentation in a single file. Use this for full context.
  </Card>

  <Card icon={<FileText className="text-purple-300" />} title=".mdx suffix">
    Add `.mdx` to any page's URL to get raw markdown content (e.g., `/docs/installation.mdx`).
  </Card>
</Cards>

Context Files \[#context-files]

Add assistant-ui context to your project's `CLAUDE.md` or `.cursorrules`:

```md
## assistant-ui

This project uses assistant-ui for chat interfaces.

Documentation: https://www.assistant-ui.com/llms-full.txt

Key patterns:
- Use AssistantRuntimeProvider at the app root
- Thread component for full chat interface
- AssistantModal for floating chat widget
- useChatRuntime hook with AI SDK transport
```

Skills \[#skills]

Install assistant-ui skills for AI Tools:

```sh
npx skills add assistant-ui/skills
```

| Skill           | Purpose                                                              |
| --------------- | -------------------------------------------------------------------- |
| `/assistant-ui` | General architecture and overview guide                              |
| `/setup`        | Project setup and configuration (AI SDK, LangGraph, custom backends) |
| `/primitives`   | UI component primitives (Thread, Composer, Message, etc.)            |
| `/runtime`      | Runtime system and state management                                  |
| `/tools`        | Tool registration and tool UI                                        |
| `/streaming`    | Streaming protocol with assistant-stream                             |
| `/cloud`        | Cloud persistence and authorization                                  |
| `/thread-list`  | Multi-thread management                                              |
| `/update`       | Update assistant-ui and AI SDK to latest versions                    |

Use by typing the command in Claude Code, e.g., `/assistant-ui` for the main guide or `/setup` when setting up a project.

MCP \[#mcp]

`@assistant-ui/mcp-docs-server` provides direct access to assistant-ui documentation and examples in your IDE via the Model Context Protocol.

Once installed, your AI assistant will understand everything about assistant-ui - just ask naturally:

* "Add a chat interface with streaming support to my app"
* "How do I integrate assistant-ui with the Vercel AI SDK?"
* "My Thread component isn't updating, what could be wrong?"

Quick Install (CLI) \[#quick-install-cli]

```bash
npx add-mcp @assistant-ui/mcp-docs-server
```

Or specify your IDE directly:

```bash
npx add-mcp @assistant-ui/mcp-docs-server -a claude-code
npx add-mcp @assistant-ui/mcp-docs-server -a claude-desktop
npx add-mcp @assistant-ui/mcp-docs-server -a codex
npx add-mcp @assistant-ui/mcp-docs-server -a cursor
npx add-mcp @assistant-ui/mcp-docs-server -a gemini-cli
npx add-mcp @assistant-ui/mcp-docs-server -a opencode
npx add-mcp @assistant-ui/mcp-docs-server -a vscode
npx add-mcp @assistant-ui/mcp-docs-server -a zed
```

Manual Installation \[#manual-installation]

<Tabs items={["Cursor", "Windsurf", "VSCode", "Zed", "Claude Code", "Claude Desktop"]}>
  <Tab>
    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=assistant-ui&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhc3Npc3RhbnQtdWkvbWNwLWRvY3Mtc2VydmVyIl19">
      <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor" className="not-prose" />
    </a>

    Or add to `.cursor/mcp.json`:

    ```json
    {
      "mcpServers": {
        "assistant-ui": {
          "command": "npx",
          "args": ["-y", "@assistant-ui/mcp-docs-server"]
        }
      }
    }
    ```

    After adding, open Cursor Settings → MCP → find "assistant-ui" and click enable.
  </Tab>

  <Tab>
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json
    {
      "mcpServers": {
        "assistant-ui": {
          "command": "npx",
          "args": ["-y", "@assistant-ui/mcp-docs-server"]
        }
      }
    }
    ```

    After adding, fully quit and re-open Windsurf.
  </Tab>

  <Tab>
    Add to `.vscode/mcp.json` in your project:

    ```json
    {
      "servers": {
        "assistant-ui": {
          "command": "npx",
          "args": ["-y", "@assistant-ui/mcp-docs-server"],
          "type": "stdio"
        }
      }
    }
    ```

    Enable MCP in Settings → search "MCP" → enable "Chat > MCP". Use GitHub Copilot Chat in Agent mode.
  </Tab>

  <Tab>
    Add to your Zed settings file:

    * macOS: `~/.zed/settings.json`
    * Linux: `~/.config/zed/settings.json`
    * Windows: `%APPDATA%\Zed\settings.json`

    Or open via `Cmd/Ctrl + ,` → "Open JSON Settings"

    ```json
    {
      "context_servers": {
        "assistant-ui": {
          "command": {
            "path": "npx",
            "args": ["-y", "@assistant-ui/mcp-docs-server"]
          }
        }
      }
    }
    ```

    The server starts automatically with the Assistant Panel.
  </Tab>

  <Tab>
    ```bash
    claude mcp add assistant-ui -- npx -y @assistant-ui/mcp-docs-server
    ```

    The server starts automatically once added.
  </Tab>

  <Tab>
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json
    {
      "mcpServers": {
        "assistant-ui": {
          "command": "npx",
          "args": ["-y", "@assistant-ui/mcp-docs-server"]
        }
      }
    }
    ```

    Restart Claude Desktop after updating the configuration.
  </Tab>
</Tabs>

Available Tools \[#available-tools]

| Tool                  | Description                                                                             |
| --------------------- | --------------------------------------------------------------------------------------- |
| `assistantUIDocs`     | Access documentation: getting started, component APIs, runtime docs, integration guides |
| `assistantUIExamples` | Browse code examples: AI SDK, LangGraph, OpenAI Assistants, tool UI patterns            |

Troubleshooting \[#troubleshooting]

* **Server not starting**: Ensure `npx` is installed and working. Check configuration file syntax.
* **Tool calls failing**: Restart the MCP server and/or your IDE. Update to latest IDE version.


# Using old React versions
URL: /docs/react-compatibility

Compatibility notes for React 18, 17, and 16.

<Callout type="warning" title="Older React Versions">
  Older React versions are not continuously tested. If you encounter any issues
  with integration, please contact us for help by joining our
  [Discord](https://discord.gg/S9dwgCNEFs).
</Callout>

This guide provides instructions for configuring assistant-ui to work with React 18 or older versions.

React 18 \[#react-18]

If you're using React 18, you need to update the shadcn/ui components to work with `forwardRef`. Specifically, you need to modify the Button component.

Updating the Button Component \[#updating-the-button-component]

Navigate to your button component file (typically `/components/ui/button.tsx`) and wrap the Button component with `forwardRef`:

```tsx
// Before
function Button({
  className,
  variant,
  size,
  asChild = false,
  ...props
}: React.ComponentProps<"button"> &
  VariantProps<typeof buttonVariants> & {
    asChild?: boolean;
  }) {
  const Comp = asChild ? Slot : "button";

  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      {...props}
    />
  );
}

// After
const Button = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<"button"> &
    VariantProps<typeof buttonVariants> & {
      asChild?: boolean;
    }
>(({ className, variant, size, asChild = false, ...props }, ref) => {
  const Comp = asChild ? Slot : "button";

  return (
    <Comp
      data-slot="button"
      className={cn(buttonVariants({ variant, size, className }))}
      ref={ref}
      {...props}
    />
  );
});
Button.displayName = "Button";
```

**Note:** If you're using a lower React version (17 or 16), you'll also need to follow the instructions for that version.

React 17 \[#react-17]

For React 17 compatibility, in addition to the modifications outlined for React 18, you must also include a polyfill for the `useSyncExternalStore` hook (utilized by zustand).

Patching Zustand with patch-package \[#patching-zustand-with-patch-package]

Since the assistant-ui uses zustand internally, which depends on `useSyncExternalStore`, you'll need to patch the zustand package directly:

1. Install the required packages:

<InstallCommand npm={["use-sync-external-store", "patch-package"]} />

2. Add a postinstall script to your package.json:

```json
{
  "scripts": {
    "postinstall": "patch-package"
  }
}
```

3. You'll want to follow the instructions in [patch-package](https://github.com/ds300/patch-package), by first making changes to the files of a particular package in your node\_modules folder, then running either `yarn patch-package package-name` or `npx patch-package package-name`. You'll need a patch for zustand - within `node_modules/zustand`, open `zustand/react.js` and make the following code changes:

````diff
diff --git a/node_modules/zustand/react.js b/node_modules/zustand/react.js
index 7599cfb..64530a8 100644
--- a/node_modules/zustand/react.js
+++ b/node_modules/zustand/react.js
@@ -1,6 +1,6 @@
 'use strict';

-var React = require('react');
+var React = require('use-sync-external-store/shim');
 var vanilla = require('zustand/vanilla');

 const identity = (arg) => arg;
@@ -10,7 +10,7 @@ function useStore(api, selector = identity) {
     () => selector(api.getState()),
     () => selector(api.getInitialState())
   );
-  React.useDebugValue(slice);
+  //React.useDebugValue(slice);
   return slice;
 }
 const createImpl = (createState) => {

This patch replaces the React import in zustand with the polyfill from `use-sync-external-store/shim` and comments out the `useDebugValue` call which isn't needed.

You should then run the patch-package command `yarn patch-package zustand` or `npx patch-package zustand` which should create a `patches` folder with a zustand patch file similar looking to this:

```diff
diff --git a/node_modules/zustand/react.js b/node_modules/zustand/react.js
index 7599cfb..64530a8 100644
--- a/node_modules/zustand/react.js
+++ b/node_modules/zustand/react.js
@@ -1,6 +1,6 @@
 'use strict';

-var React = require('react');
+var React = require('use-sync-external-store/shim');
 var vanilla = require('zustand/vanilla');

 const identity = (arg) => arg;
@@ -10,7 +10,7 @@ function useStore(api, selector = identity) {
     () => selector(api.getState()),
     () => selector(api.getInitialState())
   );
-  React.useDebugValue(slice);
+  //React.useDebugValue(slice);
   return slice;
 }
 const createImpl = (createState) => {
````

4. You may also need to apply the same patches within `node_modules/@assistant-ui/react/` and possibly a nested dependency patch for `node_modules/@assistant-ui/react/node_modules/zustand`. Look for instances of `React.useSyncExternalStore` and replace with `{ useSyncExternalStore } from "use-sync-external-store/shim";` and comment out any `useDebugValue` calls. Finally, you may need to patch `useId` from React, so within `node_modules/@assistant-ui/react/dist/runtimes/remote-thread-list/RemoteThreadListThreadListRuntimeCore.js`, change the following:

```diff
-import { Fragment, useEffect, useId } from "react";
+import { Fragment, useEffect, useRef } from "react";
 import { create } from "zustand";
 import { AssistantMessageStream } from "assistant-stream";
 import { RuntimeAdapterProvider } from "../adapters/RuntimeAdapterProvider.js";
 import { jsx } from "react/jsx-runtime";
+
+// PATCH-PACKAGE: Polyfill for useId if not available in React 16
+let useId;
+try {
+  // Try to use React's useId if available
+  useId = require("react").useId;
+} catch (e) {}
+if (!useId) {
+  // Fallback polyfill
+  let globalId = 0;
+  useId = function() {
+    const idRef = useRef();
+    if (!idRef.current) {
+      globalId++;
+      idRef.current = `uid-${globalId}`;
+    }
+    return idRef.current;
+  };
+}
```

5. Run the postinstall script to apply the patches:

```bash
npm run postinstall
# or
yarn postinstall
```

This patch replaces the React import in zustand with the polyfill from `use-sync-external-store/shim` and comments out the `useDebugValue` call which isn't needed.

**Note:** If you're using React 16, you'll also need to follow the instructions for that version.

React 16 \[#react-16]

<Callout type="info" title="Incomplete Section">
  This section is incomplete and contributions are welcome. If you're using
  React 16 and have successfully integrated assistant-ui, please consider
  contributing to this documentation.
</Callout>

For React 16 compatibility, you need to apply all the steps for **React 18** and **React 17** above.

Additional Resources \[#additional-resources]

If you encounter any issues with React compatibility, please:

1. Check that all required dependencies are installed
2. Ensure your component modifications are correctly implemented
3. Join our [Discord](https://discord.gg/S9dwgCNEFs) community for direct support


# AI SDK + assistant-ui
URL: /docs/cloud/ai-sdk-assistant-ui

Integrate cloud persistence using assistant-ui runtime and pre-built components.

Overview \[#overview]

This guide shows how to integrate Assistant Cloud with the [AI SDK](https://sdk.vercel.ai/) using assistant-ui's runtime system and pre-built UI components.

What You Get \[#what-you-get]

This integration provides:

* **`<Thread />`** — A complete chat interface with messages, composer, and status indicators
* **`<ThreadList />`** — A sidebar showing all conversations with auto-generated titles, plus new/delete/manage actions
* **Automatic Persistence** — Messages save as they stream. Threads are created automatically on first message.
* **Runtime Integration** — The assistant-ui runtime handles all cloud synchronization behind the scenes.

How It Works \[#how-it-works]

The `useChatRuntime` hook from `@assistant-ui/react-ai-sdk` wraps AI SDK's `useChat` and adds cloud persistence via the `cloud` parameter. The runtime automatically:

1. Creates a cloud thread on the first user message
2. Persists messages as they complete streaming
3. Generates a conversation title after the assistant's first response
4. Loads historical messages when switching threads via `<ThreadList />`

You provide the AI SDK endpoint (`api: "/api/chat"`) and the cloud configuration—everything else is handled.

Prerequisites \[#prerequisites]

<Callout type="info">
  You need an assistant-cloud account to follow this guide. [Sign up here](https://cloud.assistant-ui.com/) to get started.
</Callout>

Setup Guide \[#setup-guide]

<Steps>
  <Step>
    Create a Cloud Project \[#create-a-cloud-project]

    Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy:

    * **Frontend API URL**: `https://proj-[ID].assistant-api.com`
    * **Assistant Cloud API Key**: `sk_aui_proj_*`
  </Step>

  <Step>
    Configure Environment Variables \[#configure-environment-variables]

    Add the following environment variables to your project:

    ```bash title=".env.local"
    # Frontend API URL from your cloud project settings
    NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com

    # API key for server-side operations
    ASSISTANT_API_KEY=your-api-key-here
    ```
  </Step>

  <Step>
    Install Dependencies \[#install-dependencies]

    Install the required packages:

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk"]} />
  </Step>

  <Step>
    Set Up the Cloud Runtime \[#set-up-the-cloud-runtime]

    Create a client-side AssistantCloud instance and integrate it with your AI SDK runtime:

    ```tsx title="app/chat/page.tsx"
    "use client";

    import { AssistantCloud, AssistantRuntimeProvider } from "@assistant-ui/react";
    import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
    import { ThreadList } from "@/components/assistant-ui/thread-list";
    import { Thread } from "@/components/assistant-ui/thread";

    export default function ChatPage() {
      const cloud = new AssistantCloud({
        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
        anonymous: true, // Creates browser-session based user ID
      });

      const runtime = useChatRuntime({
        cloud,
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <div className="grid h-dvh grid-cols-[200px_1fr] gap-x-2 px-4 py-4">
            <ThreadList />
            <Thread />
          </div>
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

Telemetry \[#telemetry]

The `useChatRuntime` hook captures full run telemetry including timing data. This integrates with the assistant-ui runtime to provide:

**Automatically captured:**

* `status` — `"completed"`, `"incomplete"`, or `"error"`
* `duration_ms` — Total run duration (measured client-side)
* `steps` — Per-step breakdowns with timing, usage, and tool calls
* `tool_calls` — Tool invocations with name, arguments, results, and source
* `total_steps` — Number of reasoning/tool steps
* `output_text` — Full response text (truncated at 50K characters)

**Requires route configuration:**

* `model_id` — The model used
* `input_tokens` / `output_tokens` — Token usage statistics

To capture model and usage data, add the `messageMetadata` callback to your AI SDK route:

```tsx title="app/api/chat/route.ts"
import { streamText } from "ai";

export async function POST(req: Request) {
  const result = streamText({
    model: openai("gpt-5-mini"),
    messages,
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === "finish") {
        return {
          usage: part.totalUsage,
        };
      }
      if (part.type === "finish-step") {
        return {
          modelId: part.response.modelId,
        };
      }
      return undefined;
    },
  });
}
```

Without this configuration, model and token data will be omitted from telemetry reports.

Customizing Reports \[#customizing-reports]

Use the `beforeReport` hook to add custom metadata or filter reports:

```tsx
const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  telemetry: {
    beforeReport: (report) => ({
      ...report,
      metadata: { userTier: "pro", region: "us-east" },
    }),
  },
});
```

Return `null` from `beforeReport` to skip reporting a specific run. To disable telemetry entirely, pass `telemetry: false`.

Authentication \[#authentication]

The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:

```tsx
import { useAuth } from "@clerk/nextjs";
import { AssistantCloud } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

function Chat() {
  const { getToken } = useAuth();

  const cloud = useMemo(() => new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
    authToken: async () => getToken({ template: "assistant-ui" }),
  }), [getToken]);

  const runtime = useChatRuntime({ cloud });
  // ...
}
```

See the [Cloud Authorization](/docs/cloud/authorization) guide for other auth providers.

Complete Example \[#complete-example]

Check out the [with-cloud example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud) on GitHub for a fully working implementation.


# AI SDK
URL: /docs/cloud/ai-sdk

Add cloud persistence to your existing AI SDK app with a single hook.

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";

Overview \[#overview]

The `@assistant-ui/cloud-ai-sdk` package provides a single hook that adds full message and thread persistence to any [AI SDK](https://sdk.vercel.ai/) application:

* **`useCloudChat`** — wraps `useChat` with automatic cloud persistence and built-in thread management

This hook works with any React UI. You keep full control of your components.

<Callout type="tip">
  See [AI SDK + assistant-ui](/docs/cloud/ai-sdk-assistant-ui) for the full integration with assistant-ui's primitives and runtime.
</Callout>

Prerequisites \[#prerequisites]

<Callout type="info">
  You need an assistant-cloud account to follow this guide. [Sign up here](https://cloud.assistant-ui.com/) to get started.
</Callout>

Setup \[#setup]

<Steps>
  <Step>
    Create a Cloud Project \[#create-a-cloud-project]

    Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy your **Frontend API URL** (`https://proj-[ID].assistant-api.com`).
  </Step>

  <Step>
    Configure Environment Variables \[#configure-environment-variables]

    ```bash title=".env.local"
    NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com
    ```
  </Step>

  <Step>
    Install Dependencies \[#install-dependencies]

    <InstallCommand npm={["@assistant-ui/cloud-ai-sdk", "assistant-cloud", "@ai-sdk/react", "ai"]} />
  </Step>

  <Step>
    Integrate \[#integrate]

    ```tsx title="app/page.tsx"
    "use client";

    import { useState } from "react";
    import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

    export default function Chat() {
      // Zero-config: auto-initializes anonymous cloud from env var with built-in threads.
      // For custom config, pass: { cloud, threads: useThreads(...), onSyncError }
      const { messages, sendMessage, threads } = useCloudChat();

      const [input, setInput] = useState("");
      const handleSubmit = () => {
        if (!input.trim()) return;
        sendMessage({ text: input });
        setInput("");
      };

      return (
        <div>
          {/* Thread list */}
          <ul>
            {threads.threads.map((t) => (
              <li key={t.id} onClick={() => threads.selectThread(t.id)}>
                {t.title || "New conversation"}
              </li>
            ))}
            <li onClick={() => threads.selectThread(null)}>New chat</li>
          </ul>

          {/* Chat messages */}
          <div>
            {messages.map((m) => (
              <div key={m.id}>
                {m.parts.map((p) => p.type === "text" && p.text)}
              </div>
            ))}
          </div>

          {/* Composer */}
          <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
            <input value={input} onChange={(e) => setInput(e.target.value)} />
            <button type="submit">Send</button>
          </form>
        </div>
      );
    }
    ```
  </Step>
</Steps>

That's it. Messages persist automatically as they complete, and switching threads loads the full history.

API Reference \[#api-reference]

useCloudChat(options?) \[#usecloudchatoptions]

Wraps AI SDK's `useChat` with automatic cloud persistence and built-in thread management. Messages are persisted as they finish streaming. Thread creation is automatic on the first message — the hook will auto-create the thread, select it, refresh the thread list, and generate a title after the first response.

Configuration Modes \[#configuration-modes]

**1. Zero-config** — Set `NEXT_PUBLIC_ASSISTANT_BASE_URL` env var, call with no args:

```tsx
const chat = useCloudChat();
```

**2. Custom cloud instance** — For authenticated users or custom configuration:

```tsx
const cloud = new AssistantCloud({ baseUrl, authToken });
const chat = useCloudChat({ cloud });
```

**3. External thread management** — When threads need to be accessed from a separate component or you need custom thread options like `includeArchived`:

```tsx
// In a context provider or parent component
const myThreads = useThreads({ cloud, includeArchived: true });

// Pass to useCloudChat - it will use your thread state
const chat = useCloudChat({ threads: myThreads });
```

Parameters \[#parameters]

| Parameter             | Type                     | Description                                                                                                                                                 |
| --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options.cloud`       | `AssistantCloud`         | Cloud instance (optional — auto-creates anonymous instance from `NEXT_PUBLIC_ASSISTANT_BASE_URL` env var if not provided)                                   |
| `options.threads`     | `UseThreadsResult`       | External thread management from `useThreads()`. Use when you need thread operations in a separate component or custom thread options like `includeArchived` |
| `options.onSyncError` | `(error: Error) => void` | Callback invoked when a sync error occurs                                                                                                                   |

All other [AI SDK `useChat` options](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat) are also accepted.

**Returns:** `UseCloudChatResult`

| Value         | Type                                   | Description                                                        |
| ------------- | -------------------------------------- | ------------------------------------------------------------------ |
| `messages`    | `UIMessage[]`                          | Chat messages (from AI SDK)                                        |
| `status`      | `string`                               | Chat status: `"ready"`, `"submitted"`, `"streaming"`, or `"error"` |
| `sendMessage` | `(message, options?) => Promise<void>` | Send a message (auto-creates thread if needed)                     |
| `stop`        | `() => void`                           | Stop the current stream                                            |
| `threads`     | `UseThreadsResult`                     | Thread management (see below)                                      |

Plus all other properties from AI SDK's [`UseChatHelpers`](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat).

**Thread management (`threads`):**

| Value                   | Type                                              | Description                                       |
| ----------------------- | ------------------------------------------------- | ------------------------------------------------- |
| `threads.threads`       | `CloudThread[]`                                   | Active threads sorted by recency                  |
| `threads.threadId`      | `string \| null`                                  | Current thread ID (`null` for a new unsaved chat) |
| `threads.selectThread`  | `(id: string \| null) => void`                    | Switch threads or pass `null` for a new chat      |
| `threads.isLoading`     | `boolean`                                         | `true` during initial load or refresh             |
| `threads.error`         | `Error \| null`                                   | Last error, if any                                |
| `threads.refresh`       | `() => Promise<boolean>`                          | Re-fetch the thread list                          |
| `threads.delete`        | `(id: string) => Promise<boolean>`                | Delete a thread                                   |
| `threads.rename`        | `(id: string, title: string) => Promise<boolean>` | Rename a thread                                   |
| `threads.archive`       | `(id: string) => Promise<boolean>`                | Archive a thread                                  |
| `threads.unarchive`     | `(id: string) => Promise<boolean>`                | Unarchive a thread                                |
| `threads.generateTitle` | `(threadId: string) => Promise<string \| null>`   | Generate a title using AI                         |

useThreads(options) \[#usethreadsoptions]

Thread list management for use with `useCloudChat`. Call this explicitly and pass to `useCloudChat({ threads })` when you need access to thread operations outside the chat context (e.g., in a separate sidebar component).

```tsx
const myThreads = useThreads({ cloud: myCloud });
const { messages, sendMessage } = useCloudChat({ threads: myThreads });
```

**Parameters:**

| Parameter                 | Type             | Description                                 |
| ------------------------- | ---------------- | ------------------------------------------- |
| `options.cloud`           | `AssistantCloud` | Cloud client instance                       |
| `options.includeArchived` | `boolean`        | Include archived threads (default: `false`) |
| `options.enabled`         | `boolean`        | Enable thread fetching (default: `true`)    |

**Returns:** `UseThreadsResult` — same shape as `threads` from `useCloudChat()`.

Telemetry \[#telemetry]

The `useCloudChat` hook automatically reports run telemetry to Assistant Cloud after each assistant response. This includes:

**Automatically captured:**

* `status` — `"completed"` or `"incomplete"` based on response content
* `tool_calls` — Tool invocations with name, arguments, results, and source (MCP, frontend, or backend)
* `total_steps` — Number of reasoning/tool steps in the response
* `output_text` — Full response text (truncated at 50K characters)

**Requires route configuration:**

* `model_id` — The model used for the response
* `input_tokens` / `output_tokens` — Token usage statistics

To capture model and usage data, configure the `messageMetadata` callback in your AI SDK route:

```tsx title="app/api/chat/route.ts"
import { streamText } from "ai";

export async function POST(req: Request) {
  const result = streamText({
    model: openai("gpt-5-mini"),
    messages,
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === "finish") {
        return {
          usage: part.totalUsage,
        };
      }
      if (part.type === "finish-step") {
        return {
          modelId: part.response.modelId,
        };
      }
      return undefined;
    },
  });
}
```

<Callout type="info">
  The standalone hook does not capture `duration_ms`, per-step breakdowns (`steps`), custom `metadata` pass-through, or `"error"` status. These require the full runtime integration available via [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui).
</Callout>

Customizing Reports \[#customizing-reports]

Use the `beforeReport` hook to enrich or filter telemetry:

```tsx
const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  telemetry: {
    beforeReport: (report) => ({
      ...report,
      metadata: { environment: "production", version: "1.0.0" },
    }),
  },
});
```

Return `null` from `beforeReport` to skip reporting a specific run. To disable telemetry entirely, pass `telemetry: false`.

Authentication \[#authentication]

The example above uses anonymous mode (browser session-based user ID) via the env var. For production apps with user accounts, pass an explicit cloud instance:

```tsx
import { useAuth } from "@clerk/nextjs";
import { AssistantCloud } from "assistant-cloud";
import { useCloudChat } from "@assistant-ui/cloud-ai-sdk";

function Chat() {
  const { getToken } = useAuth();

  const cloud = useMemo(() => new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
    authToken: async () => getToken({ template: "assistant-ui" }),
  }), [getToken]);

  const { messages, sendMessage, threads } = useCloudChat({ cloud });
  // ...
}
```

See the [Cloud Authorization](/docs/cloud/authorization) guide for other auth providers.

Next Steps \[#next-steps]

* If you want pre-built UI components, see [AI SDK + assistant-ui](/docs/cloud/ai-sdk-assistant-ui) for the full integration
* Learn about [user authentication](/docs/cloud/authorization) for multi-user applications
* Check out the [complete example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud-standalone) on GitHub


# User Authorization
URL: /docs/cloud/authorization

Configure workspace auth tokens and integrate with auth providers.

The Assistant Cloud API is accessed directly from your frontend. This eliminates the need for a backend server for most operations—except for authorizing your users.

This guide explains how to set up user authentication and authorization for Assistant Cloud.

Workspaces \[#workspaces]

Authorization is granted to a **workspace**. A workspace is a scope that contains threads and messages. Most commonly:

* Use a `userId` as the workspace for personal chats
* Use `orgId + userId` for organization-scoped conversations
* Use `projectId + userId` for project-based apps

Authentication Approaches \[#authentication-approaches]

Choose the approach that fits your app:

| Approach                             | Best For                                                     | Complexity |
| ------------------------------------ | ------------------------------------------------------------ | ---------- |
| **Direct auth provider integration** | Supported providers (Clerk, Auth0, Supabase, etc.)           | Low        |
| **Backend server**                   | Custom auth, multi-user workspaces, or self-hosted solutions | Medium     |
| **Anonymous mode**                   | Demos, prototypes, or testing                                | None       |

Direct Integration with Auth Provider \[#direct-integration-with-auth-provider]

In the Assistant Cloud dashboard, go to **Auth Integrations** and add your provider. This sets up automatic workspace assignment based on the user's ID from your auth provider.

Then pass an `authToken` function that returns your provider's ID token:

```ts
import { AssistantCloud } from "@assistant-ui/react";

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  authToken: () => getTokenFromYourProvider(), // Returns JWT
});
```

Backend Server Approach \[#backend-server-approach]

Use this when you need custom workspace logic or unsupported auth providers.

<Steps>
  <Step>
    Create an API Key \[#create-an-api-key]

    In the Assistant Cloud dashboard, go to **API Keys** and create a key. Add it to your environment:

    ```bash
    ASSISTANT_API_KEY=your_key_here
    ```
  </Step>

  <Step>
    Create the Token Endpoint \[#create-the-token-endpoint]

    ```ts title="/app/api/assistant-ui-token/route.ts"
    import { AssistantCloud } from "assistant-cloud";
    import { auth } from "@clerk/nextjs/server"; // Or your auth provider

    export const POST = async (req: Request) => {
      const { userId, orgId } = await auth();

      if (!userId) return new Response("Unauthorized", { status: 401 });

      // Define your workspace ID based on your app's structure
      const workspaceId = orgId ? `${orgId}_${userId}` : userId;

      const assistantCloud = new AssistantCloud({
        apiKey: process.env.ASSISTANT_API_KEY!,
        userId,
        workspaceId,
      });

      const { token } = await assistantCloud.auth.tokens.create();
      return new Response(token);
    };
    ```
  </Step>

  <Step>
    Use the Token on the Frontend \[#use-the-token-on-the-frontend]

    ```tsx title="app/chat/page.tsx"
    const cloud = new AssistantCloud({
      baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
      authToken: () =>
        fetch("/api/assistant-ui-token", { method: "POST" }).then((r) => r.text()),
    });

    const runtime = useChatRuntime({
      cloud,
    });
    ```
  </Step>
</Steps>

Anonymous Mode (No Auth) \[#anonymous-mode-no-auth]

For demos or testing, use anonymous mode to create browser-session-based users:

```tsx
import { AssistantCloud } from "@assistant-ui/react";

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  anonymous: true,
});
```

<Callout type="warning">
  Anonymous mode creates a new user for each browser session. Threads won't persist across sessions or devices. Use this only for prototyping.
</Callout>

Auth Provider Examples \[#auth-provider-examples]

Clerk \[#clerk]

<Steps>
  <Step>
    Configure the JWT Template \[#configure-the-jwt-template]

    In the Clerk dashboard, go to **Configure → JWT Templates**. Create a new blank template named "assistant-ui":

    ```json
    {
      "aud": "assistant-ui"
    }
    ```

    <Callout type="info">
      The `aud` claim ensures the JWT is only valid for Assistant Cloud.
    </Callout>

    Note the **Issuer** and **JWKS Endpoint** values.
  </Step>

  <Step>
    Add Auth Integration in Assistant Cloud \[#add-auth-integration-in-assistant-cloud]

    In the Assistant Cloud dashboard, go to **Auth Rules** and create a new rule:

    * **Provider**: Clerk
    * **Issuer**: Paste from Clerk JWT Template
    * **JWKS Endpoint**: Paste from Clerk JWT Template
    * **Audience**: `assistant-ui`
  </Step>

  <Step>
    Use in Your App \[#use-in-your-app]

    ```tsx
    import { useAuth } from "@clerk/nextjs";
    import { AssistantCloud } from "@assistant-ui/react";

    function Chat() {
      const { getToken } = useAuth();

      const cloud = useMemo(
        () =>
          new AssistantCloud({
            baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
            authToken: () => getToken({ template: "assistant-ui" }),
          }),
        [getToken],
      );

      // Use with your runtime...
    }
    ```
  </Step>
</Steps>

Auth0 \[#auth0]

```tsx
import { useAuth0 } from "@auth0/auth0-react";
import { AssistantCloud } from "@assistant-ui/react";

function Chat() {
  const { getAccessTokenSilently } = useAuth0();

  const cloud = useMemo(
    () =>
      new AssistantCloud({
        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
        authToken: () => getAccessTokenSilently(),
      }),
    [getAccessTokenSilently],
  );

  // Use with your runtime...
}
```

Configure the Auth0 integration in the Assistant Cloud dashboard with your Auth0 domain and audience.

Supabase Auth \[#supabase-auth]

```tsx
import { useSupabaseClient } from "@supabase/auth-helpers-react";
import { AssistantCloud } from "@assistant-ui/react";

function Chat() {
  const supabase = useSupabaseClient();

  const cloud = useMemo(
    () =>
      new AssistantCloud({
        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
        authToken: async () => {
          const { data } = await supabase.auth.getSession();
          return data.session?.access_token ?? "";
        },
      }),
    [supabase],
  );

  // Use with your runtime...
}
```

Firebase Auth \[#firebase-auth]

```tsx
import { getAuth, getIdToken } from "firebase/auth";
import { AssistantCloud } from "@assistant-ui/react";

function Chat() {
  const cloud = useMemo(() => {
    const auth = getAuth();
    return new AssistantCloud({
      baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
      authToken: () => getIdToken(auth.currentUser!, true),
    });
  }, []);

  // Use with your runtime...
}
```


# LangGraph + assistant-ui
URL: /docs/cloud/langgraph

Integrate cloud persistence and thread management with LangGraph Cloud.

Overview \[#overview]

This guide shows how to integrate Assistant Cloud with [LangGraph Cloud](https://langchain-ai.github.io/langgraph/cloud/) using assistant-ui's runtime system and pre-built UI components.

Prerequisites \[#prerequisites]

<Callout type="info">
  You need an assistant-cloud account to follow this guide. [Sign up
  here](https://cloud.assistant-ui.com/) to get started.
</Callout>

Setup Guide \[#setup-guide]

<Steps>
  <Step>
    Create a Cloud Project \[#create-a-cloud-project]

    Create a new project in the [assistant-cloud dashboard](https://cloud.assistant-ui.com/) and from the settings page, copy:

    * **Frontend API URL**: `https://proj-[ID].assistant-api.com`
    * **API Key**: For server-side operations
  </Step>

  <Step>
    Configure Environment Variables \[#configure-environment-variables]

    Add the following environment variables to your project:

    ```bash title=".env.local"
    # Frontend API URL from your cloud project settings
    NEXT_PUBLIC_ASSISTANT_BASE_URL=https://proj-[YOUR-ID].assistant-api.com

    # API key for server-side operations
    ASSISTANT_API_KEY=your-api-key-here
    ```
  </Step>

  <Step>
    Install Dependencies \[#install-dependencies]

    Install the required packages:

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph"]} />
  </Step>

  <Step>
    Create the Runtime Provider \[#create-the-runtime-provider]

    Create a runtime provider that integrates LangGraph with assistant-cloud. Choose between anonymous mode for demos/prototypes or authenticated mode for production:

    <Tabs items={["Anonymous", "Authenticated (Clerk)"]}>
      <Tab value="Anonymous">
        ```tsx title="app/chat/runtime-provider.tsx"
        "use client";

        import {
          AssistantCloud,
          AssistantRuntimeProvider,
        } from "@assistant-ui/react";
        import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
        import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
        import { LangChainMessage } from "@assistant-ui/react-langgraph";
        import { useMemo } from "react";

        export function MyRuntimeProvider({
          children,
        }: Readonly<{
          children: React.ReactNode;
        }>) {
          const cloud = useMemo(
            () =>
              new AssistantCloud({
                baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
                anonymous: true, // Creates browser session-based user ID
              }),
            [],
          );

          const runtime = useLangGraphRuntime({
            cloud,
            stream: async function* (messages, { initialize }) {
              const { externalId } = await initialize();
              if (!externalId) throw new Error("Thread not found");

              return sendMessage({
                threadId: externalId,
                messages,
              });
            },
            create: async () => {
              const { thread_id } = await createThread();
              return { externalId: thread_id };
            },
            load: async (externalId) => {
              const state = await getThreadState(externalId);
              return {
                messages:
                  (state.values as { messages?: LangChainMessage[] }).messages ?? [],
              };
            },
          });

          return (
            <AssistantRuntimeProvider runtime={runtime}>
              {children}
            </AssistantRuntimeProvider>
          );
        }
        ```
      </Tab>

      <Tab value="Authenticated (Clerk)">
        ```tsx title="app/chat/runtime-provider.tsx"
        "use client";

        import {
          AssistantCloud,
          AssistantRuntimeProvider,
        } from "@assistant-ui/react";
        import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
        import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
        import { LangChainMessage } from "@assistant-ui/react-langgraph";
        import { useAuth } from "@clerk/nextjs";
        import { useMemo } from "react";

        export function MyRuntimeProvider({
          children,
        }: Readonly<{
          children: React.ReactNode;
        }>) {
          const { getToken } = useAuth();

          const cloud = useMemo(
            () =>
              new AssistantCloud({
                baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
                authToken: async () => getToken({ template: "assistant-ui" }),
              }),
            [getToken],
          );

          const runtime = useLangGraphRuntime({
            cloud,
            stream: async function* (messages, { initialize }) {
              const { externalId } = await initialize();
              if (!externalId) throw new Error("Thread not found");

              return sendMessage({
                threadId: externalId,
                messages,
              });
            },
            create: async () => {
              const { thread_id } = await createThread();
              return { externalId: thread_id };
            },
            load: async (externalId) => {
              const state = await getThreadState(externalId);
              return {
                messages:
                  (state.values as { messages?: LangChainMessage[] }).messages ?? [],
              };
            },
          });

          return (
            <AssistantRuntimeProvider runtime={runtime}>
              {children}
            </AssistantRuntimeProvider>
          );
        }
        ```

        <Callout type="info">
          For Clerk authentication, configure the `"assistant-ui"` token template in
          your Clerk dashboard.
        </Callout>
      </Tab>
    </Tabs>

    <Callout type="info">
      The `useLangGraphRuntime` hook now directly accepts `cloud`, `create`, and `load` parameters for simplified thread management. The runtime handles thread lifecycle internally.
    </Callout>
  </Step>

  <Step>
    Add Thread UI Components \[#add-thread-ui-components]

    Install the thread list component:

    <Tabs items={["assistant-ui", "shadcn (namespace)", "shadcn"]}>
      <Tab>
        ```sh
        npx assistant-ui@latest add thread-list
        ```
      </Tab>

      <Tab>
        ```sh
        npx shadcn@latest add https://r.assistant-ui.com/thread-list.json
        ```
      </Tab>

      <Tab>
        ```sh
        npx shadcn@latest add https://r.assistant-ui.com/thread-list.json
        ```
      </Tab>
    </Tabs>

    Then add it to your application layout:

    ```tsx title="app/chat/page.tsx"
    import { Thread } from "@/components/assistant-ui/thread";
    import { ThreadList } from "@/components/assistant-ui/thread-list";

    export default function ChatPage() {
      return (
        <div className="grid h-dvh grid-cols-[250px_1fr] gap-x-2">
          <ThreadList />
          <Thread />
        </div>
      );
    }
    ```
  </Step>
</Steps>

Authentication \[#authentication]

The examples above show two authentication modes:

* **Anonymous**: Suitable for demos and prototypes. Creates a browser session-based user ID.
* **Authenticated**: For production use with user accounts. The authenticated example uses [Clerk](https://clerk.com/), but you can integrate any auth provider.

For other authentication providers or custom implementations, see the [Cloud Authorization](/docs/cloud/authorization) guide.

Next Steps \[#next-steps]

* Learn about [LangGraph runtime setup](/docs/runtimes/langgraph) for your application
* Explore [ThreadListRuntime](/docs/api-reference/runtimes/thread-list-runtime) for advanced thread management
* Check out the [LangGraph example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph) on GitHub


# Overview
URL: /docs/cloud/overview

Add thread persistence and chat history to your AI app in minutes.

Assistant Cloud is a hosted service that adds thread management, message persistence, and user authorization to AI chat applications. It works with any React UI—whether you use assistant-ui components or your own.

What You Get \[#what-you-get]

* **Thread Persistence** — Messages automatically save as conversations progress. Users can resume chats at any time, even across sessions.
* **Thread List** — Built-in UI components (or hooks) for browsing, switching, and managing conversations.
* **Auto-Generated Titles** — Conversations get meaningful titles based on the initial messages.
* **User Authorization** — Integrates with your auth provider to scope threads per user or workspace.

Supported Backends \[#supported-backends]

| Backend   | Standalone Mode                      | With assistant-ui                                   |
| --------- | ------------------------------------ | --------------------------------------------------- |
| AI SDK    | [`useCloudChat`](/docs/cloud/ai-sdk) | [`useChatRuntime`](/docs/cloud/ai-sdk-assistant-ui) |
| LangGraph | —                                    | [`useLangGraphRuntime`](/docs/cloud/langgraph)      |
| Custom    | —                                    | Local Runtime                                       |

Getting Started \[#getting-started]

<Callout type="info">
  You'll need an Assistant Cloud account. [Sign up here](https://cloud.assistant-ui.com/) to create a project.

  From your project settings, copy the **Frontend API URL** (`https://proj-[ID].assistant-api.com`)—you'll need it for the guides below.
</Callout>

Choose Your Integration Path \[#choose-your-integration-path]

**Using AI SDK with your own UI?**\
→ Follow the [AI SDK guide](/docs/cloud/ai-sdk) for the `useCloudChat` hook. One hook, minimal changes to your existing code.

**Want pre-built components like `<Thread />` and `<ThreadList />`?**\
→ Follow the [AI SDK + assistant-ui guide](/docs/cloud/ai-sdk-assistant-ui) for full UI components with cloud persistence.

**Using LangGraph?**\
→ Follow the [LangGraph guide](/docs/cloud/langgraph) for cloud-backed LangGraph Cloud integration.

Example Repositories \[#example-repositories]

* [AI SDK (standalone)](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud-standalone) — Minimal `useCloudChat` setup
* [AI SDK + assistant-ui](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud) — Full component integration
* [LangGraph + assistant-ui](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph) — LangGraph Cloud with persistence


# Assistant Transport
URL: /docs/runtimes/assistant-transport

Stream agent state to the frontend and handle user commands for custom agents.

If you've built an agent as a Python or TypeScript script and want to add a UI to it, you need to solve two problems: streaming updates to the frontend and integrating with the UI framework. Assistant Transport handles both.

Assistant Transport streams your agent's complete state to the frontend in real-time. Unlike traditional approaches that only stream predefined message types (like text or tool calls), it streams your entire agent state—whatever structure your agent uses internally.

It consists of:

* **State streaming**: Efficiently streams updates to your agent state (supports any JSON object)
* **UI integration**: Converts your agent's state into assistant-ui components that render in the browser
* **Command handling**: Sends user actions (messages, tool executions, custom commands) back to your agent

When to Use Assistant Transport \[#when-to-use-assistant-transport]

Use Assistant Transport when:

* You don't have a streaming protocol yet and need one
* You want your agent's native state to be directly accessible in the frontend
* You're building a custom agent framework or one without a streaming protocol (e.g. OSS LangGraph)

Mental Model \[#mental-model]

<Mermaid chart="graph LR\n    Frontend -->|Commands| Agent[Agent Server]\n    Agent -->|State Snapshots| Frontend" />

The frontend receives state snapshots and converts them to React components. The goal is to have the UI be a stateless view on top of the agent framework state.

The agent server receives commands from the frontend. When a user interacts with the UI (sends a message, clicks a button, etc.), the frontend queues a command and sends it to the backend. Assistant Transport defines standard commands like `add-message` and `add-tool-result`, and you can define custom commands.

Command Lifecycle \[#command-lifecycle]

Commands go through the following lifecycle:

<Mermaid chart="graph LR\n    queued -->|sent to backend| in_transit\n    in_transit -->|backend processes| applied" />

The runtime alternates between **idle** (no active backend request) and **sending** (request in flight). When a new command is created while idle, it's immediately sent. Otherwise, it's queued until the current request completes.

<Mermaid chart="graph LR\n    idle -->|new command| sending\n    sending -->|request completes| check{check queue}\n    check -->|queue has commands| sending\n    check -->|queue empty| idle" />

To implement this architecture, you need to build 2 pieces:

1. **Backend endpoint** on the agent server that accepts commands and returns a stream of state snapshots
2. **Frontend-side [state converter](#state-converter)** that converts state snapshots to assistant-ui's data format so that the UI primitives work

Building a Backend Endpoint \[#building-a-backend-endpoint]

Let's build the backend endpoint step by step. You'll need to handle incoming commands, update your agent state, and stream the updates back to the frontend.

The backend endpoint receives POST requests with the following payload:

```typescript
{
  state: T, // The previous state that the frontend has access to
  commands: AssistantTransportCommand[],
  system?: string,
  tools?: ToolDefinition[],
  threadId: string // The current thread/conversation identifier
}
```

The backend endpoint returns a stream of state snapshots using the `assistant-stream` library ([npm](https://www.npmjs.com/package/assistant-stream) / [PyPI](https://pypi.org/project/assistant-stream/)).

Handling Commands \[#handling-commands]

The backend endpoint processes commands from the `commands` array:

```python
for command in request.commands:
    if command.type == "add-message":
        # Handle adding a user message
    elif command.type == "add-tool-result":
        # Handle tool execution result
    elif command.type == "my-custom-command":
        # Handle your custom command
```

Streaming Updates \[#streaming-updates]

To stream state updates, modify `controller.state` within your run callback:

```python
from assistant_stream import RunController, create_run
from assistant_stream.serialization import DataStreamResponse

@app.post("/assistant")
async def chat_endpoint(request: ChatRequest):
    async def run_callback(controller: RunController):
        # Emits "set" at path ["message"] with value "Hello"
        controller.state["message"] = "Hello"

        # Emits "append-text" at path ["message"] with value " World"
        controller.state["message"] += " World"

    # Create and return the stream
    stream = create_run(run_callback, state=request.state)
    return DataStreamResponse(stream)
```

The state snapshots are automatically streamed to the frontend using the operations described in [Streaming Protocol](#streaming-protocol).

> **Cancellation:** `create_run` exposes `controller.is_cancelled` and `controller.cancelled_event`.
> If the response stream is closed early (for example user cancel or client disconnect),
> these are set so your backend loop can exit cooperatively.
> `controller.cancelled_event` is a read-only signal object with `wait()` and `is_set()`.
> `create_run` gives callbacks a \~50ms cooperative shutdown window before forced task cancellation.
> Callback exceptions that happen during early-close cleanup are not re-raised to the stream consumer,
> but are logged with traceback at warning level for debugging.
> Put critical cleanup in `finally` blocks, since forced cancellation may happen after the grace window.
>
> ```python
> async def run_callback(controller: RunController):
>     while not controller.is_cancelled:
>         # Long-running work / model loop
>         await asyncio.sleep(0.05)
> ```
>
> ```python
> async def run_callback(controller: RunController):
>     await controller.cancelled_event.wait()
>     # cancellation-aware shutdown path
> ```

Backend Reference Implementation \[#backend-reference-implementation]

<Tabs items={["Minimal", "Example", "LangGraph"]}>
  <Tab>
    ```python
    from assistant_stream import RunController, create_run
    from assistant_stream.serialization import DataStreamResponse

    async def run_callback(controller: RunController):
        # Initialize state
        if controller.state is None:
            controller.state = {}

        # Process commands
        for command in request.commands:
            # Handle commands...

        # Run your agent and stream updates
        async for event in agent.stream():
            # update controller.state
            pass

    # Create and return the stream
    stream = create_run(run_callback, state=request.state)
    return DataStreamResponse(stream)
    ```
  </Tab>

  <Tab>
    ```python
    from assistant_stream.serialization import DataStreamResponse
    from assistant_stream import RunController, create_run

    @app.post("/assistant")
    async def chat_endpoint(request: ChatRequest):
        """Chat endpoint with custom agent streaming."""

        async def run_callback(controller: RunController):
            # Initialize controller state
            if controller.state is None:
                controller.state = {"messages": []}

            # Process commands
            for command in request.commands:
                if command.type == "add-message":
                    # Add message to messages array
                    controller.state["messages"].append(command.message)

            # Run your custom agent and stream updates
            async for message in your_agent.stream():
                # Push message to messages array
                controller.state["messages"].append(message)

        # Create streaming response
        stream = create_run(run_callback, state=request.state)
        return DataStreamResponse(stream)
    ```
  </Tab>

  <Tab>
    ```python
    from assistant_stream.serialization import DataStreamResponse
    from assistant_stream import RunController, create_run
    from assistant_stream.modules.langgraph import append_langgraph_event

    @app.post("/assistant")
    async def chat_endpoint(request: ChatRequest):
        """Chat endpoint using LangGraph with streaming."""

        async def run_callback(controller: RunController):
            # Initialize controller state
            if controller.state is None:
                controller.state = {}
            if "messages" not in controller.state:
                controller.state["messages"] = []

            input_messages = []

            # Process commands
            for command in request.commands:
                if command.type == "add-message":
                    text_parts = [
                        part.text for part in command.message.parts
                        if part.type == "text" and part.text
                    ]
                    if text_parts:
                        input_messages.append(HumanMessage(content=" ".join(text_parts)))

            # Create initial state for LangGraph
            input_state = {"messages": input_messages}

            # Stream events from LangGraph
            async for namespace, event_type, chunk in graph.astream(
                input_state,
                stream_mode=["messages", "updates"],
                subgraphs=True
            ):
                append_langgraph_event(
                    controller.state,
                    namespace,
                    event_type,
                    chunk
                )

        # Create streaming response
        stream = create_run(run_callback, state=request.state)
        return DataStreamResponse(stream)
    ```
  </Tab>
</Tabs>

Full example: [`python/assistant-transport-backend-langgraph`](https://github.com/assistant-ui/assistant-ui/tree/main/python/assistant-transport-backend-langgraph)

Streaming Protocol \[#streaming-protocol]

The assistant-stream state replication protocol allows for streaming updates to an arbitrary JSON object.

Operations \[#operations]

The protocol supports two operations:

> **Note:** We've found that these two operations are enough to handle all sorts of complex state operations efficiently. `set` handles value updates and nested structures, while `append-text` enables efficient streaming of text content.

set \[#set]

Sets a value at a specific path in the JSON object.

```json
// Operation
{ "type": "set", "path": ["status"], "value": "completed" }

// Before
{ "status": "pending" }

// After
{ "status": "completed" }
```

append-text \[#append-text]

Appends text to an existing string value at a path.

```json
// Operation
{ "type": "append-text", "path": ["message"], "value": " World" }

// Before
{ "message": "Hello" }

// After
{ "message": "Hello World" }
```

Wire Format \[#wire-format]

<Callout type="warn">
  The wire format will be migrated to Server-Sent Events (SSE) in a future
  release.
</Callout>

The wire format is inspired by [AI SDK's data stream protocol](https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol).

**State Update:**

```
aui-state:ObjectStreamOperation[]
```

```
aui-state:[{"type":"set","path":["status"],"value":"completed"}]
```

**Error:**

```
3:string
```

```
3:"error message"
```

Building a Frontend \[#building-a-frontend]

Now let's set up the frontend. The state converter is the heart of the integration—it transforms your agent's state into the format assistant-ui expects.

The `useAssistantTransportRuntime` hook is used to configure the runtime. It accepts the following config:

```typescript
{
  initialState: T,
  api: string,
  resumeApi?: string,
  converter: (state: T, connectionMetadata: ConnectionMetadata) => AssistantTransportState,
  headers?: Record<string, string> | (() => Promise<Record<string, string>>),
  body?: object,
  prepareSendCommandsRequest?: (body: SendCommandsRequestBody) => Record<string, unknown> | Promise<Record<string, unknown>>,
  capabilities?: { edit?: boolean },
  onResponse?: (response: Response) => void,
  onFinish?: () => void,
  onError?: (error: Error) => void,
  onCancel?: () => void
}
```

State Converter \[#state-converter]

The state converter is the core of your frontend integration. It transforms your agent's state into assistant-ui's message format.

```typescript
(
  state: T, // Your agent's state
  connectionMetadata: {
    pendingCommands: Command[], // Commands not yet sent to backend
    isSending: boolean // Whether a request is in flight
  }
) => {
  messages: ThreadMessage[], // Messages to display
  isRunning: boolean // Whether the agent is running
}
```

Converting Messages \[#converting-messages]

Use the `createMessageConverter` API to transform your agent's messages to assistant-ui format:

<Tabs items={["Example", "LangChain"]}>
  <Tab>
    ```typescript
    import { unstable_createMessageConverter as createMessageConverter } from "@assistant-ui/react";

    // Define your message type
    type YourMessageType = {
      id: string;
      role: "user" | "assistant";
      content: string;
      timestamp: number;
    };

    // Define a converter function for a single message
    const exampleMessageConverter = (message: YourMessageType) => {
      // Transform a single message to assistant-ui format
      return {
        role: message.role,
        content: [{ type: "text", text: message.content }]
      };
    };

    const messageConverter = createMessageConverter(exampleMessageConverter);

    const converter = (state: YourAgentState) => {
      return {
        messages: messageConverter.toThreadMessages(state.messages),
        isRunning: false
      };
    };
    ```
  </Tab>

  <Tab>
    ```typescript
    import { unstable_createMessageConverter as createMessageConverter } from "@assistant-ui/react";
    import { convertLangChainMessages } from "@assistant-ui/react-langgraph";

    const messageConverter = createMessageConverter(convertLangChainMessages);

    const converter = (state: YourAgentState) => {
      return {
        messages: messageConverter.toThreadMessages(state.messages),
        isRunning: false
      };
    };
    ```
  </Tab>
</Tabs>

**Reverse mapping:**

The message converter allows you to retrieve the original message format anywhere inside assistant-ui. This lets you access your agent's native message structure from any assistant-ui component:

```typescript
// Get original message(s) from a ThreadMessage anywhere in assistant-ui
const originalMessage = messageConverter.toOriginalMessage(threadMessage);
```

Optimistic Updates from Commands \[#optimistic-updates-from-commands]

The converter also receives `connectionMetadata` which contains pending commands. Use this to show optimistic updates:

```typescript
const converter = (state: State, connectionMetadata: ConnectionMetadata) => {
  // Extract pending messages from commands
  const optimisticMessages = connectionMetadata.pendingCommands
    .filter((c) => c.type === "add-message")
    .map((c) => c.message);

  return {
    messages: [...state.messages, ...optimisticMessages],
    isRunning: connectionMetadata.isSending || false
  };
};
```

Handling Errors and Cancellations \[#handling-errors-and-cancellations]

The `onError` and `onCancel` callbacks receive an `updateState` function that allows you to update the agent state on the client side without making a server request:

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  onError: (error, { commands, updateState }) => {
    console.error("Error occurred:", error);
    console.log("Commands in transit:", commands);

    // Update state to reflect the error
    updateState((currentState) => ({
      ...currentState,
      lastError: error.message,
    }));
  },
  onCancel: ({ commands, updateState }) => {
    console.log("Request cancelled");
    console.log("Commands in transit or queued:", commands);

    // Update state to reflect cancellation
    updateState((currentState) => ({
      ...currentState,
      status: "cancelled",
    }));
  },
});
```

> **Note:** `onError` receives commands that were in transit, while `onCancel` receives both in-transit and queued commands.

Custom Headers and Body \[#custom-headers-and-body]

You can pass custom headers and body to the backend endpoint:

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  headers: {
    "Authorization": "Bearer token",
    "X-Custom-Header": "value",
  },
  body: {
    customField: "value",
  },
});
```

Dynamic Headers and Body \[#dynamic-headers-and-body]

You can also evaluate the header and body payloads on every request by passing an async function:

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  headers: async () => ({
    "Authorization": `Bearer ${await getAccessToken()}`,
    "X-Request-ID": crypto.randomUUID(),
  }),
  body: async () => ({
    customField: "value",
    requestId: crypto.randomUUID(),
    timestamp: Date.now(),
  }),
});
```

Transforming the Request Body \[#transforming-the-request-body]

Use `prepareSendCommandsRequest` to transform the entire request body before it is sent to the backend. This receives the fully assembled body object and returns the (potentially transformed) body.

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  prepareSendCommandsRequest: (body) => ({
    ...body,
    trackingId: crypto.randomUUID(),
  }),
});
```

This is useful for adding tracking IDs, transforming commands, or injecting metadata that depends on the assembled request:

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  prepareSendCommandsRequest: (body) => ({
    ...body,
    commands: body.commands.map((cmd) =>
      cmd.type === "add-message"
        ? { ...cmd, trackingId: crypto.randomUUID() }
        : cmd,
    ),
  }),
});
```

Editing Messages \[#editing-messages]

By default, editing messages is disabled. To enable it, set `capabilities.edit` to `true`:

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  capabilities: {
    edit: true,
  },
});
```

`add-message` commands always include `parentId` and `sourceId` fields:

```typescript
{
  type: "add-message",
  message: { role: "user", parts: [...] },
  parentId: "msg-3",  // The message after which this message should be inserted
  sourceId: "msg-4",  // The ID of the message being replaced (null for new messages)
}
```

Backend Handling \[#backend-handling]

When the backend receives an `add-message` command with a `parentId`, it should:

1. Truncate all messages after the message with `parentId`
2. Append the new message
3. Stream the updated state back to the frontend

```python
for command in request.commands:
    if command.type == "add-message":
        if hasattr(command, "parentId") and command.parentId is not None:
            # Find the parent message index and truncate
            parent_idx = next(
                i for i, m in enumerate(messages) if m.id == command.parentId
            )
            messages = messages[:parent_idx + 1]
        # Append the new message
        messages.append(command.message)
```

<Callout type="info">
  `parentId` and `sourceId` are always included on `add-message` commands. For new messages, `sourceId` will be `null`.
</Callout>

Resuming from a Sync Server \[#resuming-from-a-sync-server]

<Callout type="info">
  We provide a sync server currently only as part of the enterprise plan. Please
  contact us for more information.
</Callout>

To enable resumability, you need to:

1. Pass a `resumeApi` URL to `useAssistantTransportRuntime` that points to your sync server
2. Use the `unstable_resumeRun` API to resume a conversation

```typescript
import { useAui } from "@assistant-ui/react";

const runtime = useAssistantTransportRuntime({
  // ... other options
  api: "http://localhost:8010/assistant",
  resumeApi: "http://localhost:8010/resume", // Sync server endpoint
  // ... other options
});

// Typically called on thread switch or mount to check if sync server has anything to resume
const aui = useAui();
aui.thread().unstable_resumeRun({
  parentId: null, // Ignored (will be removed in a future version)
});
```

Accessing Runtime State \[#accessing-runtime-state]

Use the `useAssistantTransportState` hook to access the current agent state from any component:

```typescript
import { useAssistantTransportState } from "@assistant-ui/react";

function MyComponent() {
  const state = useAssistantTransportState();

  return <div>{JSON.stringify(state)}</div>;
}
```

You can also pass a selector function to extract specific values:

```typescript
function MyComponent() {
  const messages = useAssistantTransportState((state) => state.messages);

  return <div>Message count: {messages.length}</div>;
}
```

Type Safety \[#type-safety]

Use module augmentation to add types for your agent state:

```typescript title="assistant.config.ts"
import "@assistant-ui/react";

declare module "@assistant-ui/react" {
  namespace Assistant {
    interface ExternalState {
      myState: {
        messages: Message[];
        customField: string;
      };
    }
  }
}
```

> **Note:** Place this file anywhere in your project (e.g., `src/assistant.config.ts` or at the project root). TypeScript will automatically pick up the type augmentation through module resolution—you don't need to import this file anywhere.

After adding the type augmentation, `useAssistantTransportState` will be fully typed:

```typescript
function MyComponent() {
  // TypeScript knows about your custom fields
  const customField = useAssistantTransportState((state) => state.customField);

  return <div>{customField}</div>;
}
```

Accessing the Original Message \[#accessing-the-original-message]

If you're using `createMessageConverter`, you can access the original message format from any assistant-ui component using the converter's `toOriginalMessage` method:

```typescript
import { unstable_createMessageConverter as createMessageConverter } from "@assistant-ui/react";
import { useMessage } from "@assistant-ui/react";

const messageConverter = createMessageConverter(yourMessageConverter);

function MyMessageComponent() {
  const message = useMessage();

  // Get the original message(s) from the converted ThreadMessage
  const originalMessage = messageConverter.toOriginalMessage(message);

  // Access your agent's native message structure
  return <div>{originalMessage.yourCustomField}</div>;
}
```

You can also use `toOriginalMessages` to get all original messages when a ThreadMessage was created from multiple source messages:

```typescript
const originalMessages = messageConverter.toOriginalMessages(message);
```

Frontend Reference Implementation \[#frontend-reference-implementation]

<Tabs items={["Example", "LangGraph"]}>
  <Tab>
    ```tsx
    "use client";

    import {
      AssistantRuntimeProvider,
      AssistantTransportConnectionMetadata,
      useAssistantTransportRuntime,
    } from "@assistant-ui/react";

    type State = {
      messages: Message[];
    };

    // Converter function: transforms agent state to assistant-ui format
    const converter = (
      state: State,
      connectionMetadata: AssistantTransportConnectionMetadata,
    ) => {
      // Add optimistic updates for pending commands
      const optimisticMessages = connectionMetadata.pendingCommands
        .filter((c) => c.type === "add-message")
        .map((c) => c.message);

      return {
        messages: [...state.messages, ...optimisticMessages],
        isRunning: connectionMetadata.isSending || false,
      };
    };

    export function MyRuntimeProvider({ children }) {
      const runtime = useAssistantTransportRuntime({
        initialState: {
          messages: [],
        },
        api: "http://localhost:8010/assistant",
        converter,
        headers: async () => ({
          "Authorization": "Bearer token",
        }),
        body: {
          "custom-field": "custom-value",
        },
        onResponse: (response) => {
          console.log("Response received from server");
        },
        onFinish: () => {
          console.log("Conversation completed");
        },
        onError: (error, { commands, updateState }) => {
          console.error("Assistant transport error:", error);
          console.log("Commands in transit:", commands);
        },
        onCancel: ({ commands, updateState }) => {
          console.log("Request cancelled");
          console.log("Commands in transit or queued:", commands);
        },
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Tab>

  <Tab>
    ```tsx
    "use client";

    import {
      AssistantRuntimeProvider,
      AssistantTransportConnectionMetadata,
      unstable_createMessageConverter as createMessageConverter,
      useAssistantTransportRuntime,
    } from "@assistant-ui/react";
    import {
      convertLangChainMessages,
      LangChainMessage,
    } from "@assistant-ui/react-langgraph";

    type State = {
      messages: LangChainMessage[];
    };

    const LangChainMessageConverter = createMessageConverter(
      convertLangChainMessages,
    );

    // Converter function: transforms agent state to assistant-ui format
    const converter = (
      state: State,
      connectionMetadata: AssistantTransportConnectionMetadata,
    ) => {
      // Add optimistic updates for pending commands
      const optimisticStateMessages = connectionMetadata.pendingCommands.map(
        (c): LangChainMessage[] => {
          if (c.type === "add-message") {
            return [
              {
                type: "human" as const,
                content: [
                  {
                    type: "text" as const,
                    text: c.message.parts
                      .map((p) => (p.type === "text" ? p.text : ""))
                      .join("\n"),
                  },
                ],
              },
            ];
          }
          return [];
        },
      );

      const messages = [...state.messages, ...optimisticStateMessages.flat()];

      return {
        messages: LangChainMessageConverter.toThreadMessages(messages),
        isRunning: connectionMetadata.isSending || false,
      };
    };

    export function MyRuntimeProvider({ children }) {
      const runtime = useAssistantTransportRuntime({
        initialState: {
          messages: [],
        },
        api: "http://localhost:8010/assistant",
        converter,
        headers: async () => ({
          "Authorization": "Bearer token",
        }),
        body: {
          "custom-field": "custom-value",
        },
        onResponse: (response) => {
          console.log("Response received from server");
        },
        onFinish: () => {
          console.log("Conversation completed");
        },
        onError: (error, { commands, updateState }) => {
          console.error("Assistant transport error:", error);
          console.log("Commands in transit:", commands);
        },
        onCancel: ({ commands, updateState }) => {
          console.log("Request cancelled");
          console.log("Commands in transit or queued:", commands);
        },
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Tab>
</Tabs>

Full example: [`examples/with-assistant-transport`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-assistant-transport)

Custom Commands \[#custom-commands]

Defining Custom Commands \[#defining-custom-commands]

Use module augmentation to define a custom command:

```typescript title="assistant.config.ts"
import "@assistant-ui/react";

declare module "@assistant-ui/react" {
  namespace Assistant {
    interface Commands {
      myCustomCommand: {
        type: "my-custom-command";
        data: string;
      };
    }
  }
}
```

Issuing Commands \[#issuing-commands]

Use the `useAssistantTransportSendCommand` hook to send custom commands:

```typescript
import { useAssistantTransportSendCommand } from "@assistant-ui/react";

function MyComponent() {
  const sendCommand = useAssistantTransportSendCommand();

  const handleClick = () => {
    sendCommand({
      type: "my-custom-command",
      data: "Hello, world!",
    });
  };

  return <button onClick={handleClick}>Send Custom Command</button>;
}
```

Backend Integration \[#backend-integration]

The backend receives custom commands in the `commands` array, just like built-in commands:

```python
for command in request.commands:
    if command.type == "add-message":
        # Handle add-message command
    elif command.type == "add-tool-result":
        # Handle add-tool-result command
    elif command.type == "my-custom-command":
        # Handle your custom command
        data = command.data
```

Optimistic Updates \[#optimistic-updates]

Update the [state converter](#state-converter) to optimistically handle the custom command:

```typescript
const converter = (state: State, connectionMetadata: ConnectionMetadata) => {
  // Filter custom commands from pending commands
  const customCommands = connectionMetadata.pendingCommands.filter(
    (c) => c.type === "my-custom-command"
  );

  // Apply optimistic updates based on custom commands
  const optimisticState = {
    ...state,
    customData: customCommands.map((c) => c.data),
  };

  return {
    messages: state.messages,
    state: optimisticState,
    isRunning: connectionMetadata.isSending || false,
  };
};
```

Cancellation and Error Behavior \[#cancellation-and-error-behavior]

Custom commands follow the same lifecycle as built-in commands. You can update your `onError` and `onCancel` handlers to take custom commands into account:

```typescript
const runtime = useAssistantTransportRuntime({
  // ... other options
  onError: (error, { commands, updateState }) => {
    // Check if any custom commands were in transit
    const customCommands = commands.filter((c) => c.type === "my-custom-command");

    if (customCommands.length > 0) {
      // Handle custom command errors
      updateState((state) => ({
        ...state,
        customCommandFailed: true,
      }));
    }
  },
  onCancel: ({ commands, updateState }) => {
    // Check if any custom commands were queued or in transit
    const customCommands = commands.filter((c) => c.type === "my-custom-command");

    if (customCommands.length > 0) {
      // Handle custom command cancellation
      updateState((state) => ({
        ...state,
        customCommandCancelled: true,
      }));
    }
  },
});
```


# Data Stream Protocol
URL: /docs/runtimes/data-stream

Integration with data stream protocol endpoints for streaming AI responses.

The `@assistant-ui/react-data-stream` package provides integration with data stream protocol endpoints, enabling streaming AI responses with tool support and state management.

Overview \[#overview]

The data stream protocol is a standardized format for streaming AI responses that supports:

* **Streaming text responses** with real-time updates
* **Tool calling** with structured parameters and results
* **State management** for conversation context
* **Error handling** and cancellation support
* **Attachment support** for multimodal interactions

Installation \[#installation]

<InstallCommand npm={["@assistant-ui/react-data-stream"]} />

Basic Usage \[#basic-usage]

<Steps>
  <Step>
    Set up the Runtime \[#set-up-the-runtime]

    Use `useDataStreamRuntime` to connect to your data stream endpoint:

    ```tsx title="app/page.tsx"
    "use client";
    import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
    import { AssistantRuntimeProvider } from "@assistant-ui/react";
    import { Thread } from "@/components/assistant-ui/thread";

    export default function ChatPage() {
      const runtime = useDataStreamRuntime({
        api: "/api/chat",
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <Thread />
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Create Backend Endpoint \[#create-backend-endpoint]

    Your backend endpoint should accept POST requests and return data stream responses:

    ```typescript title="app/api/chat/route.ts"
    import { createAssistantStreamResponse } from "assistant-stream";

    export async function POST(request: Request) {
      const { messages, tools, system, threadId } = await request.json();

      return createAssistantStreamResponse(async (controller) => {
        // Process the request with your AI provider
        const stream = await processWithAI({
          messages,
          tools,
          system,
        });

        // Stream the response
        for await (const chunk of stream) {
          controller.appendText(chunk.text);
        }
      });
    }
    ```

    The request body includes:

    * `messages` - The conversation history
    * `tools` - Available tool definitions
    * `system` - System prompt (if configured)
    * `threadId` - The current thread/conversation identifier
  </Step>
</Steps>

Advanced Configuration \[#advanced-configuration]

Custom Headers and Authentication \[#custom-headers-and-authentication]

```tsx
const runtime = useDataStreamRuntime({
  api: "/api/chat",
  headers: {
    "Authorization": "Bearer " + token,
    "X-Custom-Header": "value",
  },
  credentials: "include",
});
```

Dynamic Headers \[#dynamic-headers]

```tsx
const runtime = useDataStreamRuntime({
  api: "/api/chat",
  headers: async () => {
    const token = await getAuthToken();
    return {
      "Authorization": "Bearer " + token,
    };
  },
});
```

Dynamic Body \[#dynamic-body]

```tsx
const runtime = useDataStreamRuntime({
  api: "/api/chat",
  headers: async () => ({
    "Authorization": `Bearer ${await getAuthToken()}`,
  }),
  body: async () => ({
    requestId: crypto.randomUUID(),
    timestamp: Date.now(),
    signature: await computeSignature(),
  }),
});
```

Event Callbacks \[#event-callbacks]

```tsx
const runtime = useDataStreamRuntime({
  api: "/api/chat",
  onResponse: (response) => {
    console.log("Response received:", response.status);
  },
  onFinish: (message) => {
    console.log("Message completed:", message);
  },
  onError: (error) => {
    console.error("Error occurred:", error);
  },
  onCancel: () => {
    console.log("Request cancelled");
  },
});
```

Tool Integration \[#tool-integration]

<Callout type="warn">
  Human-in-the-loop tools (using `human()` for tool interrupts) are not supported
  in the data stream runtime. If you need human approval workflows or interactive
  tool UIs, consider using [LocalRuntime](/docs/runtimes/custom/local) or
  [Assistant Cloud](/docs/cloud/overview) instead.
</Callout>

Frontend Tools \[#frontend-tools]

Use the `frontendTools` helper to serialize client-side tools:

```tsx
import { frontendTools } from "@assistant-ui/react-data-stream";
import { makeAssistantTool } from "@assistant-ui/react";

const weatherTool = makeAssistantTool({
  toolName: "get_weather",
  description: "Get current weather",
  parameters: z.object({
    location: z.string(),
  }),
  execute: async ({ location }) => {
    const weather = await fetchWeather(location);
    return `Weather in ${location}: ${weather}`;
  },
});

const runtime = useDataStreamRuntime({
  api: "/api/chat",
  body: {
    tools: frontendTools({
      get_weather: weatherTool,
    }),
  },
});
```

Backend Tool Processing \[#backend-tool-processing]

Your backend should handle tool calls and return results:

```typescript title="Backend tool handling"
// Tools are automatically forwarded to your endpoint
const { tools } = await request.json();

// Process tools with your AI provider
const response = await ai.generateText({
  messages,
  tools,
  // Tool results are streamed back automatically
});
```

Assistant Cloud Integration \[#assistant-cloud-integration]

For Assistant Cloud deployments, use `useCloudRuntime`:

```tsx
import { useCloudRuntime } from "@assistant-ui/react-data-stream";

const runtime = useCloudRuntime({
  cloud: assistantCloud,
  assistantId: "my-assistant-id",
});
```

<Callout type="info">
  The `useCloudRuntime` hook is currently under active development and not yet ready for production use.
</Callout>

Message Conversion \[#message-conversion]

Framework-Agnostic Conversion (Recommended) \[#framework-agnostic-conversion-recommended]

For custom integrations, use the framework-agnostic utilities from `assistant-stream`:

```tsx
import { toGenericMessages, toToolsJSONSchema } from "assistant-stream";

// Convert messages to a generic format
const genericMessages = toGenericMessages(messages);

// Convert tools to JSON Schema format
const toolSchemas = toToolsJSONSchema(tools);
```

The `GenericMessage` format can be easily converted to any LLM provider format:

```tsx
import type { GenericMessage } from "assistant-stream";

// GenericMessage is a union of:
// - { role: "system"; content: string }
// - { role: "user"; content: (GenericTextPart | GenericFilePart)[] }
// - { role: "assistant"; content: (GenericTextPart | GenericToolCallPart)[] }
// - { role: "tool"; content: GenericToolResultPart[] }
```

AI SDK Specific Conversion \[#ai-sdk-specific-conversion]

For AI SDK integration, use `toLanguageModelMessages`:

```tsx
import { toLanguageModelMessages } from "@assistant-ui/react-data-stream";

// Convert to AI SDK LanguageModelV2Message format
const languageModelMessages = toLanguageModelMessages(messages, {
  unstable_includeId: true, // Include message IDs
});
```

<Callout type="info">
  `toLanguageModelMessages` internally uses `toGenericMessages` and adds AI SDK-specific transformations.
  For new custom integrations, prefer using `toGenericMessages` directly.
</Callout>

Error Handling \[#error-handling]

The runtime automatically handles common error scenarios:

* **Network errors**: Automatically retried with exponential backoff
* **Stream interruptions**: Gracefully handled with partial content preservation
* **Tool execution errors**: Displayed in the UI with error states
* **Cancellation**: Clean abort signal handling

Best Practices \[#best-practices]

Performance Optimization \[#performance-optimization]

```tsx
// Use React.memo for expensive components
const OptimizedThread = React.memo(Thread);

// Memoize runtime configuration
const runtimeConfig = useMemo(() => ({
  api: "/api/chat",
  headers: { "Authorization": `Bearer ${token}` },
}), [token]);

const runtime = useDataStreamRuntime(runtimeConfig);
```

Error Boundaries \[#error-boundaries]

```tsx
import { ErrorBoundary } from "react-error-boundary";

function ChatErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <h2>Something went wrong:</h2>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

export default function App() {
  return (
    <ErrorBoundary FallbackComponent={ChatErrorFallback}>
      <AssistantRuntimeProvider runtime={runtime}>
        <Thread />
      </AssistantRuntimeProvider>
    </ErrorBoundary>
  );
}
```

State Persistence \[#state-persistence]

```tsx
const runtime = useDataStreamRuntime({
  api: "/api/chat",
  body: {
    // Include conversation state
    state: conversationState,
  },
  onFinish: (message) => {
    // Save state after each message
    saveConversationState(message.metadata.unstable_state);
  },
});
```

Examples \[#examples]

Explore our [examples repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples) for implementation references.

API Reference \[#api-reference]

For detailed API documentation, see the [`@assistant-ui/react-data-stream` API Reference](/docs/api-reference/integrations/react-data-stream).


# Helicone
URL: /docs/runtimes/helicone

Configure Helicone proxy for OpenAI API logging and monitoring.

Helicone acts as a proxy for your OpenAI API calls, enabling detailed logging and monitoring. To integrate, update your API base URL and add the Helicone-Auth header.

AI SDK by vercel \[#ai-sdk-by-vercel]

1. **Set Environment Variables:**

   * `HELICONE_API_KEY`
   * `OPENAI_API_KEY`

2. **Configure the OpenAI client:**

```ts
import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";

const openai = createOpenAI({
  baseURL: "https://oai.helicone.ai/v1",
  headers: {
    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
  },
});

export async function POST(req: Request) {
  const { prompt } = await req.json();
  return streamText({
    model: openai("gpt-4o"),
    prompt,
  });
}
```

LangChain Integration (Python) \[#langchain-integration-python]

1. **Set Environment Variables:**

   * `HELICONE_API_KEY`
   * `OPENAI_API_KEY`

2. **Configure ChatOpenAI:**

```python
from langchain.chat_models import ChatOpenAI
import os

llm = ChatOpenAI(
    model_name="gpt-3.5-turbo",
    temperature=0,
    openai_api_base="https://oai.helicone.ai/v1",
    openai_api_key=os.environ["OPENAI_API_KEY"],
    openai_api_headers={"Helicone-Auth": f"Bearer {os.environ['HELICONE_API_KEY']}"}
)
```

Summary \[#summary]

Update your API base URL to `https://oai.helicone.ai/v1` and add the `Helicone-Auth` header with your API key either in your Vercel AI SDK or LangChain configuration.


# LangChain LangServe
URL: /docs/runtimes/langserve

Connect to LangServe endpoints via Vercel AI SDK integration.

<Callout type="warning">
  This integration has not been tested with AI SDK v5.
</Callout>

Overview \[#overview]

Integration with a LangServe server via Vercel AI SDK.

Getting Started \[#getting-started]

<Steps>
  <Step>
    Create a Next.JS project \[#create-a-nextjs-project]

    ```sh
    npx create-next-app@latest my-app
    cd my-app
    ```
  </Step>

  <Step>
    Install @langchain/core, AI SDK and @assistant-ui/react \[#install-langchaincore-ai-sdk-and-assistant-uireact]

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk", "ai", "@ai-sdk/react", "@langchain/core"]} />
  </Step>

  <Step>
    Setup a backend route under /api/chat \[#setup-a-backend-route-under-apichat]

    ```tsx title="@/app/api/chat/route.ts"
    import { RemoteRunnable } from "@langchain/core/runnables/remote";
    import { toDataStreamResponse } from "@ai-sdk/langchain";

    export const maxDuration = 30;

    export async function POST(req: Request) {
      const { messages } = await req.json();

      // TODO replace with your own langserve URL
      const remoteChain = new RemoteRunnable({
        url: "<YOUR_LANGSERVE_URL>",
      });

      const stream = await remoteChain.stream({
        messages,
      });

      return toDataStreamResponse(stream);
    }
    ```
  </Step>

  <Step>
    Define a MyRuntimeProvider component \[#define-a-myruntimeprovider-component]

    ```tsx twoslash include MyRuntimeProvider title="@/app/MyRuntimeProvider.tsx"
    // @filename: /app/MyRuntimeProvider.tsx
    // ---cut---
    "use client";

    import { useChat } from "@ai-sdk/react";
    import { AssistantRuntimeProvider } from "@assistant-ui/react";
    import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

    export function MyRuntimeProvider({
      children,
    }: Readonly<{
      children: React.ReactNode;
    }>) {
      const runtime = useChatRuntime();

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Wrap your app in MyRuntimeProvider \[#wrap-your-app-in-myruntimeprovider]

    ```tsx twoslash title="@/app/layout.tsx"
    // @include: MyRuntimeProvider
    // @filename: /app/layout.tsx
    // ---cut---
    import type { ReactNode } from "react";
    import { MyRuntimeProvider } from "@/app/MyRuntimeProvider";

    export default function RootLayout({
      children,
    }: Readonly<{
      children: ReactNode;
    }>) {
      return (
        <MyRuntimeProvider>
          <html lang="en">
            <body>{children}</body>
          </html>
        </MyRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>


# Picking a Runtime
URL: /docs/runtimes/pick-a-runtime

Which runtime fits your backend? Decision guide for common setups.

Choosing the right runtime is crucial for your assistant-ui implementation. This guide helps you navigate the options based on your specific needs.

Quick Decision Tree \[#quick-decision-tree]

<Mermaid chart="graph TD\n    A[What's your starting point?] --> B{Existing Framework?}\n    B -->|Vercel AI SDK| C[Use AI SDK Integration]\n    B -->|LangGraph| D[Use LangGraph Runtime]\n    B -->|LangServe| E[Use LangServe Runtime]\n    B -->|Mastra| F[Use Mastra Runtime]\n    B -->|Custom Backend| G{State Management?}\n    G -->|Let assistant-ui handle it| H[Use LocalRuntime]\n    G -->|I'll manage it myself| I[Use ExternalStoreRuntime]" />

Core Runtimes \[#core-runtimes]

These are the foundational runtimes that power assistant-ui:

<Cards>
  <Card title="`LocalRuntime`" description="assistant-ui manages chat state internally. Simple adapter pattern for any backend." href="/docs/runtimes/custom/local" />

  <Card title="`ExternalStoreRuntime`" description="You control the state. Perfect for Redux, Zustand, or existing state management." href="/docs/runtimes/custom/external-store" />
</Cards>

Pre-Built Integrations \[#pre-built-integrations]

For popular frameworks, we provide ready-to-use integrations built on top of our core runtimes:

<Cards>
  <Card title="Vercel AI SDK" description="For useChat and useAssistant hooks - streaming with all major providers" href="/docs/runtimes/ai-sdk/use-chat" />

  <Card title="Data Stream Protocol" description="For custom backends using the data stream protocol standard" href="/docs/runtimes/data-stream" />

  <Card title="LangGraph" description="For complex agent workflows with LangChain's graph framework" href="/docs/runtimes/langgraph" />

  <Card title="LangServe" description="For LangChain applications deployed with LangServe" href="/docs/runtimes/langserve" />

  <Card title="Mastra" description="For workflow orchestration with Mastra's ecosystem" href="/docs/runtimes/mastra/overview" />
</Cards>

Understanding Runtime Architecture \[#understanding-runtime-architecture]

How Pre-Built Integrations Work \[#how-pre-built-integrations-work]

The pre-built integrations (AI SDK, LangGraph, etc.) are **not separate runtime types**. They're convenient wrappers built on top of our core runtimes:

* **AI SDK Integration** → Built on `LocalRuntime` with streaming adapter
* **LangGraph Runtime** → Built on `LocalRuntime` with graph execution adapter
* **LangServe Runtime** → Built on `LocalRuntime` with LangServe client adapter
* **Mastra Runtime** → Built on `LocalRuntime` with workflow adapter

This means you get all the benefits of `LocalRuntime` (automatic state management, built-in features) with zero configuration for your specific framework.

When to Use Pre-Built vs Core Runtimes \[#when-to-use-pre-built-vs-core-runtimes]

**Use a pre-built integration when:**

* You're already using that framework
* You want the fastest possible setup
* The integration covers your needs

**Use a core runtime when:**

* You have a custom backend
* You need features not exposed by the integration
* You want full control over the implementation

<Callout>
  Pre-built integrations can always be replaced with a custom `LocalRuntime` or `ExternalStoreRuntime` implementation if you need more control later.
</Callout>

Feature Comparison \[#feature-comparison]

Core Runtime Capabilities \[#core-runtime-capabilities]

| Feature              | `LocalRuntime` | `ExternalStoreRuntime`  |
| -------------------- | -------------- | ----------------------- |
| **State Management** | Automatic      | You control             |
| **Setup Complexity** | Simple         | Moderate                |
| **Message Editing**  | Built-in       | Implement `onEdit`      |
| **Branch Switching** | Built-in       | Implement `setMessages` |
| **Regeneration**     | Built-in       | Implement `onReload`    |
| **Cancellation**     | Built-in       | Implement `onCancel`    |
| **Multi-thread**     | Via adapters   | Via adapters            |

Available Adapters \[#available-adapters]

| Adapter     | `LocalRuntime` | `ExternalStoreRuntime` |
| ----------- | -------------- | ---------------------- |
| ChatModel   | ✅ Required     | ❌ N/A                  |
| Attachments | ✅              | ✅                      |
| Speech      | ✅              | ✅                      |
| Feedback    | ✅              | ✅                      |
| History     | ✅              | ❌ Use your state       |
| Suggestions | ✅              | ❌ Use your state       |

Common Implementation Patterns \[#common-implementation-patterns]

Vercel AI SDK with Streaming \[#vercel-ai-sdk-with-streaming]

```tsx
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

export function MyAssistant() {
  const runtime = useChatRuntime();

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
}
```

Custom Backend with LocalRuntime \[#custom-backend-with-localruntime]

```tsx
import { useLocalRuntime } from "@assistant-ui/react";

const runtime = useLocalRuntime({
  async run({ messages, abortSignal }) {
    const response = await fetch("/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ messages }),
      signal: abortSignal,
    });
    return response.json();
  },
});
```

Redux Integration with ExternalStoreRuntime \[#redux-integration-with-externalstoreruntime]

```tsx
import { useExternalStoreRuntime } from "@assistant-ui/react";

const messages = useSelector(selectMessages);
const dispatch = useDispatch();

const runtime = useExternalStoreRuntime({
  messages,
  onNew: async (message) => {
    dispatch(addUserMessage(message));
    const response = await api.chat(message);
    dispatch(addAssistantMessage(response));
  },
  setMessages: (messages) => dispatch(setMessages(messages)),
  onEdit: async (message) => dispatch(editMessage(message)),
  onReload: async (parentId) => dispatch(reloadMessage(parentId)),
});
```

Examples \[#examples]

Explore our implementation examples:

* **[AI SDK v6 Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6)** - Vercel AI SDK with `useChatRuntime`
* **[External Store Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-external-store)** - `ExternalStoreRuntime` with custom state
* **[Assistant Cloud Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud)** - Multi-thread with cloud persistence
* **[LangGraph Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)** - Agent workflows

Common Pitfalls to Avoid \[#common-pitfalls-to-avoid]

LocalRuntime Pitfalls \[#localruntime-pitfalls]

* **Forgetting the adapter**: `LocalRuntime` requires a `ChatModelAdapter` - it won't work without one
* **Not handling errors**: Always handle API errors in your adapter's `run` function
* **Missing abort signal**: Pass `abortSignal` to your fetch calls for proper cancellation

ExternalStoreRuntime Pitfalls \[#externalstoreruntime-pitfalls]

* **Mutating state**: Always create new arrays/objects when updating messages
* **Missing handlers**: Each UI feature requires its corresponding handler (e.g., no edit button without `onEdit`)
* **Forgetting optimistic updates**: Set `isRunning` to `true` for loading states

General Pitfalls \[#general-pitfalls]

* **Wrong integration level**: Don't use `LocalRuntime` if you already have Vercel AI SDK - use the AI SDK integration instead
* **Over-engineering**: Start with pre-built integrations before building custom solutions
* **Ignoring TypeScript**: The types will guide you to the correct implementation

Next Steps \[#next-steps]

1. **Choose your runtime** based on the decision tree above
2. **Follow the specific guide**:
   * [AI SDK Integration](/docs/runtimes/ai-sdk/use-chat)
   * [`LocalRuntime` Guide](/docs/runtimes/custom/local)
   * [`ExternalStoreRuntime` Guide](/docs/runtimes/custom/external-store)
   * [LangGraph Integration](/docs/runtimes/langgraph)
3. **Start with an example** from our [examples repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples)
4. **Add features progressively** using adapters
5. **Consider Assistant Cloud** for production persistence

<Callout type="info">
  Need help? Join our [Discord community](https://discord.gg/S9dwgCNEFs) or check the [GitHub](https://github.com/assistant-ui/assistant-ui).
</Callout>


# Adapters
URL: /docs/react-native/adapters

Storage and title generation adapters for React Native.

Adapters customize how the local runtime persists threads and generates titles. Pass them to `useLocalRuntime` via options.

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import {
  useLocalRuntime,
  createSimpleTitleAdapter,
} from "@assistant-ui/react-native";

const runtime = useLocalRuntime(chatModel, {
  storage: AsyncStorage,
  titleGenerator: createSimpleTitleAdapter(),
});
```

Storage \[#storage]

The `storage` option accepts any object with `getItem`, `setItem`, and `removeItem` methods (matching the `AsyncStorage` interface). When provided, threads and messages are persisted across app restarts.

```tsx
type AsyncStorageLike = {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
};
```

AsyncStorage \[#asyncstorage]

The most common choice for React Native:

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";

const runtime = useLocalRuntime(chatModel, {
  storage: AsyncStorage,
});
```

An optional `storagePrefix` parameter namespaces the keys:

```tsx
const runtime = useLocalRuntime(chatModel, {
  storage: AsyncStorage,
  storagePrefix: "chat:",
  // Keys: "chat:threads", "chat:messages:<threadId>", ...
});
```

No storage (default) \[#no-storage-default]

When `storage` is omitted, threads live in memory only — lost on app restart.

```tsx
const runtime = useLocalRuntime(chatModel);
```

Advanced: createLocalStorageAdapter \[#advanced-createlocalstorageadapter]

For more control, use `createLocalStorageAdapter` directly to create a `RemoteThreadListAdapter`:

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import {
  createLocalStorageAdapter,
  createSimpleTitleAdapter,
} from "@assistant-ui/react-native";

const adapter = createLocalStorageAdapter({
  storage: AsyncStorage,
  prefix: "chat:",
  titleGenerator: createSimpleTitleAdapter(),
});
```

TitleGenerationAdapter \[#titlegenerationadapter]

Generates a title for a thread based on its messages.

```tsx
interface TitleGenerationAdapter {
  generateTitle(messages: ThreadMessage[]): Promise<string>;
}
```

Built-in implementations \[#built-in-implementations]

Simple title adapter \[#simple-title-adapter]

Returns the first 50 characters of the first user message.

```tsx
import { createSimpleTitleAdapter } from "@assistant-ui/react-native";

const titleGenerator = createSimpleTitleAdapter();
```

Custom implementation \[#custom-implementation]

```tsx
import type { TitleGenerationAdapter } from "@assistant-ui/react-native";

const aiTitleGenerator: TitleGenerationAdapter = {
  async generateTitle(messages) {
    const response = await fetch("/api/generate-title", {
      method: "POST",
      body: JSON.stringify({ messages }),
    });
    const { title } = await response.json();
    return title;
  },
};
```


# Custom Backend
URL: /docs/react-native/custom-backend

Connect your React Native app to your own backend API.

By default, `useLocalRuntime` manages threads and messages on-device. You can connect to your own backend in two ways depending on your needs.

Option 1: ChatModelAdapter only \[#option-1-chatmodeladapter-only]

The simplest approach — keep thread management local, but send messages to your backend for inference.

```tsx title="adapters/my-chat-adapter.ts"
import type { ChatModelAdapter } from "@assistant-ui/react-native";

export const myChatAdapter: ChatModelAdapter = {
  async *run({ messages, abortSignal }) {
    const response = await fetch("https://my-api.com/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ messages }),
      signal: abortSignal,
    });

    const reader = response.body?.getReader();
    if (!reader) throw new Error("No response body");

    const decoder = new TextDecoder();
    let fullText = "";

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value, { stream: true });
      fullText += chunk;
      yield { content: [{ type: "text", text: fullText }] };
    }
  },
};
```

```tsx title="hooks/use-app-runtime.ts"
import AsyncStorage from "@react-native-async-storage/async-storage";
import { useLocalRuntime } from "@assistant-ui/react-native";
import { myChatAdapter } from "@/adapters/my-chat-adapter";

export function useAppRuntime() {
  return useLocalRuntime(myChatAdapter, {
    storage: AsyncStorage, // threads + messages persisted locally
  });
}
```

This gives you:

* Streaming chat responses from your API
* Local thread list with persistence (AsyncStorage)
* Message history saved across app restarts

Option 2: Full backend thread management \[#option-2-full-backend-thread-management]

When you want your backend to own thread state (e.g. for cross-device sync, team sharing, or server-side history), implement a `RemoteThreadListAdapter`.

<Steps>
  <Step>
    Implement the adapter \[#implement-the-adapter]

    ```tsx title="adapters/my-thread-list-adapter.ts"
    import type { RemoteThreadListAdapter } from "@assistant-ui/react-native";
    import { createAssistantStream } from "assistant-stream";

    const API_BASE = "https://my-api.com";

    export const myThreadListAdapter: RemoteThreadListAdapter = {
      async list() {
        const res = await fetch(`${API_BASE}/threads`);
        const threads = await res.json();
        return {
          threads: threads.map((t: any) => ({
            remoteId: t.id,
            status: t.archived ? "archived" : "regular",
            title: t.title,
          })),
        };
      },

      async initialize(localId) {
        const res = await fetch(`${API_BASE}/threads`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ localId }),
        });
        const { id } = await res.json();
        return { remoteId: id, externalId: undefined };
      },

      async rename(remoteId, title) {
        await fetch(`${API_BASE}/threads/${remoteId}`, {
          method: "PATCH",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ title }),
        });
      },

      async archive(remoteId) {
        await fetch(`${API_BASE}/threads/${remoteId}/archive`, {
          method: "POST",
        });
      },

      async unarchive(remoteId) {
        await fetch(`${API_BASE}/threads/${remoteId}/unarchive`, {
          method: "POST",
        });
      },

      async delete(remoteId) {
        await fetch(`${API_BASE}/threads/${remoteId}`, { method: "DELETE" });
      },

      async fetch(remoteId) {
        const res = await fetch(`${API_BASE}/threads/${remoteId}`);
        const t = await res.json();
        return {
          remoteId: t.id,
          status: t.archived ? "archived" : "regular",
          title: t.title,
        };
      },

      async generateTitle(remoteId, messages) {
        return createAssistantStream(async (controller) => {
          const res = await fetch(`${API_BASE}/threads/${remoteId}/title`, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ messages }),
          });
          const { title } = await res.json();
          controller.appendText(title);
        });
      },
    };
    ```
  </Step>

  <Step>
    Compose the runtime \[#compose-the-runtime]

    ```tsx title="hooks/use-app-runtime.ts"
    import {
      useLocalRuntime,
      useRemoteThreadListRuntime,
    } from "@assistant-ui/react-native";
    import { myChatAdapter } from "@/adapters/my-chat-adapter";
    import { myThreadListAdapter } from "@/adapters/my-thread-list-adapter";

    export function useAppRuntime() {
      return useRemoteThreadListRuntime({
        runtimeHook: () => useLocalRuntime(myChatAdapter),
        adapter: myThreadListAdapter,
      });
    }
    ```
  </Step>

  <Step>
    Use in your app \[#use-in-your-app]

    ```tsx title="app/index.tsx"
    import { AssistantProvider } from "@assistant-ui/react-native";
    import { useAppRuntime } from "@/hooks/use-app-runtime";

    export default function App() {
      const runtime = useAppRuntime();
      return (
        <AssistantProvider runtime={runtime}>
          {/* your chat UI */}
        </AssistantProvider>
      );
    }
    ```
  </Step>
</Steps>

Adapter methods \[#adapter-methods]

| Method                              | Description                                          |
| ----------------------------------- | ---------------------------------------------------- |
| `list()`                            | Return all threads on mount                          |
| `initialize(localId)`               | Create a thread server-side, return `{ remoteId }`   |
| `rename(remoteId, title)`           | Persist title changes                                |
| `archive(remoteId)`                 | Mark thread as archived                              |
| `unarchive(remoteId)`               | Restore archived thread                              |
| `delete(remoteId)`                  | Permanently remove thread                            |
| `fetch(remoteId)`                   | Fetch single thread metadata                         |
| `generateTitle(remoteId, messages)` | Return an `AssistantStream` with the generated title |

Which option to choose? \[#which-option-to-choose]

|                       | Option 1: ChatModelAdapter     | Option 2: RemoteThreadListAdapter                   |
| --------------------- | ------------------------------ | --------------------------------------------------- |
| **Thread storage**    | On-device (AsyncStorage)       | Your backend                                        |
| **Message storage**   | On-device (AsyncStorage)       | On-device (can add history adapter for server-side) |
| **Cross-device sync** | No                             | Yes                                                 |
| **Setup complexity**  | Minimal                        | Moderate                                            |
| **Best for**          | Single-device apps, prototypes | Production apps with user accounts                  |


# Hooks
URL: /docs/react-native/hooks

Reactive hooks for accessing runtime state in React Native.

All hooks support an optional **selector** function for fine-grained re-renders. Without a selector, the component re-renders on every state change. With a selector, it only re-renders when the selected value changes (shallow equality).

```tsx
// Re-renders on every thread state change
const thread = useThread();

// Re-renders only when isRunning changes
const isRunning = useThread((s) => s.isRunning);
```

State Hooks \[#state-hooks]

useThread \[#usethread]

Access thread state.

```tsx
import { useThread } from "@assistant-ui/react-native";

const messages = useThread((s) => s.messages);
const isRunning = useThread((s) => s.isRunning);
```

**ThreadState fields:**

| Field          | Type                  | Description                     |
| -------------- | --------------------- | ------------------------------- |
| `messages`     | `ThreadMessage[]`     | All messages in the thread      |
| `isRunning`    | `boolean`             | Whether the model is generating |
| `isDisabled`   | `boolean`             | Whether the thread is disabled  |
| `capabilities` | `RuntimeCapabilities` | What actions are supported      |

useComposer \[#usecomposer]

Access composer state.

```tsx
import { useComposer } from "@assistant-ui/react-native";

const text = useComposer((s) => s.text);
const isEmpty = useComposer((s) => s.isEmpty);
```

**ComposerState fields:**

| Field         | Type           | Description                    |
| ------------- | -------------- | ------------------------------ |
| `text`        | `string`       | Current input text             |
| `isEmpty`     | `boolean`      | Whether the input is empty     |
| `attachments` | `Attachment[]` | Current attachments            |
| `canCancel`   | `boolean`      | Whether a run can be cancelled |

useMessage \[#usemessage]

Access the current message state. Must be used inside a `MessageProvider` or a `renderMessage` / `renderItem` callback.

```tsx
import { useMessage } from "@assistant-ui/react-native";

const role = useMessage((s) => s.role);
const isLast = useMessage((s) => s.isLast);
```

**MessageState fields:**

| Field          | Type            | Description                            |
| -------------- | --------------- | -------------------------------------- |
| `message`      | `ThreadMessage` | The message object                     |
| `role`         | `MessageRole`   | `"user"`, `"assistant"`, or `"system"` |
| `isLast`       | `boolean`       | Whether this is the last message       |
| `branchNumber` | `number`        | Current branch index                   |
| `branchCount`  | `number`        | Total number of branches               |

useContentPart \[#usecontentpart]

Access a specific content part by index within a message.

```tsx
import { useContentPart } from "@assistant-ui/react-native";

const part = useContentPart(0); // first content part
```

useThreadList \[#usethreadlist]

Access the thread list state.

```tsx
import { useThreadList } from "@assistant-ui/react-native";

const { threadIds, mainThreadId, threadItems } = useThreadList();

// With selector
const mainThreadId = useThreadList((s) => s.mainThreadId);
```

**ThreadListState fields:**

| Field          | Type                                  | Description                   |
| -------------- | ------------------------------------- | ----------------------------- |
| `threadIds`    | `string[]`                            | All thread IDs                |
| `mainThreadId` | `string`                              | Currently active thread ID    |
| `threadItems`  | `Record<string, ThreadListItemState>` | Thread metadata (title, etc.) |

Runtime Hooks \[#runtime-hooks]

useAssistantRuntime \[#useassistantruntime]

Get the `AssistantRuntime` from context. This is the top-level runtime with access to thread management.

```tsx
import { useAssistantRuntime } from "@assistant-ui/react-native";

const runtime = useAssistantRuntime();

// Switch threads
runtime.threads.switchToThread(threadId);
runtime.threads.switchToNewThread();

// Thread management
runtime.threads.rename(threadId, "New Title");
runtime.threads.delete(threadId);

// Access the current thread runtime
runtime.thread; // ThreadRuntime
```

useThreadRuntime \[#usethreadruntime]

Get the `ThreadRuntime` for the current thread.

```tsx
import { useThreadRuntime } from "@assistant-ui/react-native";

const threadRuntime = useThreadRuntime();

threadRuntime.cancelRun();
threadRuntime.appendMessage(message);
```

useComposerRuntime \[#usecomposerruntime]

Get the `ComposerRuntime` for the current composer.

```tsx
import { useComposerRuntime } from "@assistant-ui/react-native";

const composerRuntime = useComposerRuntime();

composerRuntime.setText("Hello");
composerRuntime.send();
```

useMessageRuntime \[#usemessageruntime]

Get the `MessageRuntime` for the current message.

```tsx
import { useMessageRuntime } from "@assistant-ui/react-native";

const messageRuntime = useMessageRuntime();

messageRuntime.reload();
messageRuntime.switchToBranch({ position: "next" });
```

useLocalRuntime \[#uselocalruntime]

Create an `AssistantRuntime` with a `ChatModelAdapter`. Optionally pass `storage` for persistence.

```tsx
import { useLocalRuntime } from "@assistant-ui/react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";

const runtime = useLocalRuntime(chatModel, {
  storage: AsyncStorage,
  titleGenerator: createSimpleTitleAdapter(),
});
```

| Option            | Type                     | Description                                         |
| ----------------- | ------------------------ | --------------------------------------------------- |
| `initialMessages` | `ThreadMessageLike[]`    | Messages to pre-populate                            |
| `storage`         | `AsyncStorageLike`       | Thread and message persistence                      |
| `storagePrefix`   | `string`                 | Key prefix for storage (default `"@assistant-ui:"`) |
| `titleGenerator`  | `TitleGenerationAdapter` | Auto-generate thread titles                         |

Primitive Hooks \[#primitive-hooks]

Low-level hooks for building custom components.

useThreadMessages \[#usethreadmessages]

```tsx
import { useThreadMessages } from "@assistant-ui/react-native";

const messages = useThreadMessages(); // ThreadMessage[]
```

useThreadIsRunning \[#usethreadisrunning]

```tsx
import { useThreadIsRunning } from "@assistant-ui/react-native";

const isRunning = useThreadIsRunning(); // boolean
```

useThreadIsEmpty \[#usethreadisempty]

```tsx
import { useThreadIsEmpty } from "@assistant-ui/react-native";

const isEmpty = useThreadIsEmpty(); // boolean
```

useComposerSend \[#usecomposersend]

```tsx
import { useComposerSend } from "@assistant-ui/react-native";

const { send, canSend } = useComposerSend();
```

useComposerCancel \[#usecomposercancel]

```tsx
import { useComposerCancel } from "@assistant-ui/react-native";

const { cancel, canCancel } = useComposerCancel();
```

useComposerAddAttachment \[#usecomposeraddattachment]

Add an attachment to the composer. Returns `{ addAttachment }` — call it with a `File` or `CreateAttachment` object. Pair with your own file picker (e.g. `expo-image-picker`).

```tsx
import { useComposerAddAttachment } from "@assistant-ui/react-native";

const { addAttachment } = useComposerAddAttachment();

// With expo-image-picker
const pickImage = async () => {
  const result = await ImagePicker.launchImageLibraryAsync({
    base64: true,
    quality: 0.8,
  });
  if (result.canceled) return;

  for (const asset of result.assets) {
    await addAttachment({
      name: asset.fileName ?? "image.jpg",
      type: "image",
      content: [
        { type: "image", image: `data:image/jpeg;base64,${asset.base64}` },
      ],
    });
  }
};
```

<Callout type="info">
  You must configure an `AttachmentAdapter` (e.g. `SimpleImageAttachmentAdapter`) in your runtime options for attachments to work.
</Callout>

useMessageReload \[#usemessagereload]

```tsx
import { useMessageReload } from "@assistant-ui/react-native";

const { reload, canReload } = useMessageReload();
```

useMessageBranching \[#usemessagebranching]

```tsx
import { useMessageBranching } from "@assistant-ui/react-native";

const { branchNumber, branchCount, goToPrev, goToNext } =
  useMessageBranching();
```

Model Context Hooks \[#model-context-hooks]

useAssistantTool \[#useassistanttool]

Register a tool with an optional UI renderer. The tool definition is forwarded to the model, and when the model calls it, the `execute` function runs and the `render` component displays the result.

```tsx
import { useAssistantTool } from "@assistant-ui/react-native";

useAssistantTool({
  toolName: "get_weather",
  description: "Get the current weather for a city",
  parameters: {
    type: "object",
    properties: {
      city: { type: "string" },
    },
    required: ["city"],
  },
  execute: async ({ city }) => {
    const res = await fetch(`https://api.weather.example/${city}`);
    return res.json();
  },
  render: ({ args, result }) => (
    <View>
      <Text>{args.city}: {result?.temperature}°F</Text>
    </View>
  ),
});
```

useAssistantToolUI \[#useassistanttoolui]

Register only a UI renderer for a tool (without tool definition or execute function).

```tsx
import { useAssistantToolUI } from "@assistant-ui/react-native";

useAssistantToolUI({
  toolName: "get_weather",
  render: ({ args, result, status }) => (
    <View>
      {status?.type === "running"
        ? <Text>Loading weather for {args.city}...</Text>
        : <Text>{args.city}: {result?.temperature}°F</Text>}
    </View>
  ),
});
```

useAssistantInstructions \[#useassistantinstructions]

Register system instructions in the model context.

```tsx
import { useAssistantInstructions } from "@assistant-ui/react-native";

useAssistantInstructions("You are a helpful weather assistant.");
```

makeAssistantTool \[#makeassistanttool]

Create a component that registers a tool when mounted. Useful for declarative tool registration.

```tsx
import { makeAssistantTool } from "@assistant-ui/react-native";

const WeatherTool = makeAssistantTool({
  toolName: "get_weather",
  description: "Get weather",
  parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
  execute: async ({ city }) => ({ temperature: 72 }),
  render: ({ args, result }) => <Text>{args.city}: {result?.temperature}°F</Text>,
});

// Mount inside AssistantProvider to register
<WeatherTool />
```


# Getting Started
URL: /docs/react-native

Build AI chat interfaces for iOS and Android with @assistant-ui/react-native.

Overview \[#overview]

`@assistant-ui/react-native` brings assistant-ui to React Native. It provides composable primitives, reactive hooks, and a local runtime — the same layered architecture as the web package, built on native components (`View`, `TextInput`, `FlatList`, `Pressable`).

**Key features:**

* **Primitives** — `Thread`, `Composer`, `Message`, `ThreadList`, `ThreadListItem`, `ChainOfThought`, `Suggestion`, `ActionBar`, `BranchPicker`, `Attachment` components that compose with standard React Native props
* **Reactive state** — `useAuiState` with selector support for fine-grained re-renders
* **Local runtime** — `useLocalRuntime` with pluggable `ChatModelAdapter` for any LLM API
* **Thread management** — Multi-thread support with create, switch, rename, delete
* **Tool system** — `useAssistantTool`, `makeAssistantTool` for registering tools with custom UI renderers
* **Attachments** — Image and file attachments with `useComposerAddAttachment` and attachment primitives

<Callout type="info">
  `@assistant-ui/react-native` shares its runtime core with `@assistant-ui/react` via `@assistant-ui/core`. The type system, state management, and runtime logic are identical — only the UI layer differs.
</Callout>

Getting Started \[#getting-started]

This guide uses [Expo](https://expo.dev) with the OpenAI API. You can substitute any LLM provider.

<Steps>
  <Step>
    Create an Expo project \[#create-an-expo-project]

    ```sh
    npx create-expo-app@latest my-chat-app
    cd my-chat-app
    ```
  </Step>

  <Step>
    Install dependencies \[#install-dependencies]

    ```sh
    npx expo install @assistant-ui/react-native
    ```
  </Step>

  <Step>
    Create a ChatModelAdapter \[#create-a-chatmodeladapter]

    The adapter connects your LLM API to the runtime. Here's an example for the OpenAI chat completions API with streaming:

    ```tsx title="adapters/openai-chat-adapter.ts"
    import type {
      ChatModelAdapter,
      ChatModelRunResult,
    } from "@assistant-ui/react-native";

    type OpenAIModelConfig = {
      apiKey: string;
      model?: string;
      baseURL?: string;
      fetch?: typeof globalThis.fetch;
    };

    export function createOpenAIChatModelAdapter(
      config: OpenAIModelConfig,
    ): ChatModelAdapter {
      const {
        apiKey,
        model = "gpt-4o-mini",
        baseURL = "https://api.openai.com/v1",
        fetch: customFetch = globalThis.fetch,
      } = config;

      return {
        async *run({ messages, abortSignal }) {
          const openAIMessages = messages
            .filter((m) => m.role !== "system")
            .map((m) => ({
              role: m.role as "user" | "assistant",
              content: m.content
                .filter((p) => p.type === "text")
                .map((p) => ("text" in p ? p.text : ""))
                .join("\n"),
            }));

          const response = await customFetch(
            `${baseURL}/chat/completions`,
            {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                Authorization: `Bearer ${apiKey}`,
              },
              body: JSON.stringify({
                model,
                messages: openAIMessages,
                stream: true,
              }),
              signal: abortSignal,
            },
          );

          if (!response.ok) {
            const body = await response.text().catch(() => "");
            throw new Error(
              `OpenAI API error: ${response.status} ${body}`,
            );
          }

          const reader = response.body?.getReader();
          if (!reader) {
            const json = await response.json();
            const text = json.choices?.[0]?.message?.content ?? "";
            yield {
              content: [{ type: "text" as const, text }],
            } satisfies ChatModelRunResult;
            return;
          }

          const decoder = new TextDecoder();
          let fullText = "";

          try {
            while (true) {
              const { done, value } = await reader.read();
              if (done) break;
              const chunk = decoder.decode(value, { stream: true });
              for (const line of chunk.split("\n")) {
                if (!line.startsWith("data: ")) continue;
                const data = line.slice(6);
                if (data === "[DONE]") continue;
                try {
                  const parsed = JSON.parse(data);
                  const content =
                    parsed.choices?.[0]?.delta?.content ?? "";
                  fullText += content;
                  yield {
                    content: [
                      { type: "text" as const, text: fullText },
                    ],
                  } satisfies ChatModelRunResult;
                } catch {
                  // skip invalid JSON
                }
              }
            }
          } finally {
            reader.releaseLock();
          }
        },
      };
    }
    ```

    <Callout type="tip">
      On Expo, import `fetch` from `expo/fetch` for streaming support and pass it as the `fetch` option.
    </Callout>
  </Step>

  <Step>
    Set up the runtime \[#set-up-the-runtime]

    ```tsx title="hooks/use-app-runtime.ts"
    import { useMemo } from "react";
    import { fetch } from "expo/fetch";
    import { useLocalRuntime } from "@assistant-ui/react-native";
    import { createOpenAIChatModelAdapter } from "@/adapters/openai-chat-adapter";

    export function useAppRuntime() {
      const chatModel = useMemo(
        () =>
          createOpenAIChatModelAdapter({
            apiKey: process.env.EXPO_PUBLIC_OPENAI_API_KEY ?? "",
            model: "gpt-4o-mini",
            fetch,
          }),
        [],
      );

      return useLocalRuntime(chatModel);
    }
    ```
  </Step>

  <Step>
    Build the UI \[#build-the-ui]

    Wrap your app with `AssistantProvider` — thread and composer contexts are set up automatically:

    ```tsx title="app/index.tsx"
    import {
      AssistantProvider,
      useAuiState,
      useAui,
    } from "@assistant-ui/react-native";
    import type { ThreadMessage } from "@assistant-ui/react-native";
    import {
      View,
      Text,
      TextInput,
      FlatList,
      Pressable,
      KeyboardAvoidingView,
      Platform,
    } from "react-native";
    import { useAppRuntime } from "@/hooks/use-app-runtime";

    function MessageBubble({ message }: { message: ThreadMessage }) {
      const isUser = message.role === "user";
      const text = message.content
        .filter((p) => p.type === "text")
        .map((p) => ("text" in p ? p.text : ""))
        .join("\n");

      return (
        <View
          style={{
            alignSelf: isUser ? "flex-end" : "flex-start",
            backgroundColor: isUser ? "#007aff" : "#f0f0f0",
            borderRadius: 16,
            padding: 12,
            marginVertical: 4,
            marginHorizontal: 16,
            maxWidth: "80%",
          }}
        >
          <Text style={{ color: isUser ? "#fff" : "#000" }}>{text}</Text>
        </View>
      );
    }

    function Composer() {
      const aui = useAui();
      const text = useAuiState((s) => s.composer.text);
      const isEmpty = useAuiState((s) => s.composer.isEmpty);

      return (
        <View
          style={{
            flexDirection: "row",
            padding: 12,
            alignItems: "flex-end",
          }}
        >
          <TextInput
            value={text}
            onChangeText={(t) => aui.composer().setText(t)}
            placeholder="Message..."
            multiline
            style={{
              flex: 1,
              borderWidth: 1,
              borderColor: "#ddd",
              borderRadius: 20,
              paddingHorizontal: 16,
              paddingVertical: 10,
              maxHeight: 120,
            }}
          />
          <Pressable
            onPress={() => aui.composer().send()}
            disabled={isEmpty}
            style={{
              marginLeft: 8,
              backgroundColor: !isEmpty ? "#007aff" : "#ccc",
              borderRadius: 20,
              width: 36,
              height: 36,
              justifyContent: "center",
              alignItems: "center",
            }}
          >
            <Text style={{ color: "#fff", fontWeight: "bold" }}>↑</Text>
          </Pressable>
        </View>
      );
    }

    function ChatScreen() {
      const messages = useAuiState(
        (s) => s.thread.messages,
      ) as ThreadMessage[];

      return (
        <KeyboardAvoidingView
          style={{ flex: 1 }}
          behavior={Platform.OS === "ios" ? "padding" : "height"}
        >
          <FlatList
            data={messages}
            keyExtractor={(m) => m.id}
            renderItem={({ item }) => <MessageBubble message={item} />}
          />
          <Composer />
        </KeyboardAvoidingView>
      );
    }

    export default function App() {
      const runtime = useAppRuntime();

      return (
        <AssistantProvider runtime={runtime}>
          <ChatScreen />
        </AssistantProvider>
      );
    }
    ```
  </Step>
</Steps>

Architecture \[#architecture]

```
useLocalRuntime(chatModel, options?)
  └─ AssistantProvider
       ├─ useAuiState((s) => s.thread)    → thread state (messages, isRunning, …)
       ├─ useAuiState((s) => s.composer)   → composer state (text, isEmpty, …)
       ├─ useAuiState((s) => s.message)    → single message state (inside renderItem)
       └─ Primitives                       → ThreadRoot, ComposerInput, MessageContent, …
```

The runtime core is shared with `@assistant-ui/react` — only the UI primitives are React Native-specific.

Example \[#example]

For a complete Expo example with drawer navigation, thread list, and styled chat UI, see the [`with-expo` example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-expo).


# Primitives
URL: /docs/react-native/primitives

Composable React Native components for building chat UIs.

Primitives are thin wrappers around React Native components (`View`, `TextInput`, `FlatList`, `Pressable`) that integrate with the assistant-ui runtime. They accept all standard React Native props and add runtime-aware behavior.

Many primitives share their core logic with `@assistant-ui/react` via `@assistant-ui/core/react` — only the UI layer (View/Pressable/Text vs DOM elements) differs.

Thread \[#thread]

ThreadRoot \[#threadroot]

Container `View` for the thread area.

```tsx
import { ThreadRoot } from "@assistant-ui/react-native";

<ThreadRoot style={{ flex: 1 }}>
  {children}
</ThreadRoot>
```

| Prop      | Type        | Description                      |
| --------- | ----------- | -------------------------------- |
| `...rest` | `ViewProps` | Standard React Native View props |

ThreadMessages \[#threadmessages]

`FlatList`-based message list with automatic runtime integration. Each message is wrapped in a scoped context so that `useAuiState((s) => s.message)` works inside `renderMessage`.

```tsx
import { ThreadMessages } from "@assistant-ui/react-native";

<ThreadMessages
  renderMessage={({ message }) => <MessageBubble message={message} />}
/>
```

| Prop            | Type                                                                | Description                                           |
| --------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
| `renderMessage` | `(info: { message: ThreadMessage; index: number }) => ReactElement` | Message renderer                                      |
| `...rest`       | `FlatListProps`                                                     | Standard FlatList props (except `data`, `renderItem`) |

ThreadEmpty \[#threadempty]

Renders children only when the thread has no messages.

```tsx
import { ThreadEmpty } from "@assistant-ui/react-native";

<ThreadEmpty>
  <Text>Send a message to get started</Text>
</ThreadEmpty>
```

ThreadIf \[#threadif]

Conditional rendering based on thread state.

```tsx
import { ThreadIf } from "@assistant-ui/react-native";

<ThreadIf empty>
  <Text>No messages yet</Text>
</ThreadIf>

<ThreadIf running>
  <ActivityIndicator />
</ThreadIf>
```

| Prop      | Type      | Description                   |
| --------- | --------- | ----------------------------- |
| `empty`   | `boolean` | Render when thread is empty   |
| `running` | `boolean` | Render when thread is running |

Composer \[#composer]

ComposerRoot \[#composerroot]

Container `View` for the composer area.

```tsx
import { ComposerRoot } from "@assistant-ui/react-native";

<ComposerRoot style={styles.composerContainer}>
  {children}
</ComposerRoot>
```

ComposerInput \[#composerinput]

`TextInput` wired to the composer runtime. Value and `onChangeText` are managed automatically.

```tsx
import { ComposerInput } from "@assistant-ui/react-native";

<ComposerInput
  placeholder="Message..."
  multiline
  style={styles.input}
/>
```

| Prop      | Type             | Description                                               |
| --------- | ---------------- | --------------------------------------------------------- |
| `...rest` | `TextInputProps` | Standard TextInput props (except `value`, `onChangeText`) |

ComposerSend \[#composersend]

`Pressable` that sends the current message. Automatically disabled when the composer is empty.

```tsx
import { ComposerSend } from "@assistant-ui/react-native";

<ComposerSend style={styles.sendButton}>
  <Text>Send</Text>
</ComposerSend>
```

ComposerCancel \[#composercancel]

`Pressable` that cancels the current run. Automatically disabled when no run is active.

```tsx
import { ComposerCancel } from "@assistant-ui/react-native";

<ComposerCancel style={styles.cancelButton}>
  <Text>Stop</Text>
</ComposerCancel>
```

ComposerAttachments \[#composerattachments]

Renders composer attachments using the provided component configuration.

```tsx
import { ComposerAttachments } from "@assistant-ui/react-native";

<ComposerAttachments
  components={{
    Image: MyImageAttachment,
    Document: MyDocumentAttachment,
    Attachment: MyFallbackAttachment, // fallback for all types
  }}
/>
```

| Prop         | Type                                        | Description                            |
| ------------ | ------------------------------------------- | -------------------------------------- |
| `components` | `{ Image?, Document?, File?, Attachment? }` | Component renderers by attachment type |

Message \[#message]

MessageRoot \[#messageroot]

Container `View` for a single message.

```tsx
import { MessageRoot } from "@assistant-ui/react-native";

<MessageRoot style={styles.messageBubble}>
  {children}
</MessageRoot>
```

MessageContent \[#messagecontent]

Renders message content parts. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to render props if provided.

```tsx
import { MessageContent } from "@assistant-ui/react-native";

<MessageContent
  renderText={({ part }) => <Text>{part.text}</Text>}
  renderImage={({ part }) => <Image source={{ uri: part.image }} />}
/>
```

| Prop              | Type                                       | Description                                             |
| ----------------- | ------------------------------------------ | ------------------------------------------------------- |
| `renderText`      | `(props: { part; index }) => ReactElement` | Text part renderer                                      |
| `renderToolCall`  | `(props: { part; index }) => ReactElement` | Tool call fallback (used when no tool UI is registered) |
| `renderImage`     | `(props: { part; index }) => ReactElement` | Image part renderer                                     |
| `renderReasoning` | `(props: { part; index }) => ReactElement` | Reasoning part renderer                                 |
| `renderSource`    | `(props: { part; index }) => ReactElement` | Source part renderer                                    |
| `renderFile`      | `(props: { part; index }) => ReactElement` | File part renderer                                      |
| `renderData`      | `(props: { part; index }) => ReactElement` | Data part fallback (used when no data UI is registered) |

MessageIf \[#messageif]

Conditional rendering based on message properties.

```tsx
import { MessageIf } from "@assistant-ui/react-native";

<MessageIf user>
  <Text>You said:</Text>
</MessageIf>

<MessageIf assistant last>
  <ActivityIndicator />
</MessageIf>
```

| Prop        | Type      | Description                            |
| ----------- | --------- | -------------------------------------- |
| `user`      | `boolean` | Render for user messages               |
| `assistant` | `boolean` | Render for assistant messages          |
| `running`   | `boolean` | Render when message is being generated |
| `last`      | `boolean` | Render for the last message            |

MessageAttachments \[#messageattachments]

Renders user message attachments using the provided component configuration.

```tsx
import { MessageAttachments } from "@assistant-ui/react-native";

<MessageAttachments
  components={{
    Image: MyImageAttachment,
    Attachment: MyFallbackAttachment,
  }}
/>
```

| Prop         | Type                                        | Description                            |
| ------------ | ------------------------------------------- | -------------------------------------- |
| `components` | `{ Image?, Document?, File?, Attachment? }` | Component renderers by attachment type |

Attachment \[#attachment]

Primitives for rendering individual attachments (inside `ComposerAttachments` or `MessageAttachments`).

AttachmentRoot \[#attachmentroot]

Container `View` for an attachment.

```tsx
import { AttachmentRoot } from "@assistant-ui/react-native";

<AttachmentRoot style={styles.attachment}>
  {children}
</AttachmentRoot>
```

AttachmentName \[#attachmentname]

`Text` component displaying the attachment filename.

```tsx
import { AttachmentName } from "@assistant-ui/react-native";

<AttachmentName style={styles.filename} />
```

AttachmentThumb \[#attachmentthumb]

`Text` component displaying the file extension (e.g. `.pdf`).

```tsx
import { AttachmentThumb } from "@assistant-ui/react-native";

<AttachmentThumb style={styles.extension} />
```

AttachmentRemove \[#attachmentremove]

`Pressable` that removes the attachment from the composer.

```tsx
import { AttachmentRemove } from "@assistant-ui/react-native";

<AttachmentRemove>
  <Text>Remove</Text>
</AttachmentRemove>
```

ActionBar \[#actionbar]

ActionBarCopy \[#actionbarcopy]

`Pressable` that copies the message content. Supports function-as-children for copy state feedback.

```tsx
import { ActionBarCopy } from "@assistant-ui/react-native";

<ActionBarCopy copiedDuration={3000}>
  {({ isCopied }) => <Text>{isCopied ? "Copied!" : "Copy"}</Text>}
</ActionBarCopy>
```

| Prop              | Type                     | Description                                           |
| ----------------- | ------------------------ | ----------------------------------------------------- |
| `copiedDuration`  | `number`                 | Duration in ms to show "copied" state (default: 3000) |
| `copyToClipboard` | `(text: string) => void` | Custom clipboard function                             |

ActionBarEdit \[#actionbaredit]

`Pressable` that enters edit mode for a message.

```tsx
import { ActionBarEdit } from "@assistant-ui/react-native";

<ActionBarEdit>
  <Text>Edit</Text>
</ActionBarEdit>
```

ActionBarReload \[#actionbarreload]

`Pressable` that regenerates an assistant message.

```tsx
import { ActionBarReload } from "@assistant-ui/react-native";

<ActionBarReload>
  <Text>Retry</Text>
</ActionBarReload>
```

ActionBarFeedbackPositive / ActionBarFeedbackNegative \[#actionbarfeedbackpositive--actionbarfeedbacknegative]

`Pressable` buttons for submitting message feedback.

```tsx
import {
  ActionBarFeedbackPositive,
  ActionBarFeedbackNegative,
} from "@assistant-ui/react-native";

<ActionBarFeedbackPositive>
  {({ isSubmitted }) => <Text>{isSubmitted ? "👍" : "👍🏻"}</Text>}
</ActionBarFeedbackPositive>

<ActionBarFeedbackNegative>
  {({ isSubmitted }) => <Text>{isSubmitted ? "👎" : "👎🏻"}</Text>}
</ActionBarFeedbackNegative>
```

BranchPicker \[#branchpicker]

BranchPickerPrevious / BranchPickerNext \[#branchpickerprevious--branchpickernext]

`Pressable` buttons to navigate between message branches.

```tsx
import {
  BranchPickerPrevious,
  BranchPickerNext,
  BranchPickerNumber,
  BranchPickerCount,
} from "@assistant-ui/react-native";

<View style={{ flexDirection: "row", alignItems: "center" }}>
  <BranchPickerPrevious>
    <Text>←</Text>
  </BranchPickerPrevious>
  <BranchPickerNumber />
  <Text>/</Text>
  <BranchPickerCount />
  <BranchPickerNext>
    <Text>→</Text>
  </BranchPickerNext>
</View>
```

BranchPickerNumber / BranchPickerCount \[#branchpickernumber--branchpickercount]

`Text` components displaying the current branch number and total count.

ThreadList \[#threadlist]

ThreadListRoot \[#threadlistroot]

Container `View` for the thread list.

```tsx
import { ThreadListRoot } from "@assistant-ui/react-native";

<ThreadListRoot style={styles.threadList}>
  {children}
</ThreadListRoot>
```

ThreadListItems \[#threadlistitems]

`FlatList` of thread IDs with runtime integration.

```tsx
import { ThreadListItems } from "@assistant-ui/react-native";

<ThreadListItems
  renderItem={({ threadId }) => (
    <ThreadListEntry threadId={threadId} />
  )}
/>
```

| Prop         | Type                                                           | Description                                           |
| ------------ | -------------------------------------------------------------- | ----------------------------------------------------- |
| `renderItem` | `(props: { threadId: string; index: number }) => ReactElement` | Thread item renderer                                  |
| `...rest`    | `FlatListProps`                                                | Standard FlatList props (except `data`, `renderItem`) |

ThreadListNew \[#threadlistnew]

`Pressable` that creates a new thread.

```tsx
import { ThreadListNew } from "@assistant-ui/react-native";

<ThreadListNew style={styles.newThreadButton}>
  <Text>New Chat</Text>
</ThreadListNew>
```

ThreadListItem \[#threadlistitem]

Primitives for rendering individual thread list items. Use inside a `ThreadListItemByIndexProvider` or within `ThreadListPrimitiveItems` components.

ThreadListItemRoot \[#threadlistitemroot]

Container `View` for a thread list item.

```tsx
import { ThreadListItemRoot } from "@assistant-ui/react-native";

<ThreadListItemRoot style={styles.threadItem}>
  {children}
</ThreadListItemRoot>
```

ThreadListItemTitle \[#threadlistitemtitle]

Renders the thread title text. Falls back to the provided fallback when title is empty. This component is shared from `@assistant-ui/core/react`.

```tsx
import { ThreadListItemTitle } from "@assistant-ui/react-native";

<ThreadListItemTitle fallback="New Chat" />
```

| Prop       | Type        | Description                         |
| ---------- | ----------- | ----------------------------------- |
| `fallback` | `ReactNode` | Content to show when title is empty |

ThreadListItemTrigger \[#threadlistitemtrigger]

`Pressable` that switches to the thread.

```tsx
import { ThreadListItemTrigger } from "@assistant-ui/react-native";

<ThreadListItemTrigger>
  <ThreadListItemTitle fallback="New Chat" />
</ThreadListItemTrigger>
```

ThreadListItemDelete \[#threadlistitemdelete]

`Pressable` that deletes the thread.

```tsx
import { ThreadListItemDelete } from "@assistant-ui/react-native";

<ThreadListItemDelete>
  <Text>Delete</Text>
</ThreadListItemDelete>
```

ThreadListItemArchive / ThreadListItemUnarchive \[#threadlistitemarchive--threadlistitemunarchive]

`Pressable` buttons that archive or unarchive the thread.

```tsx
import {
  ThreadListItemArchive,
  ThreadListItemUnarchive,
} from "@assistant-ui/react-native";

<ThreadListItemArchive>
  <Text>Archive</Text>
</ThreadListItemArchive>

<ThreadListItemUnarchive>
  <Text>Unarchive</Text>
</ThreadListItemUnarchive>
```

Suggestion \[#suggestion]

Primitives for rendering suggestions. Use inside a `SuggestionByIndexProvider` (from `@assistant-ui/core/react`).

SuggestionTitle \[#suggestiontitle]

`Text` component displaying the suggestion title.

```tsx
import { SuggestionTitle } from "@assistant-ui/react-native";

<SuggestionTitle style={styles.suggestionTitle} />
```

SuggestionDescription \[#suggestiondescription]

`Text` component displaying the suggestion description/label.

```tsx
import { SuggestionDescription } from "@assistant-ui/react-native";

<SuggestionDescription style={styles.suggestionDescription} />
```

SuggestionTrigger \[#suggestiontrigger]

`Pressable` that triggers the suggestion action (send or insert into composer).

```tsx
import { SuggestionTrigger } from "@assistant-ui/react-native";

<SuggestionTrigger send>
  <SuggestionTitle />
</SuggestionTrigger>
```

| Prop            | Type      | Description                                                     |
| --------------- | --------- | --------------------------------------------------------------- |
| `send`          | `boolean` | When true, sends immediately; when false, inserts into composer |
| `clearComposer` | `boolean` | Whether to clear/replace composer text (default: true)          |

ThreadSuggestion \[#threadsuggestion]

Inline `Pressable` that triggers a suggestion with a specified prompt. Use this when you want to hardcode suggestion text.

```tsx
import { ThreadSuggestion } from "@assistant-ui/react-native";

<ThreadSuggestion prompt="Tell me a joke" send>
  <Text>Tell me a joke</Text>
</ThreadSuggestion>
```

| Prop            | Type      | Description                                            |
| --------------- | --------- | ------------------------------------------------------ |
| `prompt`        | `string`  | The suggestion text                                    |
| `send`          | `boolean` | When true, sends immediately                           |
| `clearComposer` | `boolean` | Whether to clear/replace composer text (default: true) |

ThreadPrimitiveSuggestions \[#threadprimitivesuggestions]

Renders all suggestions from the store. Shared from `@assistant-ui/core/react`.

```tsx
import { ThreadPrimitiveSuggestions } from "@assistant-ui/react-native";

<ThreadPrimitiveSuggestions
  components={{ Suggestion: MySuggestionComponent }}
/>
```

ChainOfThought \[#chainofthought]

Primitives for rendering chain of thought content (grouped reasoning and tool-call parts).

ChainOfThoughtRoot \[#chainofthoughtroot]

Container `View` for chain of thought content.

```tsx
import { ChainOfThoughtRoot } from "@assistant-ui/react-native";

<ChainOfThoughtRoot style={styles.chainOfThought}>
  {children}
</ChainOfThoughtRoot>
```

ChainOfThoughtAccordionTrigger \[#chainofthoughtaccordiontrigger]

`Pressable` that toggles the collapsed state of the chain of thought.

```tsx
import { ChainOfThoughtAccordionTrigger } from "@assistant-ui/react-native";

<ChainOfThoughtAccordionTrigger>
  <Text>Toggle reasoning</Text>
</ChainOfThoughtAccordionTrigger>
```

ChainOfThoughtPrimitiveParts \[#chainofthoughtprimitiveparts]

Renders the parts within a chain of thought. Shared from `@assistant-ui/core/react`.

```tsx
import { ChainOfThoughtPrimitiveParts } from "@assistant-ui/react-native";

<ChainOfThoughtPrimitiveParts
  components={{
    Reasoning: ({ text }) => <Text>{text}</Text>,
    tools: { Fallback: MyToolComponent },
  }}
/>
```

Additional Composer Primitives \[#additional-composer-primitives]

ComposerAddAttachment \[#composeraddattachment]

`Pressable` for triggering attachment addition. The actual file picker must be implemented by the consumer (e.g. using `expo-document-picker` or `expo-image-picker`).

```tsx
import { ComposerAddAttachment } from "@assistant-ui/react-native";

<ComposerAddAttachment onPress={handlePickFile}>
  <Text>📎</Text>
</ComposerAddAttachment>
```

ComposerIf \[#composerif]

Conditional rendering based on composer state. Shared from `@assistant-ui/core/react`.

```tsx
import { ComposerIf } from "@assistant-ui/react-native";

<ComposerIf editing>
  <Text>Currently editing</Text>
</ComposerIf>
```

| Prop        | Type      | Description                             |
| ----------- | --------- | --------------------------------------- |
| `editing`   | `boolean` | Render when composer is in editing mode |
| `dictation` | `boolean` | Render when dictation is active         |

Shared Primitives from core/react \[#shared-primitives-from-corereact]

The following primitives are shared with `@assistant-ui/react` via `@assistant-ui/core/react` and work identically on both platforms:

* **`ThreadPrimitiveMessages`** / **`ThreadPrimitiveMessageByIndex`** — Component-composition pattern for rendering messages (alternative to the FlatList-based `ThreadMessages`)
* **`MessagePrimitiveParts`** / **`MessagePrimitivePartByIndex`** — Renders message parts with grouping, ChainOfThought, and Empty support (alternative to the render-props-based `MessageContent`). Uses `<Text>` as default text renderer on RN.
* **`ThreadPrimitiveSuggestions`** / **`ThreadPrimitiveSuggestionByIndex`** — Renders suggestions from the store
* **`ThreadListPrimitiveItems`** / **`ThreadListPrimitiveItemByIndex`** — Component-composition pattern for thread list items (alternative to the FlatList-based `ThreadListItems`)
* **`ChainOfThoughtPrimitiveParts`** — Renders chain of thought parts

```tsx
import {
  ThreadPrimitiveMessages,
  MessagePrimitiveParts,
  ThreadPrimitiveSuggestions,
} from "@assistant-ui/react-native";
```


# Accordion
URL: /docs/ui/accordion

A vertically stacked set of interactive headings that reveal or hide content sections.

import { PreviewCode } from "@/components/docs/preview-code.server";
import {
  AccordionSample,
  AccordionVariantsSample,
  AccordionMultipleSample,
  AccordionWithIconsSample,
  AccordionControlledSample,
  AccordionFAQSample,
} from "@/components/docs/samples/accordion";

<Callout>
  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
</Callout>

<AccordionSample />

Installation \[#installation]

<InstallCommand shadcn={["accordion"]} />

Usage \[#usage]

```tsx
import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from "@/components/assistant-ui/accordion";

export function Example() {
  return (
    <Accordion type="single" collapsible>
      <AccordionItem value="item-1">
        <AccordionTrigger>Section 1</AccordionTrigger>
        <AccordionContent>Content for section 1.</AccordionContent>
      </AccordionItem>
      <AccordionItem value="item-2">
        <AccordionTrigger>Section 2</AccordionTrigger>
        <AccordionContent>Content for section 2.</AccordionContent>
      </AccordionItem>
    </Accordion>
  );
}
```

Examples \[#examples]

Variants \[#variants]

Use the `variant` prop on `Accordion` to change the visual style. Child components inherit the variant automatically.

<AccordionVariantsSample />

```tsx
// Default - border-bottom separator
<Accordion type="single" collapsible variant="default">
  <AccordionItem value="item-1">
    <AccordionTrigger>...</AccordionTrigger>
    <AccordionContent>...</AccordionContent>
  </AccordionItem>
</Accordion>

// Outline - bordered container
<Accordion type="single" collapsible variant="outline">
  <AccordionItem value="item-1">
    <AccordionTrigger>...</AccordionTrigger>
    <AccordionContent>...</AccordionContent>
  </AccordionItem>
</Accordion>

// Ghost - separated cards
<Accordion type="single" collapsible variant="ghost">
  <AccordionItem value="item-1">
    <AccordionTrigger>...</AccordionTrigger>
    <AccordionContent>...</AccordionContent>
  </AccordionItem>
</Accordion>
```

Multiple Items Open \[#multiple-items-open]

Use `type="multiple"` to allow multiple items to be open simultaneously.

<AccordionMultipleSample />

```tsx
<Accordion type="multiple">
  <AccordionItem value="item-1">
    <AccordionTrigger>First Section</AccordionTrigger>
    <AccordionContent>Content 1</AccordionContent>
  </AccordionItem>
  <AccordionItem value="item-2">
    <AccordionTrigger>Second Section</AccordionTrigger>
    <AccordionContent>Content 2</AccordionContent>
  </AccordionItem>
</Accordion>
```

With Icons \[#with-icons]

Add icons or custom elements inside the trigger.

<PreviewCode file="components/docs/samples/accordion" name="AccordionWithIconsSample">
  <AccordionWithIconsSample />
</PreviewCode>

Controlled \[#controlled]

Use `value` and `onValueChange` for controlled accordion state.

<PreviewCode file="components/docs/samples/accordion" name="AccordionControlledSample">
  <AccordionControlledSample />
</PreviewCode>

FAQ Section \[#faq-section]

A practical example of using accordion for a FAQ section.

<PreviewCode file="components/docs/samples/accordion" name="AccordionFAQSample">
  <AccordionFAQSample />
</PreviewCode>

API Reference \[#api-reference]

Composable API \[#composable-api]

| Component          | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `Accordion`        | The root component that manages accordion state and variant. |
| `AccordionItem`    | A single collapsible section container.                      |
| `AccordionTrigger` | The clickable header that toggles content visibility.        |
| `AccordionContent` | The collapsible content panel.                               |

Accordion \[#accordion]

The root component that manages accordion state. Set `variant` here to style all child components.

<ParametersTable
  type="AccordionProps"
  parameters={[
{
  name: "type",
  type: '"single" | "multiple"',
  required: true,
  description: "Whether only one or multiple items can be open at once.",
},
{
  name: "collapsible",
  type: "boolean",
  default: "false",
  description: "When type is 'single', allows closing the open item by clicking it again.",
},
{
  name: "defaultValue",
  type: "string | string[]",
  description: "The default open item(s) (uncontrolled).",
},
{
  name: "value",
  type: "string | string[]",
  description: "The controlled open item(s).",
},
{
  name: "onValueChange",
  type: "(value: string | string[]) => void",
  description: "Callback when the open item(s) change.",
},
{
  name: "variant",
  type: '"default" | "outline" | "ghost"',
  default: '"default"',
  description: "The visual style of the accordion. Child components inherit this automatically.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

AccordionItem \[#accordionitem]

A single collapsible section container.

<ParametersTable
  type="AccordionItemProps"
  parameters={[
{
  name: "value",
  type: "string",
  required: true,
  description: "A unique identifier for this item.",
},
{
  name: "disabled",
  type: "boolean",
  description: "Whether the item is disabled.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

AccordionTrigger \[#accordiontrigger]

The clickable header that toggles content visibility.

<ParametersTable
  type="AccordionTriggerProps"
  parameters={[
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

AccordionContent \[#accordioncontent]

The collapsible content panel.

<ParametersTable
  type="AccordionContentProps"
  parameters={[
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

Style Variants (CVA) \[#style-variants-cva]

| Export              | Description                         |
| ------------------- | ----------------------------------- |
| `accordionVariants` | Styles for the accordion container. |

```tsx
import { accordionVariants } from "@/components/assistant-ui/accordion";

<div className={accordionVariants({ variant: "outline" })}>
  Custom Accordion Container
</div>
```


# AssistantModal
URL: /docs/ui/assistant-modal

Floating chat bubble for support widgets and help desks.

import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";

A floating chat modal built on Radix UI Popover. Ideal for support widgets, help desks, and embedded assistants.

<AssistantModalSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add assistant-modal \[#add-assistant-modal]

    <InstallCommand shadcn={["assistant-modal"]} />

    This adds `/components/assistant-ui/assistant-modal.tsx` to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    ```tsx title="/app/page.tsx" {1,6}
    import { AssistantModal } from "@/components/assistant-ui/assistant-modal";

    export default function Home() {
      return (
        <div className="h-full">
          <AssistantModal />
        </div>
      );
    }
    ```
  </Step>
</Steps>

Anatomy \[#anatomy]

The `AssistantModal` component is built with the following primitives:

```tsx
import { AssistantModalPrimitive } from "@assistant-ui/react";

<AssistantModalPrimitive.Root>
  <AssistantModalPrimitive.Anchor />
  <AssistantModalPrimitive.Trigger />
  <AssistantModalPrimitive.Content>
    {/* Thread component goes here */}
  </AssistantModalPrimitive.Content>
</AssistantModalPrimitive.Root>
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the modal. Based on Radix UI Popover.

<ParametersTable
  type="AssistantModalPrimitiveRootProps"
  parameters={[
{
  name: "defaultOpen",
  type: "boolean",
  description: "The initial open state when uncontrolled.",
},
{
  name: "open",
  type: "boolean",
  description: "The controlled open state.",
},
{
  name: "onOpenChange",
  type: "(open: boolean) => void",
  description: "Callback when the open state changes.",
},
{
  name: "unstable_openOnRunStart",
  type: "boolean",
  description: "Automatically open the modal when the assistant starts running.",
},
]}
/>

Trigger \[#trigger]

A button that toggles the modal open/closed state.

<ParametersTable
  type="AssistantModalPrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

This primitive renders a `<button>` element unless `asChild` is set.

Content \[#content]

The popover content container that holds the chat interface.

<ParametersTable
  type="AssistantModalPrimitiveContentProps"
  parameters={[
{
  name: "side",
  type: "'top' | 'right' | 'bottom' | 'left'",
  default: "'top'",
  description: "The preferred side of the anchor to render against.",
},
{
  name: "align",
  type: "'start' | 'center' | 'end'",
  default: "'end'",
  description: "The preferred alignment against the anchor.",
},
{
  name: "dissmissOnInteractOutside",
  type: "boolean",
  description: "Whether to close the modal when clicking outside.",
},
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

Anchor \[#anchor]

An optional anchor element to position the modal relative to.

<ParametersTable
  type="AssistantModalPrimitiveAnchorProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

Related Components \[#related-components]

* [Thread](/docs/ui/thread) - The main chat interface used inside the modal
* [AssistantSidebar](/docs/ui/assistant-sidebar) - Alternative layout for side panel chat


# AssistantSidebar
URL: /docs/ui/assistant-sidebar

Side panel chat for co-pilot experiences and inline assistance.

import { AssistantSidebarSample } from "@/components/docs/samples/assistant-sidebar";

A resizable side panel layout with your main content on the left and a Thread chat interface on the right. Ideal for co-pilot experiences and inline assistance.

<AssistantSidebarSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add assistant-sidebar \[#add-assistant-sidebar]

    <InstallCommand shadcn={["assistant-sidebar"]} />

    This adds `/components/assistant-ui/assistant-sidebar.tsx` to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    ```tsx title="/app/page.tsx" {1,6}
    import { AssistantSidebar } from "@/components/assistant-ui/assistant-sidebar";

    export default function Home() {
      return (
        <div className="h-full">
          <AssistantSidebar>{/* your app */}</AssistantSidebar>
        </div>
      );
    }
    ```
  </Step>
</Steps>

API Reference \[#api-reference]

AssistantSidebar \[#assistantsidebar]

A layout component that creates a resizable two-panel interface.

<ParametersTable
  type="AssistantSidebarProps"
  parameters={[
{
  name: "children",
  type: "ReactNode",
  description: "Content to display in the left panel (your main application).",
},
]}
/>

The component uses `ResizablePanelGroup` from shadcn/ui internally, creating:

* **Left panel**: Your application content (passed as `children`)
* **Right panel**: The Thread chat interface (rendered automatically)
* **Resize handle**: Draggable divider between panels

Customization \[#customization]

Since this component is copied to your project at `/components/assistant-ui/assistant-sidebar.tsx`, you can customize:

* Panel default sizes and min/max constraints
* Resize handle styling
* Thread component configuration

```tsx title="/components/assistant-ui/assistant-sidebar.tsx"
<ResizablePanelGroup direction="horizontal">
  <ResizablePanel defaultSize={60} minSize={30}>
    {children}
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={40} minSize={20}>
    <Thread />
  </ResizablePanel>
</ResizablePanelGroup>
```

Related Components \[#related-components]

* [Thread](/docs/ui/thread) - The chat interface displayed in the sidebar
* [AssistantModal](/docs/ui/assistant-modal) - Alternative floating modal layout


# Attachment
URL: /docs/ui/attachment

UI components for attaching and viewing files in messages.

import { AttachmentSample } from "@/components/docs/samples/attachment";

<AttachmentSample />

<Callout type="info">
  **Note:** These components provide the UI for attachments, but you also need
  to configure attachment adapters in your runtime to handle file uploads and
  processing. See the [Attachments Guide](/docs/guides/attachments) for complete
  setup instructions.
</Callout>

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add attachment \[#add-attachment]

    <InstallCommand shadcn={["attachment"]} />

    This adds a `/components/assistant-ui/attachment.tsx` file to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    ```tsx title="/components/assistant-ui/thread.tsx" {1-4,9-10}
    import {
      ComposerAttachments,
      ComposerAddAttachment,
    } from "@/components/assistant-ui/attachment";

    const Composer: FC = () => {
      return (
        <ComposerPrimitive.Root className="...">
          <ComposerAttachments />
          <ComposerAddAttachment />

          <ComposerPrimitive.Input
            autoFocus
            placeholder="Write a message..."
            rows={1}
            className="..."
          />
          <ComposerAction />
        </ComposerPrimitive.Root>
      );
    };
    ```

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    import { UserMessageAttachments } from "@/components/assistant-ui/attachment";

    const UserMessage: FC = () => {
      return (
        <MessagePrimitive.Root className="...">
          <UserActionBar />

          <UserMessageAttachments />

          <div className="...">
            <MessagePrimitive.Parts />
          </div>

          <BranchPicker className="..." />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

API Reference \[#api-reference]

Composer Attachments \[#composer-attachments]

ComposerPrimitive.Attachments \[#composerprimitiveattachments]

Renders all attachments in the composer.

<ParametersTable
  type="ComposerPrimitiveAttachmentsProps"
  parameters={[
{
  name: "components",
  type: "AttachmentComponents",
  description: "Components to render for different attachment types.",
  children: [
    {
      type: "AttachmentComponents",
      parameters: [
        {
          name: "Image",
          type: "ComponentType",
          description: "Component for image attachments.",
        },
        {
          name: "Document",
          type: "ComponentType",
          description: "Component for document attachments (PDF, etc.).",
        },
        {
          name: "File",
          type: "ComponentType",
          description: "Component for generic file attachments.",
        },
        {
          name: "Attachment",
          type: "ComponentType",
          description: "Fallback component for all attachment types.",
        },
      ],
    },
  ],
},
]}
/>

ComposerPrimitive.AddAttachment \[#composerprimitiveaddattachment]

A button that opens the file picker to add attachments.

<ParametersTable
  type="ComposerPrimitiveAddAttachmentProps"
  parameters={[
{
  name: "multiple",
  type: "boolean",
  default: "true",
  description: "Allow selecting multiple files at once.",
},
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

This primitive renders a `<button>` element unless `asChild` is set.

Message Attachments \[#message-attachments]

MessagePrimitive.Attachments \[#messageprimitiveattachments]

Renders all attachments in a user message.

<ParametersTable
  type="MessagePrimitiveAttachmentsProps"
  parameters={[
{
  name: "components",
  type: "AttachmentComponents",
  description: "Components to render for different attachment types (same as ComposerPrimitive.Attachments).",
},
]}
/>

Attachment Primitives \[#attachment-primitives]

AttachmentPrimitive.Root \[#attachmentprimitiveroot]

Container for a single attachment.

<ParametersTable
  type="AttachmentPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

AttachmentPrimitive.Name \[#attachmentprimitivename]

Renders the attachment's file name.

AttachmentPrimitive.Remove \[#attachmentprimitiveremove]

A button to remove the attachment from the composer.

<ParametersTable
  type="AttachmentPrimitiveRemoveProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

Attachment Types \[#attachment-types]

Attachments have the following structure:

```typescript
type Attachment = {
  id: string;
  type: "image" | "document" | "file" | (string & {});
  name: string;
  contentType?: string;
  file?: File;
  status:
    | { type: "running" | "requires-action" | "incomplete"; progress?: number }
    | { type: "complete" };
};
```

The `type` field accepts custom strings (e.g. `"data-workflow"`) beyond the built-in types. When an unknown type is encountered, the generic `Attachment` component is used as a fallback. The `contentType` field is optional — it can be omitted for non-file attachments where a MIME type is not meaningful.

Related Components \[#related-components]

* [Thread](/docs/ui/thread) - Main chat interface that displays attachments
* [Attachments Guide](/docs/guides/attachments) - Complete setup instructions for attachment adapters


# Badge
URL: /docs/ui/badge

A small label component for displaying status, categories, or metadata.

import { PreviewCode } from "@/components/docs/preview-code.server";
import {
  BadgeSample,
  BadgeSizesSample,
  BadgeWithIconSample,
  BadgeAsLinkSample,
  BadgeAnimatedSample,
} from "@/components/docs/samples/badge";

<Callout>
  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
</Callout>

<BadgeSample />

Installation \[#installation]

<InstallCommand shadcn={["badge"]} />

Usage \[#usage]

```tsx
import { Badge } from "@/components/assistant-ui/badge";

export function Example() {
  return <Badge>Label</Badge>;
}
```

Examples \[#examples]

Variants \[#variants]

Use the `variant` prop to change the visual style.

<BadgeSample />

```tsx
<Badge variant="outline" />     // Border (default)
<Badge variant="secondary" />   // Secondary background
<Badge variant="muted" />       // Muted background
<Badge variant="ghost" />       // No background
<Badge variant="info" />        // Blue/info style
<Badge variant="warning" />     // Amber/warning style
<Badge variant="success" />     // Green/success style
<Badge variant="destructive" /> // Red/error style
```

Sizes \[#sizes]

Use the `size` prop to change the badge size.

<BadgeSizesSample />

```tsx
<Badge size="sm" />      // Small
<Badge size="default" /> // Default
<Badge size="lg" />      // Large
```

With Icons \[#with-icons]

Badges automatically style SVG icons.

<PreviewCode file="components/docs/samples/badge" name="BadgeWithIconSample">
  <BadgeWithIconSample />
</PreviewCode>

As Link \[#as-link]

Use the `asChild` prop to render the badge as a different element, like a link.

<PreviewCode file="components/docs/samples/badge" name="BadgeAsLinkSample">
  <BadgeAsLinkSample />
</PreviewCode>

Animated \[#animated]

Combine with CSS transitions for scroll and color animations.

<PreviewCode file="components/docs/samples/badge" name="BadgeAnimatedSample">
  <BadgeAnimatedSample />
</PreviewCode>

API Reference \[#api-reference]

Badge \[#badge]

<ParametersTable
  type="BadgeProps"
  parameters={[
{
  name: "variant",
  type: '"outline" | "secondary" | "muted" | "ghost" | "info" | "warning" | "success" | "destructive"',
  default: '"outline"',
  description: "The visual style of the badge.",
},
{
  name: "size",
  type: '"sm" | "default" | "lg"',
  default: '"default"',
  description: "The size of the badge.",
},
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a span.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

Style Variants (CVA) \[#style-variants-cva]

| Export          | Description                     |
| --------------- | ------------------------------- |
| `badgeVariants` | Styles for the badge component. |

```tsx
import { badgeVariants } from "@/components/assistant-ui/badge";

<span className={badgeVariants({ variant: "muted", size: "sm" })}>
  Custom Badge
</span>
```


# Context Display
URL: /docs/ui/context-display

Visualize token usage relative to a model's context window — ring, bar, or text — with a detailed hover popover.

import { ContextDisplaySample } from "@/components/docs/samples/context-display";

<ContextDisplaySample />

<Callout type="info">
  This component requires server-side setup to [forward token usage metadata](#forward-token-usage-from-your-route-handler). Without it, ContextDisplay will show 0 usage and no breakdown data.
</Callout>

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add context-display \[#add-context-display]

    <InstallCommand shadcn={["context-display"]} />

    This adds a `/components/assistant-ui/context-display.tsx` file to your project.
  </Step>

  <Step>
    Forward token usage from your route handler \[#forward-token-usage-from-your-route-handler]

    Use `messageMetadata` in your Next.js route to attach `usage` from `finish` and `modelId` from `finish-step`:

    ```tsx title="app/api/chat/route.ts"
    import { streamText, convertToModelMessages } from "ai";

    export async function POST(req: Request) {
      const { messages, modelName } = await req.json();
      const result = streamText({
        model: getModel(modelName),
        messages: await convertToModelMessages(messages),
      });
      return result.toUIMessageStreamResponse({
        messageMetadata: ({ part }) => {
          if (part.type === "finish") {
            return {
              usage: part.totalUsage,
            };
          }
          if (part.type === "finish-step") {
            return {
              modelId: part.response.modelId,
            };
          }
          return undefined;
        },
      });
    }
    ```
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Pick a variant and place it in your thread footer, composer, or sidebar. Pass `modelContextWindow` with your model's token limit.

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    import { ContextDisplay } from "@/components/assistant-ui/context-display";

    const ThreadFooter: FC = () => {
      return (
        <div className="flex items-center justify-end px-3 py-1.5">
          <ContextDisplay.Bar modelContextWindow={128000} />
        </div>
      );
    };
    ```
  </Step>
</Steps>

Variants \[#variants]

Three preset variants are available, each wrapping the shared tooltip popover:

```tsx
// SVG donut ring (default, compact)
<ContextDisplay.Ring modelContextWindow={128000} />

// Horizontal progress bar with label
<ContextDisplay.Bar modelContextWindow={128000} />

// Minimal monospace text
<ContextDisplay.Text modelContextWindow={128000} />
```

All presets accept `className` for styling overrides and `side` to control tooltip placement (`"top"`, `"bottom"`, `"left"`, `"right"`).

Composable API \[#composable-api]

For custom visualizations, use the building blocks directly:

```tsx
import { ContextDisplay } from "@/components/assistant-ui/context-display";

<ContextDisplay.Root modelContextWindow={128000}>
  <ContextDisplay.Trigger aria-label="Context usage">
    <MyCustomGauge />
  </ContextDisplay.Trigger>
  <ContextDisplay.Content side="top" />
</ContextDisplay.Root>
```

| Component | Description                                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Root`    | Uses provided `usage` when supplied, otherwise fetches token usage internally; provides shared context and wraps children in a tooltip |
| `Trigger` | Button that opens the tooltip on hover                                                                                                 |
| `Content` | Tooltip popover with the token breakdown (Usage %, Input, Cached, Output, Reasoning, Total)                                            |

API Reference \[#api-reference]

Preset Props \[#preset-props]

All preset variants (`Ring`, `Bar`, `Text`) share the same props:

| Prop                 | Type                                     | Default | Description                                                                        |
| -------------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| `modelContextWindow` | `number`                                 | —       | Maximum token limit of the current model (required)                                |
| `className`          | `string`                                 | —       | Additional class names on the trigger button                                       |
| `side`               | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Tooltip placement                                                                  |
| `usage`              | `ThreadTokenUsage`                       | —       | Optional externally-provided usage data (skips internal usage fetch when provided) |

Color Thresholds \[#color-thresholds]

Ring and Bar share the same severity colors:

| Level    | Threshold   | Ring                 | Bar              |
| -------- | ----------- | -------------------- | ---------------- |
| Low      | `< 65%`     | `stroke-emerald-500` | `bg-emerald-500` |
| Warning  | `65% – 85%` | `stroke-amber-500`   | `bg-amber-500`   |
| Critical | `> 85%`     | `stroke-red-500`     | `bg-red-500`     |

Text displays numeric values only — no severity color.

Related \[#related]

* [Message Timing](/docs/ui/message-timing) — Streaming performance stats (TTFT, tok/s)
* [Thread](/docs/ui/thread) — The thread component where ContextDisplay is typically placed


# Diff Viewer
URL: /docs/ui/diff-viewer

Render code diffs with syntax highlighting for additions and deletions.

import { PreviewCode } from "@/components/docs/preview-code.server";
import {
  DiffViewerSample,
  DiffViewerSplitSample,
  DiffViewerViewModesSample,
  DiffViewerVariantsSample,
  DiffViewerSizesSample,
} from "@/components/docs/samples/diff-viewer";

<Callout>
  This is a **standalone component** that does not depend on the assistant-ui runtime.
</Callout>

<DiffViewerViewModesSample />

Installation \[#installation]

<InstallCommand shadcn={["diff-viewer"]} />

Usage \[#usage]

```tsx
import { DiffViewer } from "@/components/assistant-ui/diff-viewer";

// With a unified diff patch
<DiffViewer patch={diffString} />

// With file comparison
<DiffViewer
  oldFile={{ content: "old content", name: "file.txt" }}
  newFile={{ content: "new content", name: "file.txt" }}
/>
```

As Markdown Language Override \[#as-markdown-language-override]

Integrate with `MarkdownTextPrimitive` to render diff code blocks:

```tsx title="/components/assistant-ui/markdown-text.tsx"
import { DiffViewer } from "@/components/assistant-ui/diff-viewer"; // [!code ++]

const MarkdownTextImpl = () => {
  return (
    <MarkdownTextPrimitive
      remarkPlugins={[remarkGfm]}
      className="aui-md"
      components={defaultComponents}
      componentsByLanguage={{                                       // [!code ++]
        diff: {                                                     // [!code ++]
          SyntaxHighlighter: ({ code }) => <DiffViewer patch={code} /> // [!code ++]
        },                                                          // [!code ++]
      }}                                                            // [!code ++]
    />
  );
};

export const MarkdownText = memo(MarkdownTextImpl);
```

Examples \[#examples]

Unified View \[#unified-view]

Shows all changes in a single column with `+`/`-` indicators. This is the default mode.

<DiffViewerSample />

```tsx
<DiffViewer patch={diffString} viewMode="unified" />
```

Split View \[#split-view]

Shows old content on the left, new content on the right side-by-side.

<DiffViewerSplitSample />

```tsx
<DiffViewer patch={diffString} viewMode="split" />
```

Interactive Mode Toggle \[#interactive-mode-toggle]

<PreviewCode file="components/docs/samples/diff-viewer" name="DiffViewerViewModesSample">
  <DiffViewerViewModesSample />
</PreviewCode>

Variants \[#variants]

<DiffViewerVariantsSample />

Sizes \[#sizes]

<DiffViewerSizesSample />

Theming \[#theming]

DiffViewer uses CSS variables for colors. Override them in your CSS:

```css
[data-slot="diff-viewer"] {
  --diff-add-bg: rgba(46, 160, 67, 0.15);
  --diff-add-text: #1a7f37;
  --diff-add-text-dark: #3fb950;
  --diff-del-bg: rgba(248, 81, 73, 0.15);
  --diff-del-text: #cf222e;
  --diff-del-text-dark: #f85149;
}
```

| Variable               | Description                               |
| ---------------------- | ----------------------------------------- |
| `--diff-add-bg`        | Background for added lines                |
| `--diff-add-text`      | Text color for added lines (light mode)   |
| `--diff-add-text-dark` | Text color for added lines (dark mode)    |
| `--diff-del-bg`        | Background for deleted lines              |
| `--diff-del-text`      | Text color for deleted lines (light mode) |
| `--diff-del-text-dark` | Text color for deleted lines (dark mode)  |

API Reference \[#api-reference]

DiffViewer \[#diffviewer]

The main component for rendering diffs.

<ParametersTable
  type="DiffViewerProps"
  parameters={[
{
  name: "patch",
  type: "string",
  description: "Unified diff string (e.g., output from git diff).",
},
{
  name: "code",
  type: "string",
  description: "Alias for patch (for markdown integration).",
},
{
  name: "oldFile",
  type: "{ content: string; name?: string }",
  description: "Old file for direct comparison.",
},
{
  name: "newFile",
  type: "{ content: string; name?: string }",
  description: "New file for direct comparison.",
},
{
  name: "viewMode",
  type: '"unified" | "split"',
  default: '"unified"',
  description: "Display mode for the diff.",
},
{
  name: "variant",
  type: '"default" | "ghost" | "muted"',
  default: '"default"',
  description: "Visual style variant.",
},
{
  name: "size",
  type: '"sm" | "default" | "lg"',
  default: '"default"',
  description: "Font size.",
},
{
  name: "showLineNumbers",
  type: "boolean",
  default: "true",
  description: "Show line numbers.",
},
{
  name: "showIcon",
  type: "boolean",
  default: "true",
  description: "Show file extension badge in header.",
},
{
  name: "showStats",
  type: "boolean",
  default: "true",
  description: "Show addition/deletion counts in header.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

Composable API \[#composable-api]

| Component             | Description                                |
| --------------------- | ------------------------------------------ |
| `DiffViewer`          | Main component that renders the diff.      |
| `DiffViewerFile`      | Wrapper for each file in multi-file diffs. |
| `DiffViewerHeader`    | File name header with icon and stats.      |
| `DiffViewerContent`   | Scrollable content area.                   |
| `DiffViewerLine`      | Individual line in unified mode.           |
| `DiffViewerSplitLine` | Side-by-side line pair in split mode.      |
| `DiffViewerFileBadge` | File extension badge (e.g., "TS").         |
| `DiffViewerStats`     | Addition/deletion count display.           |

Style Variants (CVA) \[#style-variants-cva]

| Export                 | Description                       |
| ---------------------- | --------------------------------- |
| `diffViewerVariants`   | Styles for the root container.    |
| `diffLineVariants`     | Background styles for diff lines. |
| `diffLineTextVariants` | Text color styles for diff lines. |

```tsx
import {
  diffViewerVariants,
  diffLineVariants,
  diffLineTextVariants,
} from "@/components/assistant-ui/diff-viewer";

// Use variants directly
<div className={diffViewerVariants({ variant: "ghost", size: "sm" })}>
  Custom diff container
</div>
```

Utilities \[#utilities]

| Export                  | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `parsePatch(patch)`     | Parse unified diff string into structured data. |
| `computeDiff(old, new)` | Compute diff between two strings.               |
| `ParsedLine`            | Type for a single diff line.                    |
| `ParsedFile`            | Type for a parsed file with lines and stats.    |
| `SplitLinePair`         | Type for a side-by-side line pair.              |

Styling \[#styling]

Data Attributes \[#data-attributes]

Use data attributes for custom styling:

| Attribute        | Values                                                              | Description              |
| ---------------- | ------------------------------------------------------------------- | ------------------------ |
| `data-slot`      | `"diff-viewer"`, `"diff-viewer-header"`, `"diff-viewer-line"`, etc. | Component identification |
| `data-type`      | `"add"`, `"del"`, `"normal"`, `"empty"`                             | Line type                |
| `data-view-mode` | `"unified"`, `"split"`                                              | Current view mode        |
| `data-variant`   | `"default"`, `"ghost"`, `"muted"`                                   | Current variant          |

Custom CSS Example \[#custom-css-example]

```css
[data-slot="diff-viewer"][data-view-mode="split"] {
  /* Custom split view styles */
}

[data-slot="diff-viewer-line"][data-type="add"] {
  /* Custom addition styles */
}

[data-slot="diff-viewer-line"][data-type="del"] {
  /* Custom deletion styles */
}
```

Related Components \[#related-components]

* [Markdown](/docs/ui/markdown) - Rich text rendering where diff viewer can be integrated
* [Syntax Highlighting](/docs/ui/syntax-highlighting) - Code highlighting for other languages


# File
URL: /docs/ui/file

Display file message parts with icon, name, size, and download button.

import { FileSample } from "@/components/docs/samples/file";

<FileSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add file \[#add-file]

    <InstallCommand shadcn={["file"]} />
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Pass `File` to `MessagePrimitive.Parts`:

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    import { File } from "@/components/assistant-ui/file";

    const AssistantMessage: FC = () => {
      return (
        <MessagePrimitive.Root className="...">
          <MessagePrimitive.Parts
            components={{
              File,
            }}
          />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Variants \[#variants]

Use the `variant` prop to change the visual style.

```tsx
<File.Root variant="outline" /> // Border (default)
<File.Root variant="ghost" />   // No border
<File.Root variant="muted" />   // Background fill
```

Sizes \[#sizes]

Use the `size` prop to change padding and font size.

```tsx
<File.Root size="sm" />      // Compact
<File.Root size="default" /> // Default
<File.Root size="lg" />      // Larger
```

MimeType Icons \[#mimetype-icons]

The component automatically selects an appropriate icon based on the file's MIME type:

| MIME Type          | Icon         |
| ------------------ | ------------ |
| `image/*`          | ImageIcon    |
| `application/pdf`  | FileTextIcon |
| `application/json` | BracesIcon   |
| `text/*`           | FileTextIcon |
| `audio/*`          | MusicIcon    |
| `video/*`          | VideoIcon    |
| fallback           | FileIcon     |

API Reference \[#api-reference]

Composable API \[#composable-api]

The component exports composable sub-components:

```tsx
import {
  File,
  FileRoot,
  FileIconDisplay,
  FileName,
  FileSize,
  FileDownload,
} from "@/components/assistant-ui/file";

<FileRoot variant="muted" size="lg">
  <FileIconDisplay mimeType="application/pdf" />
  <div className="flex flex-col gap-0.5">
    <FileName>report.pdf</FileName>
    <FileSize bytes={2048} className="text-xs" />
  </div>
  <FileDownload
    data="SGVsbG8gV29ybGQh"
    mimeType="application/pdf"
    filename="report.pdf"
  />
</FileRoot>
```

| Component       | Description                                     |
| --------------- | ----------------------------------------------- |
| `File`          | Default export, renders complete file part      |
| `File.Root`     | Container with variant and size styling         |
| `File.Icon`     | MIME type-aware icon, or pass custom `children` |
| `File.Name`     | Truncated filename                              |
| `File.Size`     | Human-readable file size                        |
| `File.Download` | Download link button                            |

Custom Icon \[#custom-icon]

Pass `children` to `File.Icon` to override the default MIME type icon:

```tsx
<File.Icon>
  <MyCustomIcon className="size-5" />
</File.Icon>
```

Utilities \[#utilities]

The component also exports utility functions:

```tsx
import {
  getMimeTypeIcon,
  getBase64Size,
  formatFileSize,
} from "@/components/assistant-ui/file";

// Get icon component for a MIME type
const Icon = getMimeTypeIcon("application/pdf"); // FileTextIcon

// Calculate size from base64 string
const bytes = getBase64Size("SGVsbG8gV29ybGQh"); // 12

// Format bytes to human-readable
const size = formatFileSize(2048); // "2.0 KB"
```

Related Components \[#related-components]

* [Image](/docs/ui/image) - Image message parts
* [Attachment](/docs/ui/attachment) - File attachments in composer and messages


# Image
URL: /docs/ui/image

Display image message parts with preview, loading states, and fullscreen dialog.

import { ImageSample } from "@/components/docs/samples/image";

<ImageSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add image \[#add-image]

    <InstallCommand shadcn={["image"]} />
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Pass `Image` to `MessagePrimitive.Parts`:

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    import { Image } from "@/components/assistant-ui/image";

    const AssistantMessage: FC = () => {
      return (
        <MessagePrimitive.Root className="...">
          <MessagePrimitive.Parts
            components={{
              Image,
            }}
          />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Variants \[#variants]

Use the `variant` prop to change the visual style.

```tsx
<Image.Root variant="outline" /> // Border (default)
<Image.Root variant="ghost" />   // No border
<Image.Root variant="muted" />   // Background fill
```

Sizes \[#sizes]

Use the `size` prop to control the maximum width.

```tsx
<Image.Root size="sm" />      // max-w-64 (256px)
<Image.Root size="default" /> // max-w-96 (384px)
<Image.Root size="lg" />      // max-w-[512px]
<Image.Root size="full" />    // w-full
```

API Reference \[#api-reference]

Composable API \[#composable-api]

The component exports composable sub-components:

```tsx
import {
  Image,
  ImageRoot,
  ImagePreview,
  ImageFilename,
  ImageZoom,
} from "@/components/assistant-ui/image";

<ImageRoot variant="muted" size="lg">
  <ImageZoom src="https://example.com/photo.jpg" alt="Photo">
    <ImagePreview src="https://example.com/photo.jpg" alt="Photo" />
  </ImageZoom>
  <ImageFilename>photo.jpg</ImageFilename>
</ImageRoot>
```

| Component        | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `Image`          | Default export, renders complete image part               |
| `Image.Root`     | Container with variant and size styling                   |
| `Image.Preview`  | Image container with loading/error states                 |
| `Image.Filename` | Optional filename display below image                     |
| `Image.Zoom`     | Medium-style zoom overlay (click to expand, ESC to close) |

Related Components \[#related-components]

* [Attachment](/docs/ui/attachment) - File attachments in composer and messages
* [File](/docs/ui/file) - Non-image file message parts


# Markdown
URL: /docs/ui/markdown

Display rich text with headings, lists, links, and code blocks.

import { MarkdownSample } from "@/components/docs/samples/markdown";

<MarkdownSample />

<Callout>
  Markdown support is already included by default in the `Thread` component.
</Callout>

Enabling markdown support \[#enabling-markdown-support]

<Steps>
  <Step>
    Add markdown-text \[#add-markdown-text]

    <InstallCommand shadcn={["markdown-text"]} />

    This adds a `/components/assistant-ui/markdown-text.tsx` file to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use it in your application \[#use-it-in-your-application]

    Pass the `MarkdownText` component to the `MessagePrimitive.Parts` component

    ```tsx twoslash title="/components/assistant-ui/thread.tsx" {1,7}
    // @filename: /components/assistant-ui/markdown-text.tsx
    import { FC } from "react";
    export const MarkdownText: FC = () => null;

    // @filename: ./thread.tsx
    import { FC } from "react";
    import { MessagePrimitive } from "@assistant-ui/react";
    import { Avatar, AvatarFallback } from "@/components/ui/avatar";

    const AssistantActionBar: FC = () => null;
    const BranchPicker: FC<{ className?: string }> = () => null;

    // ---cut---
    import { MarkdownText } from "@/components/assistant-ui/markdown-text";

    const AssistantMessage: FC = () => {
      return (
        <MessagePrimitive.Root className="...">
          <div className="...">
            <MessagePrimitive.Parts components={{ Text: MarkdownText }} />
          </div>
          <AssistantActionBar />

          <BranchPicker className="..." />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Syntax highlighting \[#syntax-highlighting]

Syntax Highlighting is not included by default, see [Syntax Highlighting](/docs/ui/syntax-highlighting) to learn how to add it.

Related Components \[#related-components]

* [Syntax Highlighting](/docs/ui/syntax-highlighting) - Add code highlighting to markdown
* [Mermaid](/docs/ui/mermaid) - Render diagrams in markdown code blocks


# Mermaid Diagrams
URL: /docs/ui/mermaid

Render Mermaid diagrams in chat messages with streaming support.

import { MermaidSample } from "@/components/docs/samples/mermaid";

<MermaidSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add mermaid-diagram component \[#add-mermaid-diagram-component]

    <InstallCommand shadcn={["mermaid-diagram"]} />

    This will install the required dependencies and add the component to your project.
  </Step>

  <Step>
    Add it to componentsByLanguage in markdown-text.tsx \[#add-it-to-componentsbylanguage-in-markdown-texttsx]

    ```tsx title="/components/assistant-ui/markdown-text.tsx"
    import { MermaidDiagram } from "@/components/assistant-ui/mermaid-diagram"; // [!code ++]

    const MarkdownTextImpl = () => {
      return (
        <MarkdownTextPrimitive
          remarkPlugins={[remarkGfm]}
          className="aui-md"
          components={defaultComponents}
          componentsByLanguage={{               // [!code ++]
            mermaid: {                          // [!code ++]
              SyntaxHighlighter: MermaidDiagram // [!code ++]
            },                                  // [!code ++]
          }}                                    // [!code ++]
        />
      );
    };

    export const MarkdownText = memo(MarkdownTextImpl);
    ```
  </Step>
</Steps>

Configuration \[#configuration]

Configure mermaid options in `mermaid-diagram.tsx`:

```tsx title="/components/assistant-ui/mermaid-diagram.tsx"
mermaid.initialize({ theme: "default" });
```

Streaming Performance \[#streaming-performance]

The `MermaidDiagram` component is optimized for streaming scenarios:

* **Smart completion detection**: Only renders when the specific code block is complete
* **Zero failed renders**: Avoids parsing incomplete diagram code during streaming

Supported Diagram Types \[#supported-diagram-types]

Mermaid supports various diagram types including:

* Flowcharts and decision trees
* Sequence diagrams
* Gantt charts
* Class diagrams
* State diagrams
* Git graphs
* User journey maps
* Entity relationship diagrams

See the [Mermaid documentation](https://mermaid.js.org/) for complete syntax reference.

Related Components \[#related-components]

* [Markdown](/docs/ui/markdown) - Rich text rendering where mermaid is integrated
* [Syntax Highlighting](/docs/ui/syntax-highlighting) - Code highlighting for other languages


# Message Timing
URL: /docs/ui/message-timing

Display streaming performance stats — TTFT, total time, tok/s, and chunk count — as a badge with hover popover.

import { MessageTimingSample } from "@/components/docs/samples/message-timing";

<MessageTimingSample />

<Callout type="warn">
  This component is experimental. The API and displayed metrics may change in future versions. When used with the Vercel AI SDK, token counts and tok/s are **estimated** client-side and may be inaccurate — see [Accuracy](#accuracy) below.
</Callout>

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add message-timing \[#add-message-timing]

    <InstallCommand shadcn={["message-timing"]} />

    This adds a `/components/assistant-ui/message-timing.tsx` file to your project.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Place `MessageTiming` inside `ActionBarPrimitive.Root` in your `thread.tsx`. It will inherit the action bar's auto-hide behaviour and only renders after the stream completes.

    ```tsx title="/components/assistant-ui/thread.tsx" {2,12}
    import { ActionBarPrimitive } from "@assistant-ui/react";
    import { MessageTiming } from "@/components/assistant-ui/message-timing";

    const AssistantActionBar: FC = () => {
      return (
        <ActionBarPrimitive.Root
          hideWhenRunning
          autohide="not-last"
        >
          <ActionBarPrimitive.Copy />
          <ActionBarPrimitive.Reload />
          <MessageTiming />
        </ActionBarPrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

What It Shows \[#what-it-shows]

The badge displays `totalStreamTime` inline and reveals a popover on hover with the full breakdown:

| Metric          | Description                                               |
| --------------- | --------------------------------------------------------- |
| **First token** | Time from request start to first text chunk (TTFT)        |
| **Total**       | Total wall-clock time from start to stream end            |
| **Speed**       | Output tokens per second (hidden for very short messages) |
| **Chunks**      | Number of stream chunks received                          |

Accuracy \[#accuracy]

Timing accuracy depends on how your backend is connected.

assistant-stream (accurate) \[#assistant-stream-accurate]

When using `assistant-stream` on the backend, token counts come directly from the model's usage data sent in `step-finish` chunks. The `tokensPerSecond` metric is exact whenever your backend reports `outputTokens`.

Vercel AI SDK (estimated) \[#vercel-ai-sdk-estimated]

When using the AI SDK integration (`useChatRuntime`), token counts are **estimated** client-side using a 4 characters per token approximation. This can overcount significantly for short messages.

API Reference \[#api-reference]

MessageTiming component \[#messagetiming-component]

| Prop        | Type                                     | Default   | Description                                |
| ----------- | ---------------------------------------- | --------- | ------------------------------------------ |
| `className` | `string`                                 | —         | Additional class names on the root element |
| `side`      | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Side of the tooltip relative to the badge  |

Renders `null` until `totalStreamTime` is available (i.e., while streaming or for user messages).

For the underlying `useMessageTiming()` hook, field definitions, and runtime-specific setup (LocalRuntime, ExternalStore, etc.), see the [Message Timing guide](/docs/guides/message-timing).

Related \[#related]

* [Message Timing guide](/docs/guides/message-timing) — `useMessageTiming()` hook, runtime support table, and custom timing UI
* [Thread](/docs/ui/thread) — The action bar context that `MessageTiming` is typically placed inside


# ModelSelector
URL: /docs/ui/model-selector

Model picker with unified overlay positioning and runtime integration.

import { ModelSelectorSample } from "@/components/docs/samples/model-selector";

A select component that lets users switch between AI models. Uses item-aligned positioning so the selected model overlays the trigger for a unified look. Integrates with assistant-ui's `ModelContext` system to automatically propagate the selected model to your backend.

<ModelSelectorSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add model-selector \[#add-model-selector]

    <InstallCommand shadcn={["model-selector"]} />
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Place the `ModelSelector` inside your thread component, typically in the composer area:

    ```tsx title="/components/assistant-ui/thread.tsx" {1,6-14}
    import { ModelSelector } from "@/components/assistant-ui/model-selector";

    const ComposerAction: FC = () => {
      return (
        <div className="flex items-center gap-1">
          <ModelSelector
            models={[
              { id: "gpt-5-nano", name: "GPT-5 Nano", description: "Fast and efficient" },
              { id: "gpt-5-mini", name: "GPT-5 Mini", description: "Balanced performance" },
              { id: "gpt-5", name: "GPT-5", description: "Most capable" },
            ]}
            defaultValue="gpt-5-mini"
            size="sm"
          />
        </div>
      );
    };
    ```
  </Step>

  <Step>
    Read the model in your API route \[#read-the-model-in-your-api-route]

    The selected model name is sent as `config.modelName` in the request body:

    ```tsx title="app/api/chat/route.ts" {2,5}
    export async function POST(req: Request) {
      const { messages, config } = await req.json();

      const result = streamText({
        model: openai(config?.modelName ?? "gpt-4o"),
        messages: convertToModelMessages(messages),
      });

      return result.toUIMessageStreamResponse();
    }
    ```
  </Step>
</Steps>

Variants \[#variants]

Use the `variant` prop to change the trigger's visual style.

```tsx
<ModelSelector variant="outline" /> // Border (default)
<ModelSelector variant="ghost" />   // No background
<ModelSelector variant="muted" />   // Solid background
```

| Variant   | Description                                  |
| --------- | -------------------------------------------- |
| `outline` | Border with transparent background (default) |
| `ghost`   | No background, subtle hover                  |
| `muted`   | Solid secondary background                   |

Sizes \[#sizes]

Use the `size` prop to control the trigger dimensions.

```tsx
<ModelSelector size="sm" />      // Compact (h-8, text-xs)
<ModelSelector size="default" /> // Standard (h-9)
<ModelSelector size="lg" />      // Large (h-10)
```

Model Options \[#model-options]

Each model in the `models` array supports:

```tsx
const models = [
  {
    id: "gpt-5",           // Sent to backend as config.modelName
    name: "GPT-5",         // Display name in trigger and items
    description: "Most capable", // Optional subtitle in items only
    icon: <SparklesIcon />,      // Optional icon (any ReactNode)
  },
];
```

Runtime Integration \[#runtime-integration]

The default `ModelSelector` export automatically registers the selected model with assistant-ui's `ModelContext` system. When a user selects a model:

1. The component calls `api.modelContext().register()` with `config.modelName`
2. The `AssistantChatTransport` includes `config` in the request body
3. Your API route reads `config.modelName` to determine which model to use

This works out of the box with `@assistant-ui/react-ai-sdk`.

API Reference \[#api-reference]

Composable API \[#composable-api]

For custom layouts, use the sub-components directly with `ModelSelector.Root`:

```tsx
import {
  ModelSelectorRoot,
  ModelSelectorTrigger,
  ModelSelectorContent,
  ModelSelectorItem,
} from "@/components/assistant-ui/model-selector";

<ModelSelectorRoot models={models} value={modelId} onValueChange={setModelId}>
  <ModelSelectorTrigger variant="outline" />
  <ModelSelectorContent />
</ModelSelectorRoot>
```

| Component               | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `ModelSelector`         | Default export with runtime integration              |
| `ModelSelector.Root`    | Presentational root (no runtime, controlled state)   |
| `ModelSelector.Trigger` | CVA-styled trigger showing current model             |
| `ModelSelector.Content` | Select content with model items                      |
| `ModelSelector.Item`    | Individual model option with icon, name, description |

ModelSelector \[#modelselector]

<ParametersTable
  type="ModelSelectorProps"
  parameters={[
{
  name: "models",
  type: "ModelOption[]",
  required: true,
  description: "Array of available models to display.",
},
{
  name: "defaultValue",
  type: "string",
  description: "Initial model ID for uncontrolled usage.",
},
{
  name: "value",
  type: "string",
  description: "Controlled selected model ID.",
},
{
  name: "onValueChange",
  type: "(value: string) => void",
  description: "Callback when selected model changes.",
},
{
  name: "variant",
  type: '"outline" | "ghost" | "muted"',
  default: '"outline"',
  description: "Visual style of the trigger button.",
},
{
  name: "size",
  type: '"sm" | "default" | "lg"',
  default: '"default"',
  description: "Size of the trigger button.",
},
{
  name: "contentClassName",
  type: "string",
  description: "Additional class name for the dropdown content.",
},
]}
/>

ModelOption \[#modeloption]

<ParametersTable
  type="ModelOption"
  parameters={[
{
  name: "id",
  type: "string",
  required: true,
  description: "Unique identifier sent to the backend as modelName.",
},
{
  name: "name",
  type: "string",
  required: true,
  description: "Display name shown in trigger and dropdown.",
},
{
  name: "description",
  type: "string",
  description: "Optional subtitle shown below the model name.",
},
{
  name: "icon",
  type: "React.ReactNode",
  description: "Optional icon displayed before the model name.",
},
]}
/>


# Message Part Grouping
URL: /docs/ui/part-grouping

Organize message parts into custom groups with flexible grouping functions.

import { PartGroupingSample } from "@/components/docs/samples/part-grouping";

<PartGroupingSample />

<Callout type="warn">
  This feature is experimental and the API may change in future versions.
</Callout>

Basic Usage \[#basic-usage]

Use the `MessagePrimitive.Unstable_PartsGrouped` component with a custom grouping function:

```tsx twoslash title="/components/assistant-ui/thread.tsx"
import { FC, PropsWithChildren } from "react";
import { MessagePrimitive } from "@assistant-ui/react";

const AssistantActionBar: FC = () => null;
const BranchPicker: FC<{ className?: string }> = () => null;

// ---cut---
const AssistantMessage: FC = () => {
  return (
    <MessagePrimitive.Root className="...">
      <div className="...">
        <MessagePrimitive.Unstable_PartsGrouped
          groupingFunction={(parts) => {
            // Your custom grouping logic here
            return [{ groupKey: undefined, indices: [0, 1, 2] }];
          }}
          components={{
            Group: ({ groupKey, indices, children }) => {
              // Your custom group rendering
              return <div className="group">{children}</div>;
            },
          }}
        />
      </div>
      <AssistantActionBar />
      <BranchPicker className="..." />
    </MessagePrimitive.Root>
  );
};
```

How Grouping Works \[#how-grouping-works]

The grouping function receives all message parts and returns an array of groups. Each group contains:

* `groupKey`: A string identifier for the group (or `undefined` for ungrouped parts)
* `indices`: An array of indices indicating which parts belong to this group

Use Cases & Examples \[#use-cases--examples]

Group by Parent ID \[#group-by-parent-id]

Group related content together using a parent-child relationship:

```tsx
import { FC, PropsWithChildren, useState } from "react";
import { ChevronDownIcon, ChevronUpIcon } from "lucide-react";

const groupByParentId = (parts: readonly any[]) => {
  const groups = new Map<string, number[]>();

  for (let i = 0; i < parts.length; i++) {
    const part = parts[i];
    const groupId = part?.parentId ?? `__ungrouped_${i}`;

    const indices = groups.get(groupId) ?? [];
    indices.push(i);
    groups.set(groupId, indices);
  }

  return Array.from(groups.entries()).map(([groupId, indices]) => ({
    groupKey: groupId.startsWith("__ungrouped_") ? undefined : groupId,
    indices,
  }));
};

// Usage with collapsible groups
const CollapsibleGroup: FC<
  PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>
> = ({ groupKey, indices, children }) => {
  const [isCollapsed, setIsCollapsed] = useState(false);

  if (!groupKey) return <>{children}</>;

  return (
    <div className="my-2 overflow-hidden rounded-lg border">
      <button
        onClick={() => setIsCollapsed(!isCollapsed)}
        className="hover:bg-muted/50 flex w-full items-center justify-between p-3"
      >
        <span>
          Group {groupKey} ({indices.length} items)
        </span>
        {isCollapsed ? <ChevronDownIcon /> : <ChevronUpIcon />}
      </button>
      {!isCollapsed && <div className="border-t p-3">{children}</div>}
    </div>
  );
};
```

Group by Tool Name \[#group-by-tool-name]

Organize tool calls by their type:

```tsx
import { FC, PropsWithChildren } from "react";

const groupByToolName = (parts: readonly any[]) => {
  const groups = new Map<string, number[]>();

  for (let i = 0; i < parts.length; i++) {
    const part = parts[i];
    // Group tool calls by tool name, everything else ungrouped
    const groupKey = part.type === "tool-call" ? part.toolName : `__other_${i}`;

    const indices = groups.get(groupKey) ?? [];
    indices.push(i);
    groups.set(groupKey, indices);
  }

  return Array.from(groups.entries()).map(([groupKey, indices]) => ({
    groupKey: groupKey.startsWith("__other_") ? undefined : groupKey,
    indices,
  }));
};

// Render tool groups with custom styling
const ToolGroup: FC<
  PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>
> = ({ groupKey, indices, children }) => {
  if (!groupKey) return <>{children}</>;

  return (
    <div className="tool-group my-2 rounded-lg border">
      <div className="bg-muted/50 px-4 py-2 text-sm font-medium">
        Tool: {groupKey} ({indices.length} calls)
      </div>
      <div className="p-4">{children}</div>
    </div>
  );
};
```

Group Consecutive Text Parts \[#group-consecutive-text-parts]

Combine multiple text parts into cohesive blocks:

```tsx
import { FC, PropsWithChildren } from "react";

type MessagePartGroup = {
  groupKey: string | undefined;
  indices: number[];
};

const groupConsecutiveText = (parts: readonly any[]) => {
  const groups: MessagePartGroup[] = [];
  let currentGroup: number[] = [];
  let isTextGroup = false;

  for (let i = 0; i < parts.length; i++) {
    const isText = parts[i].type === "text";

    if (isText === isTextGroup && currentGroup.length > 0) {
      currentGroup.push(i);
    } else {
      if (currentGroup.length > 0) {
        groups.push({
          groupKey: isTextGroup ? "text-block" : undefined,
          indices: currentGroup,
        });
      }
      currentGroup = [i];
      isTextGroup = isText;
    }
  }

  if (currentGroup.length > 0) {
    groups.push({
      groupKey: isTextGroup ? "text-block" : undefined,
      indices: currentGroup,
    });
  }

  return groups;
};

// Render text blocks with special formatting
const TextBlockGroup: FC<
  PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>
> = ({ groupKey, indices, children }) => {
  if (groupKey === "text-block") {
    return (
      <div className="prose prose-sm my-2 rounded-lg bg-gray-50 p-4">
        {children}
      </div>
    );
  }
  return <>{children}</>;
};
```

Group by Content Type \[#group-by-content-type]

Separate different types of content for distinct visual treatment:

```tsx
type MessagePartGroup = {
  groupKey: string | undefined;
  indices: number[];
};

const groupByContentType = (parts: readonly any[]) => {
  const typeGroups = new Map<string, number[]>();

  for (let i = 0; i < parts.length; i++) {
    const part = parts[i];
    const type = part.type;

    const indices = typeGroups.get(type) ?? [];
    indices.push(i);
    typeGroups.set(type, indices);
  }

  // Order groups by type priority
  const typeOrder = [
    "reasoning",
    "tool-call",
    "source",
    "text",
    "image",
    "file",
  ];
  const orderedGroups: MessagePartGroup[] = [];

  for (const type of typeOrder) {
    const indices = typeGroups.get(type);
    if (indices && indices.length > 0) {
      orderedGroups.push({ groupKey: type, indices });
    }
  }

  // Add any remaining types
  for (const [type, indices] of typeGroups) {
    if (!typeOrder.includes(type)) {
      orderedGroups.push({ groupKey: type, indices });
    }
  }

  return orderedGroups;
};
```

Group by Custom Metadata \[#group-by-custom-metadata]

Use any custom metadata in your parts for grouping:

```tsx
import { FC, PropsWithChildren } from "react";

type MessagePartGroup = {
  groupKey: string | undefined;
  indices: number[];
};

const groupByPriority = (parts: readonly any[]) => {
  const priorityGroups = new Map<string, number[]>();

  for (let i = 0; i < parts.length; i++) {
    const part = parts[i];
    // Assume parts have a custom priority field
    const priority = part.priority || "normal";

    const indices = priorityGroups.get(priority) ?? [];
    indices.push(i);
    priorityGroups.set(priority, indices);
  }

  // Order by priority
  const priorityOrder = ["high", "normal", "low"];
  const orderedGroups: MessagePartGroup[] = [];

  for (const priority of priorityOrder) {
    const indices = priorityGroups.get(priority);
    if (indices) {
      orderedGroups.push({ groupKey: priority, indices });
    }
  }

  return orderedGroups;
};

// Render with priority indicators
const PriorityGroup: FC<
  PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>
> = ({ groupKey, indices, children }) => {
  if (!groupKey) return <>{children}</>;

  const priorityStyles = {
    high: "border-red-500 bg-red-50",
    normal: "border-gray-300 bg-white",
    low: "border-gray-200 bg-gray-50",
  };

  return (
    <div
      className={`my-2 rounded-lg border-2 p-4 ${priorityStyles[groupKey] || ""}`}
    >
      <div className="mb-2 text-xs font-semibold uppercase text-gray-600">
        {groupKey} Priority
      </div>
      {children}
    </div>
  );
};
```

Integration with Assistant Streams \[#integration-with-assistant-streams]

When using assistant-stream libraries, you can add custom metadata to parts:

Python (assistant-stream) \[#python-assistant-stream]

```python
from assistant_stream import create_run

async def my_run(controller):
    # Add parts with custom parentId
    research_controller = controller.with_parent_id("research-123")

    await research_controller.add_tool_call("search", {"query": "climate data"})
    research_controller.append_text("Key findings from the research:")

    # Add parts with custom metadata
    controller.append_part({
        "type": "text",
        "text": "High priority finding",
        "priority": "high",
        "category": "findings"
    })
```

TypeScript (assistant-stream) \[#typescript-assistant-stream]

```typescript
import { createAssistantStream } from "@assistant-ui/react/assistant-stream";

const stream = createAssistantStream(async (controller) => {
  // Add parts with parentId
  const researchController = controller.withParentId("research-123");

  await researchController.addToolCallPart({
    toolName: "search",
    args: { query: "climate data" },
  });

  // Add parts with custom metadata
  controller.appendPart({
    type: "text",
    text: "High priority finding",
    priority: "high",
    category: "findings",
  });
});
```

API Reference \[#api-reference]

MessagePrimitive.Unstable\_PartsGrouped \[#messageprimitiveunstable\_partsgrouped]

<ParametersTable
  type="MessagePrimitiveUnstable_PartsGroupedProps"
  parameters={[
{
  name: "groupingFunction",
  type: "(parts: readonly any[]) => MessagePartGroup[]",
  description:
    "Function that takes an array of message parts and returns an array of groups. Each group contains a groupKey (for identification) and an array of indices.",
  required: true,
},
{
  name: "components",
  type: "object",
  description:
    "Component configuration for rendering different types of message content and groups.",
  children: [
    {
      type: "Components",
      parameters: [
        {
          name: "Empty",
          type: "EmptyMessagePartComponent",
          description: "Component for rendering empty messages",
        },
        {
          name: "Text",
          type: "TextMessagePartComponent",
          description: "Component for rendering text content",
        },
        {
          name: "Reasoning",
          type: "ReasoningMessagePartComponent",
          description:
            "Component for rendering reasoning content (typically hidden)",
        },
        {
          name: "Source",
          type: "SourceMessagePartComponent",
          description: "Component for rendering source content",
        },
        {
          name: "Image",
          type: "ImageMessagePartComponent",
          description: "Component for rendering image content",
        },
        {
          name: "File",
          type: "FileMessagePartComponent",
          description: "Component for rendering file content",
        },
        {
          name: "Unstable_Audio",
          type: "Unstable_AudioMessagePartComponent",
          description:
            "Component for rendering audio content (experimental)",
        },
        {
          name: "tools",
          type: "object | { Override: ComponentType }",
          description:
            "Configuration for tool call rendering. Can be an object with by_name map and Fallback component, or an Override component.",
        },
        {
          name: "Group",
          type: "ComponentType<PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>>",
          description:
            "Component for rendering grouped message parts. Receives groupKey, indices array, and children to render.",
        },
      ],
    },
  ],
},
]}
/>

MessagePartGroup Type \[#messagepartgroup-type]

```typescript
type MessagePartGroup = {
  groupKey: string | undefined; // The group identifier (undefined for ungrouped parts)
  indices: number[]; // Array of part indices belonging to this group
};
```

Group Component Props \[#group-component-props]

The `Group` component receives:

* `groupKey`: The group identifier (or `undefined` for ungrouped parts)
* `indices`: Array of indices for the parts in this group
* `children`: The rendered message part components

Best Practices \[#best-practices]

1. **Keep grouping logic simple**: Complex grouping functions can impact performance
2. **Handle ungrouped parts**: Always consider parts that don't match any group criteria
3. **Maintain order**: Consider the visual flow when ordering groups
4. **Use meaningful keys**: Group keys should be descriptive for debugging
5. **Test edge cases**: Empty messages, single parts, and large numbers of parts

Common Patterns \[#common-patterns]

Conditional Grouping \[#conditional-grouping]

Only group when certain conditions are met:

```tsx
const conditionalGrouping = (parts: readonly any[]) => {
  // Only group if there are enough parts
  if (parts.length < 5) {
    return [{ groupKey: undefined, indices: parts.map((_, i) => i) }];
  }

  // Your grouping logic here
};
```

Nested Grouping \[#nested-grouping]

Create hierarchical groups:

```tsx
const nestedGrouping = (parts: readonly any[]) => {
  // First level: group by type
  // Second level: group by subtype or metadata
  // Implementation depends on your specific needs
};
```

Dynamic Group Rendering \[#dynamic-group-rendering]

Adjust group appearance based on content:

```tsx
import { FC, PropsWithChildren } from "react";
import { useAuiState } from "@assistant-ui/react";

const DynamicGroup: FC<
  PropsWithChildren<{ groupKey: string | undefined; indices: number[] }>
> = ({ groupKey, indices, children }) => {
  const parts = useAuiState((s) => s.message.content);
  const groupParts = indices.map((i) => parts[i]);

  // Analyze group content
  const hasErrors = groupParts.some((p) => p.error);
  const isLoading = groupParts.some((p) => p.status?.type === "running");

  if (!groupKey) return <>{children}</>;

  return (
    <div
      className={`my-2 rounded-lg border p-4 ${hasErrors ? "border-red-500 bg-red-50" : ""} ${isLoading ? "animate-pulse" : ""} `}
    >
      {children}
    </div>
  );
};
```


# Reasoning
URL: /docs/ui/reasoning

Collapsible UI for displaying AI reasoning and thinking messages.

import { ReasoningSample, ReasoningGroupSample } from "@/components/docs/samples/reasoning";

<ReasoningSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add reasoning \[#add-reasoning]

    <InstallCommand shadcn={["reasoning"]} />

    This adds a `/components/assistant-ui/reasoning.tsx` file to your project.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Pass the `Reasoning` and `ReasoningGroup` components to the `MessagePrimitive.Parts` component:

    ```tsx title="/app/components/assistant-ui/thread.tsx" {2,10-11}
    import { MessagePrimitive } from "@assistant-ui/react";
    import { Reasoning, ReasoningGroup } from "@/components/assistant-ui/reasoning";

    const AssistantMessage: FC = () => {
      return (
        <MessagePrimitive.Root className="...">
          <div className="...">
            <MessagePrimitive.Parts
              components={{
                Reasoning: Reasoning,
                ReasoningGroup: ReasoningGroup
              }}
            />
          </div>
          <AssistantActionBar />
          <BranchPicker className="..." />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

How It Works \[#how-it-works]

The component consists of two parts:

1. `Reasoning`: Renders individual reasoning message part content (with markdown support)
2. `ReasoningGroup`: Wraps consecutive reasoning parts in a collapsible container

Consecutive reasoning parts are automatically grouped together by the `ReasoningGroup` component.

> When using the composable API, `Reasoning.Text` is a plain container. Add `<MarkdownText />` for markdown rendering.

Variants \[#variants]

Use the `variant` prop on `Reasoning.Root` to change the visual style:

```tsx
<Reasoning.Root variant="outline">...</Reasoning.Root>
<Reasoning.Root variant="muted">...</Reasoning.Root>
```

| Variant   | Description           |
| --------- | --------------------- |
| `default` | No additional styling |
| `muted`   | Muted background      |
| `outline` | Rounded border        |

ReasoningGroup \[#reasoninggroup]

`ReasoningGroup` wraps consecutive reasoning parts in a collapsible container. It auto-expands during streaming.

<ReasoningGroupSample />

```tsx
import { ReasoningGroup } from "@/components/assistant-ui/reasoning";

const ReasoningGroupImpl: ReasoningGroupComponent = ({
  children,
  startIndex,
  endIndex,
}) => {
  const isReasoningStreaming = useAuiState((s) => {
    if (s.message.status?.type !== "running") return false;
    const lastIndex = s.message.parts.length - 1;
    if (lastIndex < 0) return false;
    const lastType = s.message.parts[lastIndex]?.type;
    if (lastType !== "reasoning") return false;
    return lastIndex >= startIndex && lastIndex <= endIndex;
  });

  return (
    <ReasoningRoot defaultOpen={isReasoningStreaming}>
      <ReasoningTrigger active={isReasoningStreaming} />
      <ReasoningContent aria-busy={isReasoningStreaming}>
        <ReasoningText>{children}</ReasoningText>
      </ReasoningContent>
    </ReasoningRoot>
  );
};
```

API Reference \[#api-reference]

Composable API \[#composable-api]

All sub-components are exported for custom layouts:

| Component           | Description                            |
| ------------------- | -------------------------------------- |
| `Reasoning.Root`    | Collapsible container with scroll lock |
| `Reasoning.Trigger` | Button with icon, label, and shimmer   |
| `Reasoning.Content` | Animated collapsible content wrapper   |
| `Reasoning.Text`    | Text wrapper with slide/fade animation |
| `Reasoning.Fade`    | Gradient fade overlay at bottom        |

```tsx
import {
  Reasoning,
  ReasoningRoot,
  ReasoningTrigger,
  ReasoningContent,
  ReasoningText,
  ReasoningFade,
} from "@/components/assistant-ui/reasoning";

// Compound component syntax
<Reasoning.Root variant="muted">
  <Reasoning.Trigger active={isStreaming} />
  <Reasoning.Content>
    <Reasoning.Text>{children}</Reasoning.Text>
  </Reasoning.Content>
</Reasoning.Root>
```

Related Components \[#related-components]

* [ToolGroup](/docs/ui/tool-group) - Similar grouping pattern for tool calls
* [PartGrouping](/docs/ui/part-grouping) - Experimental API for grouping message parts


# Custom Scrollbar
URL: /docs/ui/scrollbar

Replace the default scrollbar with a custom Radix UI scroll area.

import { ScrollbarSample } from "@/components/docs/samples/scrollbar";

<ScrollbarSample />

If you want to show a custom scrollbar UI of the `ThreadPrimitive.Viewport` in place of the system default, you can integrate `radix-ui`'s Scroll Area.
An example implementation of this is [shadcn/ui's Scroll Area](https://ui.shadcn.com/docs/components/scroll-area).

<Steps>
  <Step>
    Add shadcn Scroll Area \[#add-shadcn-scroll-area]

    ```bash
    npx shadcn@latest add scroll-area
    ```
  </Step>

  <Step>
    Add Additional Styles \[#add-additional-styles]

    The Radix UI Viewport component adds an intermediate `<div data-radix-scroll-area-content>` element.
    Add the following CSS to your `globals.css`:

    ```css title="@/app/globals.css"
    .thread-viewport > [data-radix-scroll-area-content] {
      @apply flex flex-col items-center self-stretch bg-inherit;
    }
    ```
  </Step>

  <Step>
    Integrate with Thread \[#integrate-with-thread]

    * Wrap `ThreadPrimitive.Root` with `<ScrollAreaPrimitive.Root asChild>`
    * Wrap `ThreadPrimitive.Viewport` with `<ScrollAreaPrimitive.Viewport className="thread-viewport" asChild>`
    * Add shadcn's `<ScrollBar />` to `ThreadPrimitive.Root`

    The resulting MyThread component should look like this:

    ```tsx {1-2,6,8,12-13,15}
    import { ScrollArea as ScrollAreaPrimitive } from "radix-ui";
    import { ScrollBar } from "@/components/ui/scroll-area";

    const MyThread: FC = () => {
      return (
        <ScrollAreaPrimitive.Root asChild>
          <ThreadPrimitive.Root className="...">
            <ScrollAreaPrimitive.Viewport className="thread-viewport" asChild>
              <ThreadPrimitive.Viewport className="...">
                ...
              </ThreadPrimitive.Viewport>
            </ScrollAreaPrimitive.Viewport>
            <ScrollBar />
          </ThreadPrimitive.Root>
        </ScrollAreaPrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Related Components \[#related-components]

* [Thread](/docs/ui/thread) - The main chat interface where the scrollbar is used


# Select
URL: /docs/ui/select

A dropdown select component with composable sub-components.

import { PreviewCode } from "@/components/docs/preview-code.server";
import {
  SelectSample,
  SelectDisabledItemsSample,
  SelectPlaceholderSample,
  SelectDisabledSample,
  SelectGroupsSample,
  SelectVariantsSample,
  SelectSizesSample,
  SelectScrollableSample,
} from "@/components/docs/samples/select";

<Callout>
  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
</Callout>

<SelectSample />

Installation \[#installation]

<InstallCommand shadcn={["select"]} />

Usage \[#usage]

```tsx
import { Select } from "@/components/assistant-ui/select";

const options = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
];

export function FruitPicker() {
  const [value, setValue] = useState("apple");

  return (
    <Select
      value={value}
      onValueChange={setValue}
      options={options}
      placeholder="Select a fruit..."
    />
  );
}
```

Examples \[#examples]

Variants \[#variants]

Use the `variant` prop on `SelectTrigger` to change the visual style.

<SelectVariantsSample />

```tsx
<SelectTrigger variant="outline" /> // Border (default)
<SelectTrigger variant="ghost" />   // No border
<SelectTrigger variant="muted" />   // Solid background
```

Sizes \[#sizes]

Use the `size` prop on `SelectTrigger` to change the height.

<SelectSizesSample />

```tsx
<SelectTrigger size="default" /> // 36px (default)
<SelectTrigger size="sm" />      // 32px
```

Scrollable \[#scrollable]

Long lists automatically become scrollable.

<PreviewCode file="components/docs/samples/select" name="SelectScrollableSample">
  <SelectScrollableSample />
</PreviewCode>

Groups \[#groups]

Use the composable API for grouped options:

<PreviewCode file="components/docs/samples/select" name="SelectGroupsSample">
  <SelectGroupsSample />
</PreviewCode>

Disabled Items \[#disabled-items]

<PreviewCode file="components/docs/samples/select" name="SelectDisabledItemsSample">
  <SelectDisabledItemsSample />
</PreviewCode>

With Placeholder \[#with-placeholder]

<PreviewCode file="components/docs/samples/select" name="SelectPlaceholderSample">
  <SelectPlaceholderSample />
</PreviewCode>

Disabled Select \[#disabled-select]

<PreviewCode file="components/docs/samples/select" name="SelectDisabledSample">
  <SelectDisabledSample />
</PreviewCode>

API Reference \[#api-reference]

Composable API \[#composable-api]

| Component                | Description                                                             |
| ------------------------ | ----------------------------------------------------------------------- |
| `Select`                 | A convenience component that renders a complete select with options.    |
| `SelectRoot`             | The root component that manages state.                                  |
| `SelectTrigger`          | The button that opens the dropdown. Accepts `variant` and `size` props. |
| `SelectValue`            | Renders the selected value or placeholder.                              |
| `SelectContent`          | The dropdown content container with animations.                         |
| `SelectItem`             | An individual selectable item.                                          |
| `SelectGroup`            | Groups related items together.                                          |
| `SelectLabel`            | A label for a group of items.                                           |
| `SelectSeparator`        | A visual separator between items or groups.                             |
| `SelectScrollUpButton`   | Scroll indicator for long lists.                                        |
| `SelectScrollDownButton` | Scroll indicator for long lists.                                        |

Select \[#select]

A convenience component that renders a complete select with options.

<ParametersTable
  type="SelectProps"
  parameters={[
{
  name: "value",
  type: "string",
  required: true,
  description: "The controlled value of the select.",
},
{
  name: "onValueChange",
  type: "(value: string) => void",
  required: true,
  description: "Callback when the selected value changes.",
},
{
  name: "options",
  type: "SelectOption[]",
  required: true,
  description: "Array of options to display.",
},
{
  name: "placeholder",
  type: "string",
  description: "Placeholder text when no value is selected.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes for the trigger.",
},
{
  name: "disabled",
  type: "boolean",
  description: "Whether the select is disabled.",
},
]}
/>

SelectOption \[#selectoption]

<ParametersTable
  type="SelectOption"
  parameters={[
{
  name: "value",
  type: "string",
  required: true,
  description: "The value of the option.",
},
{
  name: "label",
  type: "ReactNode",
  required: true,
  description: "The display label for the option.",
},
{
  name: "textValue",
  type: "string",
  description: "Optional text value for typeahead. Defaults to label if it's a string.",
},
{
  name: "disabled",
  type: "boolean",
  description: "Whether the option is disabled.",
},
]}
/>

SelectTrigger \[#selecttrigger]

The button that opens the dropdown.

<ParametersTable
  type="SelectTriggerProps"
  parameters={[
{
  name: "variant",
  type: '"outline" | "ghost" | "muted"',
  default: '"outline"',
  description: "The visual style of the trigger.",
},
{
  name: "size",
  type: '"sm" | "default" | "lg"',
  default: '"default"',
  description: "The size of the trigger.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

Style Variants (CVA) \[#style-variants-cva]

| Export                  | Description                           |
| ----------------------- | ------------------------------------- |
| `selectTriggerVariants` | Styles for the select trigger button. |

```tsx
import { selectTriggerVariants } from "@/components/assistant-ui/select";

<button className={selectTriggerVariants({ variant: "ghost", size: "sm" })}>
  Custom Trigger
</button>
```


# Sources
URL: /docs/ui/sources

Display URL sources with favicon, title, and external link.

import { SourcesSample } from "@/components/docs/samples/sources";

<SourcesSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add sources \[#add-sources]

    <InstallCommand shadcn={["sources"]} />
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    Pass `Sources` to `MessagePrimitive.Parts`:

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    import { Sources } from "@/components/assistant-ui/sources";

    const AssistantMessage: FC = () => {
      return (
        <MessagePrimitive.Root className="...">
          <MessagePrimitive.Parts
            components={{
              Source: Sources,
            }}
          />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Variants \[#variants]

Use the `variant` prop to change the visual style.

```tsx
<Source variant="outline" /> // Border (default)
<Source variant="ghost" />   // No background
<Source variant="muted" />   // Solid background
```

Sizes \[#sizes]

Use the `size` prop to change the size.

```tsx
<Source size="sm" />      // Small
<Source size="default" /> // Default
<Source size="lg" />      // Large
```

API Reference \[#api-reference]

Composable API \[#composable-api]

The component exports composable sub-components:

```tsx
import { Source, SourceIcon, SourceTitle } from "@/components/assistant-ui/sources";

<Source href="https://example.com" className="gap-2">
  <SourceIcon url="https://example.com" className="size-4" />
  <SourceTitle className="max-w-none font-medium">Example</SourceTitle>
</Source>
```

| Component     | Description                          |
| ------------- | ------------------------------------ |
| `Source`      | Root container, renders as `<a>`     |
| `SourceIcon`  | Favicon with domain initial fallback |
| `SourceTitle` | Truncated title text                 |

Related Components \[#related-components]

* [PartGrouping](/docs/ui/part-grouping) - Group sources by parentId


# Streamdown
URL: /docs/ui/streamdown

Alternative markdown renderer with built-in syntax highlighting, math, and diagram support.

import { PackageManagerTabs } from "@/components/docs/fumadocs/install/package-manager-tabs";
import { StreamdownSample } from "@/components/docs/samples/streamdown";

<StreamdownSample />

<Callout type="info">
  `@assistant-ui/react-streamdown` is an **alternative** to `@assistant-ui/react-markdown`. Choose based on your needs:

  * **react-markdown**: Lightweight, bring-your-own syntax highlighter
  * **react-streamdown**: Feature-rich with built-in Shiki, KaTeX, Mermaid support
</Callout>

Installation \[#installation]

<PackageManagerTabs packages={["@assistant-ui/react-streamdown", "streamdown"]} />

For additional features, install the optional plugins:

<PackageManagerTabs packages={["@streamdown/code", "@streamdown/math", "@streamdown/mermaid", "@streamdown/cjk"]} />

Basic Usage \[#basic-usage]

```tsx
import { StreamdownTextPrimitive } from "@assistant-ui/react-streamdown";

// Inside a MessagePrimitive.Parts component
<MessagePrimitive.Parts components={{ Text: StreamdownText }} />

// Where StreamdownText is:
const StreamdownText = () => <StreamdownTextPrimitive />;
```

With Plugins (Recommended) \[#with-plugins-recommended]

```tsx
import { StreamdownTextPrimitive } from "@assistant-ui/react-streamdown";
import { code } from "@streamdown/code";
import { math } from "@streamdown/math";
import { mermaid } from "@streamdown/mermaid";
import "katex/dist/katex.min.css";

const StreamdownText = () => (
  <StreamdownTextPrimitive
    plugins={{ code, math, mermaid }}
    shikiTheme={["github-light", "github-dark"]}
  />
);
```

When `@streamdown/code` is provided, the default theme is `["github-light", "github-dark"]` for light/dark mode support.

Migration from react-markdown \[#migration-from-react-markdown]

If you're migrating from `@assistant-ui/react-markdown`, your existing `SyntaxHighlighter` and `CodeHeader` components still work:

```tsx
import { StreamdownTextPrimitive } from "@assistant-ui/react-streamdown";

const StreamdownText = () => (
  <StreamdownTextPrimitive
    components={{
      SyntaxHighlighter: MySyntaxHighlighter,
      CodeHeader: MyCodeHeader,
    }}
    componentsByLanguage={{
      mermaid: { SyntaxHighlighter: MermaidRenderer }
    }}
  />
);
```

Props \[#props]

| Prop                        | Type                       | Default                           | Description                                                      |
| --------------------------- | -------------------------- | --------------------------------- | ---------------------------------------------------------------- |
| `mode`                      | `"streaming" \| "static"`  | `"streaming"`                     | Rendering mode                                                   |
| `plugins`                   | `PluginConfig`             | -                                 | Streamdown plugins (code, math, mermaid, cjk)                    |
| `shikiTheme`                | `[string, string]`         | `["github-light", "github-dark"]` | Light and dark theme for Shiki                                   |
| `components`                | `object`                   | -                                 | Custom components including `SyntaxHighlighter` and `CodeHeader` |
| `componentsByLanguage`      | `object`                   | -                                 | Language-specific component overrides                            |
| `preprocess`                | `(text: string) => string` | -                                 | Text preprocessing function                                      |
| `controls`                  | `boolean \| object`        | `true`                            | Enable/disable UI controls for code blocks and tables            |
| `caret`                     | `"block" \| "circle"`      | -                                 | Streaming caret style                                            |
| `mermaid`                   | `MermaidOptions`           | -                                 | Mermaid diagram configuration                                    |
| `linkSafety`                | `LinkSafetyConfig`         | -                                 | Link safety confirmation dialog                                  |
| `remend`                    | `RemendConfig`             | -                                 | Incomplete markdown auto-completion                              |
| `allowedTags`               | `Record<string, string[]>` | -                                 | HTML tags whitelist                                              |
| `containerProps`            | `object`                   | -                                 | Props for the container div                                      |
| `containerClassName`        | `string`                   | -                                 | Class name for the container                                     |
| `remarkRehypeOptions`       | `object`                   | -                                 | Options passed to remark-rehype                                  |
| `BlockComponent`            | `ComponentType`            | -                                 | Custom component for rendering blocks                            |
| `parseMarkdownIntoBlocksFn` | `(md: string) => string[]` | -                                 | Custom block parsing function                                    |
| `parseIncompleteMarkdown`   | `boolean`                  | `false`                           | Parse incomplete markdown as-is (skip remend)                    |
| `security`                  | `SecurityConfig`           | -                                 | URL/image security restrictions                                  |

Plugin Configuration \[#plugin-configuration]

Code Highlighting \[#code-highlighting]

```tsx
import { code } from "@streamdown/code";

<StreamdownTextPrimitive
  plugins={{ code }}
  shikiTheme={["github-light", "github-dark"]}
/>
```

Math (LaTeX) \[#math-latex]

```tsx
import { math } from "@streamdown/math";
import "katex/dist/katex.min.css";

<StreamdownTextPrimitive plugins={{ math }} />
```

Mermaid Diagrams \[#mermaid-diagrams]

```tsx
import { mermaid } from "@streamdown/mermaid";

<StreamdownTextPrimitive plugins={{ mermaid }} />
```

CJK Text Optimization \[#cjk-text-optimization]

```tsx
import { cjk } from "@streamdown/cjk";

<StreamdownTextPrimitive plugins={{ cjk }} />
```

Advanced Configuration \[#advanced-configuration]

Mermaid Options \[#mermaid-options]

Customize Mermaid diagram rendering with configuration and error handling:

```tsx
import { mermaid } from "@streamdown/mermaid";

<StreamdownTextPrimitive
  plugins={{ mermaid }}
  mermaid={{
    config: { theme: "dark" },
    errorComponent: ({ error, chart, retry }) => (
      <div>
        <p>Failed to render diagram: {error}</p>
        <button onClick={retry}>Retry</button>
      </div>
    ),
  }}
/>
```

Streaming Caret \[#streaming-caret]

Display a caret indicator during streaming:

```tsx
<StreamdownTextPrimitive caret="block" />  // ▋
<StreamdownTextPrimitive caret="circle" /> // ●
```

Link Safety \[#link-safety]

Show confirmation before opening external links:

```tsx
<StreamdownTextPrimitive
  linkSafety={{
    enabled: true,
    onLinkCheck: (url) => url.startsWith("https://trusted.com"),
  }}
/>
```

Incomplete Markdown Handling (Remend) \[#incomplete-markdown-handling-remend]

Configure how incomplete markdown syntax is handled during streaming:

```tsx
<StreamdownTextPrimitive
  remend={{
    links: true,      // Complete incomplete links
    images: true,     // Handle incomplete images
    bold: true,       // Complete **text → **text**
    italic: true,     // Complete *text → *text*
    inlineCode: true, // Complete `code → `code`
    katex: true,      // Complete $$equation → $$equation$$
  }}
/>
```

Allowed HTML Tags \[#allowed-html-tags]

Allow specific HTML tags in markdown content:

```tsx
<StreamdownTextPrimitive
  allowedTags={{
    div: ["class", "id"],
    span: ["class", "style"],
    iframe: ["src", "width", "height"],
  }}
/>
```

Security Configuration \[#security-configuration]

Restrict allowed URLs for links and images. This overrides streamdown's default allow-all policy:

```tsx
<StreamdownTextPrimitive
  security={{
    // Only allow links to trusted domains
    allowedLinkPrefixes: ["https://example.com", "https://docs.example.com"],
    // Only allow images from your CDN
    allowedImagePrefixes: ["https://cdn.example.com"],
    // Restrict protocols
    allowedProtocols: ["https", "mailto"],
    // Disable base64 data images
    allowDataImages: false,
    // CSS class for blocked elements
    blockedLinkClass: "blocked-link",
    blockedImageClass: "blocked-image",
  }}
/>
```

Detecting Inline vs Block Code \[#detecting-inline-vs-block-code]

When building custom code components, you can use `useIsStreamdownCodeBlock` to detect whether you're inside a code block or inline code:

```tsx
import { useIsStreamdownCodeBlock } from "@assistant-ui/react-streamdown";

function MyCodeComponent({ children, ...props }) {
  const isCodeBlock = useIsStreamdownCodeBlock();

  if (!isCodeBlock) {
    return <code className="inline-code" {...props}>{children}</code>;
  }

  return <pre><code {...props}>{children}</code></pre>;
}
```

You can also use `useStreamdownPreProps` to access the props passed to the parent `<pre>` element:

```tsx
import { useStreamdownPreProps } from "@assistant-ui/react-streamdown";

function MyCodeComponent({ children }) {
  const preProps = useStreamdownPreProps();

  if (!preProps) {
    // Inline code
    return <code>{children}</code>;
  }

  // Block code - preProps contains className, node, etc.
  return <code className={preProps.className}>{children}</code>;
}
```

Comparison with react-markdown \[#comparison-with-react-markdown]

| Feature             | react-markdown | react-streamdown      |
| ------------------- | -------------- | --------------------- |
| Bundle size         | Smaller        | Larger (with plugins) |
| Syntax highlighting | Bring your own | Built-in Shiki        |
| Math rendering      | Manual setup   | Built-in KaTeX        |
| Mermaid diagrams    | Manual setup   | Built-in support      |
| CJK optimization    | None           | Built-in              |
| Streaming           | `smooth` prop  | `mode` + block-based  |

Re-exported Utilities \[#re-exported-utilities]

The package re-exports useful utilities:

```tsx
import {
  // Context for accessing streamdown state
  StreamdownContext,
  // Parse markdown into blocks (for custom implementations)
  parseMarkdownIntoBlocks,
  // Hooks for custom code components
  useIsStreamdownCodeBlock,
  useStreamdownPreProps,
  // Memo comparison utility for custom components
  memoCompareNodes,
  // Default Shiki theme: ["github-light", "github-dark"]
  DEFAULT_SHIKI_THEME,
} from "@assistant-ui/react-streamdown";
```

Available Types \[#available-types]

```tsx
import type {
  // Component props
  StreamdownTextPrimitiveProps,
  SyntaxHighlighterProps,
  CodeHeaderProps,
  ComponentsByLanguage,
  StreamdownTextComponents,
  StreamdownProps,
  // Plugin types
  PluginConfig,
  ResolvedPluginConfig,
  CodeHighlighterPlugin,
  DiagramPlugin,
  MathPlugin,
  CjkPlugin,
  HighlightOptions,
  // Shiki types
  BundledTheme,
  BundledLanguage,
  // Configuration types
  CaretStyle,
  ControlsConfig,
  MermaidOptions,
  MermaidErrorComponentProps,
  LinkSafetyConfig,
  LinkSafetyModalProps,
  RemendConfig,
  RemendHandler,
  AllowedTags,
  RemarkRehypeOptions,
  BlockProps,
  SecurityConfig,
} from "@assistant-ui/react-streamdown";
```

Related Components \[#related-components]

* [Markdown](/docs/ui/markdown) - Lightweight markdown with react-markdown
* [Syntax Highlighting](/docs/ui/syntax-highlighting) - Add code highlighting to react-markdown
* [Mermaid](/docs/ui/mermaid) - Render diagrams in react-markdown


# Syntax Highlighting
URL: /docs/ui/syntax-highlighting

Code block syntax highlighting with react-shiki or react-syntax-highlighter.

import { SyntaxHighlightingSample } from "@/components/docs/samples/syntax-highlighting";

<Callout type="warn">
  Syntax highlighting is not enabled in markdown by default.
</Callout>

<SyntaxHighlightingSample />

<Callout type="info">
  `assistant-ui` provides two options for syntax highlighting:

  * **react-shiki** (recommended for performance & dynamic language support)
  * **react-syntax-highlighter** (legacy - Prism or Highlight.js based)
</Callout>

***

react-shiki \[#react-shiki]

<Steps>
  <Step>
    Add shiki-highlighter \[#add-shiki-highlighter]

    <InstallCommand shadcn={["shiki-highlighter"]} />

    This adds a `/components/assistant-ui/shiki-highlighter.tsx` file to your project and
    installs the `react-shiki` dependency. The highlighter can be customized by editing
    the config in the `shiki-highlighter.tsx` file.
  </Step>

  <Step>
    Add it to defaultComponents in markdown-text.tsx \[#add-it-to-defaultcomponents-in-markdown-texttsx]

    ```tsx title="/components/assistant-ui/markdown-text.tsx"
    import { SyntaxHighlighter } from "./shiki-highlighter";

    export const defaultComponents = memoizeMarkdownComponents({
      SyntaxHighlighter: SyntaxHighlighter, // [!code ++]
      h1: /* ... */,
      // ...other elements...
    });
    ```
  </Step>
</Steps>

Options \[#options]

See [react-shiki documentation](https://github.com/AVGVSTVS96/react-shiki#props) for all available options.

Key options:

* `theme` - Shiki theme or multi-theme object (`{ light, dark, ... }`)
* `language` - Language for highlighting (default: `"text"`)
* `defaultColor` - Default color mode (`string | false`, e.g. `light-dark()`)
* `delay` - Delay between highlights, useful for streaming (default: `0`)
* `customLanguages` - Custom languages to preload for dynamic support
* `codeToHastOptions` - All other options accepted by Shiki's [`codeToHast`](https://github.com/shikijs/shiki/blob/main/packages/types/src/options.ts#L121)

Dual/multi theme support \[#dualmulti-theme-support]

To use multiple themes, pass a theme object:

```tsx title="/components/assistant-ui/shiki-highlighter.tsx"
<ShikiHighlighter
  /* ... */
  theme={{
    light: "github-light",
    dark: "github-dark",
  }}
  defaultColor="light-dark()"
  /* ... */
>
```

> **Note:** The `shiki-highlighter` component sets `defaultColor="light-dark()"` automatically.
> Only set this manually if using `ShikiHighlighter` directly.

With `defaultColor="light-dark()"`, theme switching is automatic based on your site's `color-scheme`.
No custom Shiki CSS overrides are required.

Set `color-scheme` on your app root:

System-based (follows OS/browser preference):

```css title="globals.css"
:root {
  color-scheme: light dark;
}
```

Class-based theme switching:

```css title="globals.css"
:root {
  color-scheme: light;
}
:root.dark {
  color-scheme: dark;
}
```

If you need broader support for older browsers, you can still use the manual CSS-variable switching approach from the Shiki dual-theme docs.

For more information:

* [react-shiki multi-theme/reactive themes](https://github.com/AVGVSTVS96/react-shiki)
* [Shiki dual themes + `light-dark()`](https://shiki.style/guide/dual-themes)

Bundle Optimization \[#bundle-optimization]

By default, `react-shiki` includes the full Shiki bundle, which contains all supported languages and themes.

To reduce bundle size, you can use the web bundle by changing the import to `react-shiki/web`, to include a smaller bundle of web related languages:

```tsx title="/components/assistant-ui/shiki-highlighter.tsx"
import ShikiHighlighter, { type ShikiHighlighterProps } from "react-shiki/web";
```

Custom Bundles \[#custom-bundles]

For strict bundle size control, `react-shiki` also supports custom bundles created using `createHighlighterCore` from `react-shiki/core` (re-exported from Shiki):

```tsx title="/components/assistant-ui/shiki-highlighter.tsx" {3-9}
import { createHighlighterCore, createOnigurumaEngine } from "react-shiki/core"; // [!code ++]

// Create the highlighter
// Use dynamic imports to load languages and themes on client on demand
const customHighlighter = await createHighlighterCore({
  themes: [import("@shikijs/themes/nord")],
  langs: [
    import("@shikijs/langs/javascript"),
    import("@shikijs/langs/typescript"),
  ],
  engine: createOnigurumaEngine(import("shiki/wasm")), 
});

// Then pass it to the highlighter prop
<SyntaxHighlighter
  {...props}
  language={language}
  theme={theme}
  highlighter={customHighlighter} // [!code ++]
/>;
```

<Callout type="info">
  For more information, see [react-shiki - bundle options](https://github.com/avgvstvs96/react-shiki#bundle-options).
</Callout>

***

react-syntax-highlighter \[#react-syntax-highlighter]

<Callout type="warn">
  This option may be removed in a future release. Consider using
  [react-shiki](#react-shiki) instead.
</Callout>

<Steps>
  <Step>
    Add syntax-highlighter \[#add-syntax-highlighter]

    <InstallCommand shadcn={["syntax-highlighter"]} />

    Adds a `/components/assistant-ui/syntax-highlighter.tsx` file to your project and installs the `react-syntax-highlighter` dependency.
  </Step>

  <Step>
    Add it to defaultComponents in markdown-text.tsx \[#add-it-to-defaultcomponents-in-markdown-texttsx-1]

    ```tsx title="/components/assistant-ui/markdown-text.tsx"
    import { SyntaxHighlighter } from "./syntax-highlighter";

    export const defaultComponents = memoizeMarkdownComponents({
      SyntaxHighlighter: SyntaxHighlighter, // [!code ++]
      h1: /* ... */,
      // ...other elements...
    });
    ```
  </Step>
</Steps>

Options \[#options-1]

Supports all options from [`react-syntax-highlighter`](https://github.com/react-syntax-highlighter/react-syntax-highlighter#props).

Bundle Optimization \[#bundle-optimization-1]

By default, the syntax highlighter uses a light build that only includes languages you register. To include all languages:

```tsx title="/components/assistant-ui/syntax-highlighter.tsx"
import { makePrismAsyncSyntaxHighlighter } from "@assistant-ui/react-syntax-highlighter/full";
```

Related Components \[#related-components]

* [Markdown](/docs/ui/markdown) - Rich text rendering that uses syntax highlighting
* [Mermaid](/docs/ui/mermaid) - Render diagrams instead of code blocks


# Tabs
URL: /docs/ui/tabs

A multi-variant tabs component for organizing content into switchable panels.

import { PreviewCode } from "@/components/docs/preview-code.server";
import {
  TabsSample,
  TabsVariantsSample,
  TabsSizesSample,
  TabsWithIconsSample,
  TabsControlledSample,
  TabsAsLinkSample,
  TabsAnimatedIndicatorSample,
} from "@/components/docs/samples/tabs";

<Callout>
  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
</Callout>

<TabsSample />

Installation \[#installation]

<InstallCommand shadcn={["tabs"]} />

Usage \[#usage]

```tsx
import {
  Tabs,
  TabsList,
  TabsTrigger,
  TabsContent,
} from "@/components/assistant-ui/tabs";

export function Example() {
  return (
    <Tabs defaultValue="account">
      <TabsList>
        <TabsTrigger value="account">Account</TabsTrigger>
        <TabsTrigger value="password">Password</TabsTrigger>
      </TabsList>
      <TabsContent value="account">Account settings here.</TabsContent>
      <TabsContent value="password">Password settings here.</TabsContent>
    </Tabs>
  );
}
```

Examples \[#examples]

Variants \[#variants]

Use the `variant` prop on `TabsList` to change the visual style. Child components inherit the variant automatically.

<TabsVariantsSample />

```tsx
<TabsList variant="default" />  // Muted background with shadow (default)
<TabsList variant="line" />     // Underline indicator
<TabsList variant="ghost" />    // Transparent with hover states
<TabsList variant="pills" />    // Rounded pill buttons
<TabsList variant="outline" />  // Border with background on active
```

Sizes \[#sizes]

Use the `size` prop on `TabsList` to change the tab height. Child components inherit the size automatically.

<TabsSizesSample />

```tsx
<TabsList size="sm" />      // 32px height
<TabsList size="default" /> // 36px height
<TabsList size="lg" />      // 40px height
```

With Icons \[#with-icons]

Tabs automatically style SVG icons placed inside triggers.

<PreviewCode file="components/docs/samples/tabs" name="TabsWithIconsSample">
  <TabsWithIconsSample />
</PreviewCode>

Controlled \[#controlled]

Use `value` and `onValueChange` for controlled tab state.

<PreviewCode file="components/docs/samples/tabs" name="TabsControlledSample">
  <TabsControlledSample />
</PreviewCode>

As Link \[#as-link]

Use the `asChild` prop on `TabsTrigger` to render as a different element, like a navigation link.

<PreviewCode file="components/docs/samples/tabs" name="TabsAsLinkSample">
  <TabsAsLinkSample />
</PreviewCode>

Animated Indicator \[#animated-indicator]

All variants feature smooth animated indicators that slide between tabs:

| Variant   | Indicator Style                      |
| --------- | ------------------------------------ |
| `default` | Sliding background with shadow       |
| `line`    | Sliding underline                    |
| `ghost`   | Sliding background with hover effect |
| `pills`   | Sliding pill background              |
| `outline` | Sliding border                       |

<PreviewCode file="components/docs/samples/tabs" name="TabsAnimatedIndicatorSample">
  <TabsAnimatedIndicatorSample />
</PreviewCode>

API Reference \[#api-reference]

Composable API \[#composable-api]

| Component     | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `Tabs`        | The root component that manages tab state.                     |
| `TabsList`    | The container for tab triggers. Set `variant` and `size` here. |
| `TabsTrigger` | An individual tab button. Inherits variant/size from TabsList. |
| `TabsContent` | The content panel for a tab.                                   |

Tabs \[#tabs]

The root component that manages tab state.

<ParametersTable
  type="TabsProps"
  parameters={[
{
  name: "defaultValue",
  type: "string",
  description: "The default active tab value (uncontrolled).",
},
{
  name: "value",
  type: "string",
  description: "The controlled active tab value.",
},
{
  name: "onValueChange",
  type: "(value: string) => void",
  description: "Callback when the active tab changes.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

TabsList \[#tabslist]

The container for tab triggers. Set `variant` and `size` here to style all child components.

<ParametersTable
  type="TabsListProps"
  parameters={[
{
  name: "variant",
  type: '"default" | "line" | "ghost" | "pills" | "outline"',
  default: '"default"',
  description: "The visual style of the tabs. Child components inherit this automatically.",
},
{
  name: "size",
  type: '"sm" | "default" | "lg"',
  default: '"default"',
  description: "The size of the tabs. Child components inherit this automatically.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

TabsTrigger \[#tabstrigger]

An individual tab button.

<ParametersTable
  type="TabsTriggerProps"
  parameters={[
{
  name: "value",
  type: "string",
  required: true,
  description: "The unique value for this tab.",
},
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a button.",
},
{
  name: "disabled",
  type: "boolean",
  description: "Whether the tab is disabled.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

TabsContent \[#tabscontent]

The content panel for a tab.

<ParametersTable
  type="TabsContentProps"
  parameters={[
{
  name: "value",
  type: "string",
  required: true,
  description: "The value matching the corresponding TabsTrigger.",
},
{
  name: "className",
  type: "string",
  description: "Additional CSS classes.",
},
]}
/>

Style Variants (CVA) \[#style-variants-cva]

| Export                        | Description                               |
| ----------------------------- | ----------------------------------------- |
| `tabsListVariants`            | Styles for the tabs list container.       |
| `tabsActiveIndicatorVariants` | Styles for the animated active indicator. |

```tsx
import {
  tabsListVariants,
  tabsActiveIndicatorVariants,
} from "@/components/assistant-ui/tabs";

<div className={tabsListVariants({ variant: "ghost", size: "sm" })}>
  Custom Tabs Container
</div>
```


# ThreadList
URL: /docs/ui/thread-list

Switch between conversations. Supports sidebar or dropdown layouts.

import { ThreadListSample } from "@/components/docs/samples/threadlist";

<ThreadListSample />

<Callout>
  This demo uses `ThreadListSidebar`, which includes `thread-list` as a dependency and provides a complete sidebar layout. For custom implementations, you can use `thread-list` directly.
</Callout>

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add the component \[#add-the-component]

    Use `threadlist-sidebar` for a complete sidebar layout or `thread-list` for custom layouts.

    ThreadListSidebar \[#threadlistsidebar]

    <InstallCommand shadcn={["threadlist-sidebar"]} />

    ThreadList \[#threadlist]

    <InstallCommand shadcn={["thread-list"]} />
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    <Tabs items={["With Sidebar", "Without Sidebar"]}>
      <Tab value="With Sidebar">
        ```tsx title="/app/assistant.tsx"
        import { Thread } from "@/components/assistant-ui/thread";
        import { ThreadListSidebar } from "@/components/assistant-ui/threadlist-sidebar";
        import {
          SidebarProvider,
          SidebarInset,
          SidebarTrigger
        } from "@/components/ui/sidebar";

        export default function Assistant() {
          return (
            <SidebarProvider>
              <div className="flex h-dvh w-full">
                <ThreadListSidebar />
                <SidebarInset>
                  {/* Add sidebar trigger, location can be customized */}
                  <SidebarTrigger className="absolute top-4 left-4" />
                  <Thread />
                </SidebarInset>
              </div>
            </SidebarProvider>
          );
        }
        ```
      </Tab>

      <Tab value="Without Sidebar">
        ```tsx title="/app/assistant.tsx"
        import { Thread } from "@/components/assistant-ui/thread";
        import { ThreadList } from "@/components/assistant-ui/thread-list";

        export default function Assistant() {
          return (
            <div className="grid h-full grid-cols-[200px_1fr]">
              <ThreadList />
              <Thread />
            </div>
          );
        }
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

Anatomy \[#anatomy]

The `ThreadList` component is built with the following primitives:

```tsx
import { ThreadListPrimitive, ThreadListItemPrimitive } from "@assistant-ui/react";

<ThreadListPrimitive.Root>
  <ThreadListPrimitive.New />
  <ThreadListPrimitive.Items
    components={{
      ThreadListItem: () => (
        <ThreadListItemPrimitive.Root>
          <ThreadListItemPrimitive.Trigger>
            <ThreadListItemPrimitive.Title />
          </ThreadListItemPrimitive.Trigger>
          <ThreadListItemPrimitive.Archive />
          <ThreadListItemPrimitive.Delete />
        </ThreadListItemPrimitive.Root>
      ),
    }}
  />
</ThreadListPrimitive.Root>
```

API Reference \[#api-reference]

ThreadListPrimitive.Root \[#threadlistprimitiveroot]

Container for the thread list.

<ParametersTable
  type="ThreadListPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

ThreadListPrimitive.Items \[#threadlistprimitiveitems]

Renders all threads in the list.

<ParametersTable
  type="ThreadListPrimitiveItemsProps"
  parameters={[
{
  name: "archived",
  type: "boolean",
  description: "When true, renders archived threads instead of active threads.",
},
{
  name: "components",
  type: "object",
  required: true,
  description: "Component configuration.",
  children: [
    {
      type: "Components",
      parameters: [
        {
          name: "ThreadListItem",
          type: "ComponentType",
          required: true,
          description: "Component to render for each thread item.",
        },
      ],
    },
  ],
},
]}
/>

ThreadListPrimitive.New \[#threadlistprimitivenew]

A button to create a new thread.

<ParametersTable
  type="ThreadListPrimitiveNewProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

ThreadListItemPrimitive.Root \[#threadlistitemprimitiveroot]

Container for a single thread item. Automatically sets `data-active` and `aria-current` when this is the current thread.

<ParametersTable
  type="ThreadListItemPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

ThreadListItemPrimitive.Trigger \[#threadlistitemprimitivetrigger]

A button that switches to this thread when clicked.

<ParametersTable
  type="ThreadListItemPrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

ThreadListItemPrimitive.Title \[#threadlistitemprimitivetitle]

Renders the thread's title.

<ParametersTable
  type="ThreadListItemPrimitiveTitleProps"
  parameters={[
{
  name: "fallback",
  type: "ReactNode",
  description: "Content to display when the thread has no title.",
},
]}
/>

ThreadListItemPrimitive.Archive \[#threadlistitemprimitivearchive]

A button to archive the thread.

<ParametersTable
  type="ThreadListItemPrimitiveArchiveProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

ThreadListItemPrimitive.Unarchive \[#threadlistitemprimitiveunarchive]

A button to restore an archived thread.

<ParametersTable
  type="ThreadListItemPrimitiveUnarchiveProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

ThreadListItemPrimitive.Delete \[#threadlistitemprimitivedelete]

A button to permanently delete the thread.

<ParametersTable
  type="ThreadListItemPrimitiveDeleteProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

ThreadListItemMorePrimitive \[#threadlistitemmoreprimitive]

A dropdown menu for additional thread actions, built on Radix UI DropdownMenu.

ThreadListItemMorePrimitive.Root \[#threadlistitemmoreprimitiveroot]

Menu container that manages dropdown state.

<ParametersTable
  type="ThreadListItemMorePrimitiveRootProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

ThreadListItemMorePrimitive.Trigger \[#threadlistitemmoreprimitivetrigger]

Button to open the menu.

<ParametersTable
  type="ThreadListItemMorePrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
]}
/>

ThreadListItemMorePrimitive.Content \[#threadlistitemmoreprimitivecontent]

Menu content container.

<ParametersTable
  type="ThreadListItemMorePrimitiveContentProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

ThreadListItemMorePrimitive.Item \[#threadlistitemmoreprimitiveitem]

Individual menu item.

<ParametersTable
  type="ThreadListItemMorePrimitiveItemProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

ThreadListItemMorePrimitive.Separator \[#threadlistitemmoreprimitiveseparator]

Visual separator between items.

<ParametersTable
  type="ThreadListItemMorePrimitiveSeparatorProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
]}
/>

Related Components \[#related-components]

* [Thread](/docs/ui/thread) - The main chat interface displayed alongside the list


# Thread
URL: /docs/ui/thread

The main chat container with messages, composer, and auto-scroll.

import { ThreadSample } from "@/components/docs/samples/thread";

A complete chat interface that combines message rendering, auto-scrolling, composer input,
attachments, and conditional UI states. Fully customizable and composable.

<ThreadSample />

Anatomy \[#anatomy]

The `Thread` component is built with the following primitives:

```tsx
import { ThreadPrimitive, SelectionToolbarPrimitive, AuiIf } from "@assistant-ui/react";

<ThreadPrimitive.Root>
  <ThreadPrimitive.Viewport>
    <AuiIf condition={(s) => s.thread.isEmpty} />
    <ThreadPrimitive.Messages
      components={{
        EditComposer,
        UserMessage,
        AssistantMessage,
      }}
    />
    <ThreadPrimitive.ScrollToBottom />
  </ThreadPrimitive.Viewport>
  <ThreadPrimitive.Suggestions />
  <AuiIf condition={...} />

  {/* Floating toolbar — appears when text is selected in a message */}
  <SelectionToolbarPrimitive.Root>
    <SelectionToolbarPrimitive.Quote>Quote</SelectionToolbarPrimitive.Quote>
  </SelectionToolbarPrimitive.Root>
</ThreadPrimitive.Root>
```

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add the component \[#add-the-component]

    <InstallCommand shadcn={["thread"]} />

    This adds a `/components/assistant-ui/thread.tsx` file to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    ```tsx title="/app/page.tsx" {1,6}
    import { Thread } from "@/components/assistant-ui/thread";

    export default function Chat() {
      return (
        <div className="h-full">
          <Thread />
        </div>
      );
    }
    ```
  </Step>
</Steps>

Examples \[#examples]

Welcome Screen \[#welcome-screen]

```tsx
<AuiIf condition={(s) => s.thread.isEmpty}>
  <ThreadWelcome />
</AuiIf>
```

Viewport Spacer \[#viewport-spacer]

```tsx
<AuiIf condition={(s) => !s.thread.isEmpty}>
  <div className="min-h-8 grow" />
</AuiIf>
```

Conditional Send/Cancel Button \[#conditional-sendcancel-button]

```tsx
<AuiIf condition={(s) => !s.thread.isRunning}>
  <ComposerPrimitive.Send>
    Send
  </ComposerPrimitive.Send>
</AuiIf>

<AuiIf condition={(s) => s.thread.isRunning}>
  <ComposerPrimitive.Cancel>
    Cancel
  </ComposerPrimitive.Cancel>
</AuiIf>
```

Suggestions \[#suggestions]

Display suggested prompts using the Suggestions API. See the [Suggestions guide](/docs/guides/suggestions) for detailed configuration.

```tsx
import { SuggestionPrimitive, ThreadPrimitive } from "@assistant-ui/react";

// Configure suggestions in your runtime provider
const aui = useAui({
  suggestions: Suggestions(["What's the weather?", "Tell me a joke"]),
});

// Display suggestions in your thread component
<ThreadPrimitive.Suggestions
  components={{
    Suggestion: SuggestionItem,
  }}
/>

// Custom suggestion item
const SuggestionItem = () => (
  <SuggestionPrimitive.Trigger send asChild>
    <button>
      <SuggestionPrimitive.Title />
    </button>
  </SuggestionPrimitive.Trigger>
);
```

API Reference \[#api-reference]

The following primitives are used within the Thread component and can be customized in your `/components/assistant-ui/thread.tsx` file.

Root \[#root]

Contains all parts of the thread.

<ParametersTable
  type="ThreadPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
{
  name: "className",
  type: "string",
  description: "CSS class name.",
},
]}
/>

This primitive renders a `<div>` element unless `asChild` is set.

Viewport \[#viewport]

The scrollable area containing all messages. Automatically scrolls to the bottom as new messages are added.

<ParametersTable
  type="ThreadPrimitiveViewportProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper div.",
},
{
  name: "autoScroll",
  type: "boolean",
  default: "true",
  description:
    "Whether to automatically scroll to the bottom when new messages are added while the viewport was previously scrolled to the bottom.",
},
{
  name: "className",
  type: "string",
  description: "CSS class name.",
},
]}
/>

This primitive renders a `<div>` element unless `asChild` is set.

Messages \[#messages]

Renders all messages in the thread. This primitive renders a separate component for each message.

```tsx
<ThreadPrimitive.Messages
  components={{
    UserMessage: UserMessage,
    EditComposer: EditComposer,
    AssistantMessage: AssistantMessage,
  }}
/>
```

<ParametersTable
  type="ThreadPrimitiveMessagesProps"
  parameters={[
{
  name: "components",
  type: "MessageComponents",
  required: true,
  description: "Components to render for different message types.",
  children: [
    {
      type: "MessageComponents",
      parameters: [
        {
          name: "Message",
          type: "ComponentType",
          description: "Default component for all messages.",
        },
        {
          name: "UserMessage",
          type: "ComponentType",
          description: "Component for user messages.",
        },
        {
          name: "EditComposer",
          type: "ComponentType",
          description:
            "Component for user messages being edited.",
        },
        {
          name: "AssistantMessage",
          type: "ComponentType",
          description: "Component for assistant messages.",
        },
        {
          name: "SystemMessage",
          type: "ComponentType",
          description: "Component for system messages.",
        },
      ],
    },
  ],
},
]}
/>

MessageByIndex \[#messagebyindex]

Renders a single message at the specified index.

```tsx
<ThreadPrimitive.MessageByIndex
  index={0}
  components={{
    UserMessage: UserMessage,
    AssistantMessage: AssistantMessage
  }}
/>
```

<ParametersTable
  type="ThreadPrimitiveMessageByIndexProps"
  parameters={[
{
  name: "index",
  type: "number",
  required: true,
  description: "The index of the message to render.",
},
{
  name: "components",
  type: "MessageComponents",
  description: "Components to render for different message types.",
},
]}
/>

Empty \[#empty]

Renders children only when there are no messages in the thread.

<ParametersTable
  type="ThreadPrimitiveEmptyProps"
  parameters={[
{
  name: "children",
  type: "ReactNode",
  description: "Content to display when the thread is empty.",
},
]}
/>

ScrollToBottom \[#scrolltobottom]

A button to scroll the viewport to the bottom. Disabled when the viewport is already at the bottom.

<ParametersTable
  type="ThreadPrimitiveScrollToBottomProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
{
  name: "className",
  type: "string",
  description: "CSS class name.",
},
]}
/>

This primitive renders a `<button>` element unless `asChild` is set.

Suggestions \[#suggestions-1]

Renders all configured suggestions. Configure suggestions using the `Suggestions()` API in your runtime provider.

```tsx
<ThreadPrimitive.Suggestions
  components={{
    Suggestion: CustomSuggestionComponent,
  }}
/>
```

<ParametersTable
  type="ThreadPrimitiveSuggestionsProps"
  parameters={[
{
  name: "components",
  type: "{ Suggestion: ComponentType }",
  description: "Custom component to render each suggestion.",
},
]}
/>

<Callout type="info">
  See the [Suggestions guide](/docs/guides/suggestions) for detailed information on configuring and customizing suggestions.
</Callout>

AuiIf \[#auiif]

Conditionally renders children based on assistant state. This is a generic component that can access thread, message, composer, and other state.

```tsx
import { AuiIf } from "@assistant-ui/react";

<AuiIf condition={(s) => s.thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>

<AuiIf condition={(s) => s.thread.isRunning}>
  <LoadingIndicator />
</AuiIf>

<AuiIf condition={(s) => s.message.role === "assistant"}>
  <AssistantAvatar />
</AuiIf>
```

<ParametersTable
  type="AuiIfProps"
  parameters={[
{
  name: "condition",
  type: "(state: AssistantState) => boolean",
  required: true,
  description: "A function that receives the assistant state and returns whether to render children.",
},
]}
/>

<Callout type="info">
  The condition function receives an `AssistantState` object with access to `thread`, `message`, `composer`, `part`, and `attachment` state depending on context.
</Callout>

Related Components \[#related-components]

* [ThreadList](/docs/ui/thread-list) - List of threads, with or without sidebar
* [Quoting guide](/docs/guides/quoting) - Quote selected text from messages
* [SelectionToolbarPrimitive](/docs/reference/primitives/selection-toolbar) - Floating toolbar API reference


# ToolFallback
URL: /docs/ui/tool-fallback

Default UI component for tools without dedicated custom renderers.

import {
  ToolFallbackSample,
  ToolFallbackRunningSample,
  ToolFallbackCancelledSample,
  ToolFallbackStreamingSample,
} from "@/components/docs/samples/tool-fallback";

<ToolFallbackSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add tool-fallback \[#add-tool-fallback]

    <InstallCommand shadcn={["tool-fallback"]} />

    This adds a `/components/assistant-ui/tool-fallback.tsx` file to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use it in your application \[#use-it-in-your-application]

    Pass the `ToolFallback` component to the `MessagePrimitive.Parts` component

    ```tsx title="/components/assistant-ui/thread.tsx" {1,9}
    import { ToolFallback } from "@/components/assistant-ui/tool-fallback";

    const AssistantMessage = () => {
      return (
        <MessagePrimitive.Root>
          <MessagePrimitive.Parts
            components={{
              tools: { 
                Fallback: ToolFallback 
              },
            }}
          />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Examples \[#examples]

Streaming Demo \[#streaming-demo]

Interactive demo showing the full tool call lifecycle: running → complete.

<ToolFallbackStreamingSample />

Running State \[#running-state]

Shows a loading spinner and shimmer animation while the tool is executing.

<ToolFallbackRunningSample />

Cancelled State \[#cancelled-state]

Shows a muted appearance when a tool call was cancelled.

<ToolFallbackCancelledSample />

Composable API \[#composable-api]

All sub-components are exported for custom layouts:

| Component              | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `ToolFallback.Root`    | Collapsible container with scroll lock          |
| `ToolFallback.Trigger` | Header with tool name, status icon, and shimmer |
| `ToolFallback.Content` | Animated collapsible content wrapper            |
| `ToolFallback.Args`    | Displays tool arguments                         |
| `ToolFallback.Result`  | Displays tool execution result                  |
| `ToolFallback.Error`   | Displays error or cancellation messages         |

```tsx
import {
  ToolFallback,
  ToolFallbackRoot,
  ToolFallbackTrigger,
  ToolFallbackContent,
  ToolFallbackArgs,
  ToolFallbackResult,
  ToolFallbackError,
} from "@/components/assistant-ui/tool-fallback";

// Compound component syntax
<ToolFallback.Root>
  <ToolFallback.Trigger toolName="get_weather" status={status} />
  <ToolFallback.Content>
    <ToolFallback.Error status={status} />
    <ToolFallback.Args argsText={argsText} />
    <ToolFallback.Result result={result} />
  </ToolFallback.Content>
</ToolFallback.Root>
```

Related Components \[#related-components]

* [ToolGroup](/docs/ui/tool-group) - Group consecutive tool calls together


# ToolGroup
URL: /docs/ui/tool-group

Wrapper for consecutive tool calls with collapsible and styled options.

import {
  ToolGroupSample,
  ToolGroupStreamingSample,
} from "@/components/docs/samples/tool-group";

A wrapper component that groups consecutive tool calls together, displaying them in a collapsible container with auto-expand behavior during streaming.

<ToolGroupSample />

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add tool-group \[#add-tool-group]

    <InstallCommand shadcn={["tool-group"]} />

    This adds a `/components/assistant-ui/tool-group.tsx` file to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use it in your application \[#use-it-in-your-application]

    Pass the `ToolGroup` component to the `MessagePrimitive.Parts` component

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    import { ToolGroup } from "@/components/assistant-ui/tool-group";

    const AssistantMessage = () => {
      return (
        <MessagePrimitive.Root>
          <MessagePrimitive.Parts
            components={{
              ToolGroup,
            }}
          />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Variants \[#variants]

Use the `variant` prop on `ToolGroup.Root` to change the visual style:

```tsx
<ToolGroup.Root variant="outline">...</ToolGroup.Root>
<ToolGroup.Root variant="muted">...</ToolGroup.Root>
```

| Variant   | Description                  |
| --------- | ---------------------------- |
| `default` | No additional styling        |
| `outline` | Rounded border               |
| `muted`   | Muted background with border |

Examples \[#examples]

Streaming Demo (Custom UI + Fallback) \[#streaming-demo-custom-ui--fallback]

Interactive demo showing tool group with **custom tool UIs** and `ToolFallback` working together. Watch as weather cards stream in with loading states, followed by a search tool using the fallback UI.

<ToolGroupStreamingSample />

Custom Tool UIs \[#custom-tool-uis]

ToolGroup works with any custom tool UI components:

```tsx
// Custom Weather Tool UI
function WeatherToolUI({ location, temperature, condition }) {
  return (
    <div className="flex items-center gap-3 rounded-lg border p-3">
      <WeatherIcon condition={condition} />
      <div>
        <div className="text-xs text-muted-foreground">{location}</div>
        <div className="text-lg font-medium">{temperature}°F</div>
      </div>
    </div>
  );
}

// Use in ToolGroup
<ToolGroupRoot variant="outline">
  <ToolGroupTrigger count={3} />
  <ToolGroupContent>
    <WeatherToolUI location="New York" temperature={65} condition="Cloudy" />
    <WeatherToolUI location="London" temperature={55} condition="Rainy" />
    <SearchToolUI query="best restaurants" results={24} />
  </ToolGroupContent>
</ToolGroupRoot>
```

Composable API \[#composable-api]

All sub-components are exported for custom layouts:

| Component           | Description                                            |
| ------------------- | ------------------------------------------------------ |
| `ToolGroup.Root`    | Collapsible container with scroll lock and variants    |
| `ToolGroup.Trigger` | Header with tool count, shimmer animation, and chevron |
| `ToolGroup.Content` | Animated collapsible content wrapper                   |

```tsx
import {
  ToolGroup,
  ToolGroupRoot,
  ToolGroupTrigger,
  ToolGroupContent,
} from "@/components/assistant-ui/tool-group";

// Compound component syntax
<ToolGroup.Root variant="outline" defaultOpen>
  <ToolGroup.Trigger count={3} active={false} />
  <ToolGroup.Content>
    {/* Any tool UI components - custom or ToolFallback */}
  </ToolGroup.Content>
</ToolGroup.Root>
```

API Reference \[#api-reference]

ToolGroupRoot \[#toolgrouproot]

<ParametersTable
  type="ToolGroupRootProps"
  parameters={[
{
  name: "variant",
  type: '"default" | "outline" | "muted"',
  default: '"default"',
  description: "Visual variant of the tool group container.",
},
{
  name: "open",
  type: "boolean",
  description: "Controlled open state.",
},
{
  name: "onOpenChange",
  type: "(open: boolean) => void",
  description: "Callback when open state changes.",
},
{
  name: "defaultOpen",
  type: "boolean",
  default: "false",
  description: "Initial open state for uncontrolled usage.",
},
]}
/>

ToolGroupTrigger \[#toolgrouptrigger]

<ParametersTable
  type="ToolGroupTriggerProps"
  parameters={[
{
  name: "count",
  type: "number",
  required: true,
  description: "Number of tool calls to display in the label.",
},
{
  name: "active",
  type: "boolean",
  default: "false",
  description: "Shows loading spinner and shimmer animation when true.",
},
]}
/>

ToolGroup (Default Export) \[#toolgroup-default-export]

<ParametersTable
  type="ToolGroupProps"
  parameters={[
{
  name: "startIndex",
  type: "number",
  required: true,
  description: "The index of the first tool call in the group.",
},
{
  name: "endIndex",
  type: "number",
  required: true,
  description: "The index of the last tool call in the group.",
},
{
  name: "children",
  type: "ReactNode",
  required: true,
  description: "The rendered tool call components.",
},
]}
/>

Related Components \[#related-components]

* [ToolFallback](/docs/ui/tool-fallback) - Default UI for tools without custom renderers
* [PartGrouping](/docs/ui/part-grouping) - Advanced message part grouping (experimental)


# Assistant Frame API
URL: /docs/copilots/assistant-frame

Share model context across iframe boundaries

The Assistant Frame API enables iframes to provide model context (tools and instructions) to a parent window's assistant. This is particularly useful for embedded applications, plugins, or sandboxed components that need to contribute capabilities to the main assistant.

Overview \[#overview]

The Assistant Frame system consists of two main components:

* **AssistantFrameProvider**: Runs inside the iframe and provides model context
* **AssistantFrameHost**: Runs in the parent window and consumes context from iframes

Basic Usage \[#basic-usage]

In the iframe (Provider) \[#in-the-iframe-provider]

The iframe acts as a provider of model context using `AssistantFrameProvider`:

```tsx
// iframe.tsx
import { AssistantFrameProvider } from "@assistant-ui/react";
import { ModelContextRegistry } from "@assistant-ui/react";
import { z } from "zod";

// Create a registry to manage your model context
const registry = new ModelContextRegistry();

// Expose the registry to the parent window
AssistantFrameProvider.addModelContextProvider(registry);

// Add tools that will be available to the parent assistant
registry.addTool({
  toolName: "searchProducts",
  description: "Search for products in the catalog",
  parameters: z.object({
    query: z.string(),
    category: z.string().optional(),
  }),
  execute: async ({ query, category }) => {
    // Tool implementation runs in the iframe
    const results = await searchAPI(query, category);
    return { products: results };
  },
});

// Add system instructions
const instructionHandle = registry.addInstruction(
  "You are a helpful assistant.",
);

// update the instruction
instructionHandle.update("You have access to a product catalog search tool.");
```

In the parent window (Host) \[#in-the-parent-window-host]

The parent window consumes the iframe's context using `AssistantFrameHost`:

```tsx
// parent.tsx
import { useAssistantFrameHost } from "@assistant-ui/react";
import { useRef } from "react";

function ParentComponent() {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  // Connect to the iframe's model context
  useAssistantFrameHost({
    iframeRef,
    targetOrigin: "https://trusted-iframe-domain.com", // optional for increased security
  });

  return (
    <div>
      <Thread /> {/* Your assistant-ui */}
      <iframe
        ref={iframeRef}
        src="https://trusted-iframe-domain.com/embed"
        title="Embedded App"
      />
    </div>
  );
}
```

Advanced Usage \[#advanced-usage]

ModelContextRegistry \[#modelcontextregistry]

The `ModelContextRegistry` provides a flexible way to manage model context dynamically:

```tsx
const registry = new ModelContextRegistry();

// Add a tool with handle for updates
const toolHandle = registry.addTool({
  toolName: "convertCurrency",
  description: "Convert between currencies",
  parameters: z.object({
    amount: z.number(),
    from: z.string(),
    to: z.string(),
  }),
  execute: async ({ amount, from, to }) => {
    const rate = await fetchExchangeRate(from, to);
    return { result: amount * rate, currency: to };
  },
});

// Update the tool later
toolHandle.update({
  toolName: "convertCurrency",
  description: "Convert between currencies with live rates", // Updated description
  parameters: z.object({
    amount: z.number(),
    from: z.string(),
    to: z.string(),
    includesFees: z.boolean().optional(),
  }),
  execute: async ({ amount, from, to, includesFees }) => {
    const rate = await fetchExchangeRate(from, to);
    const fee = includesFees ? 0.02 : 0; // 2% fee
    return {
      result: amount * rate * (1 - fee),
      currency: to,
      fee: includesFees ? amount * rate * fee : 0,
    };
  },
});

// Remove the tool when no longer needed
toolHandle.remove();

// Add multiple instructions
const instruction1 = registry.addInstruction("Be helpful and concise.");
const instruction2 = registry.addInstruction("Use metric units.");

// Remove instructions
instruction1.remove();
```

Multiple Providers \[#multiple-providers]

You can register multiple model context providers in the same iframe:

```tsx
const catalogRegistry = new ModelContextRegistry();
const analyticsRegistry = new ModelContextRegistry();

// Add different tools to each registry
catalogRegistry.addTool({
  /* ... */
});
analyticsRegistry.addTool({
  /* ... */
});

// Register both providers
const unsubscribe1 =
  AssistantFrameProvider.addModelContextProvider(catalogRegistry);
const unsubscribe2 =
  AssistantFrameProvider.addModelContextProvider(analyticsRegistry);

// Later, unsubscribe if needed
unsubscribe1();
unsubscribe2();
```

Security Considerations \[#security-considerations]

Origin Validation \[#origin-validation]

Both the provider and host can specify allowed origins for security:

```tsx
// In iframe - only accept messages from specific parent
AssistantFrameProvider.addModelContextProvider(
  registry,
  "https://parent-app.com",
);

// In parent - only accept messages from specific iframe
useAssistantFrameHost({
  iframeRef,
  targetOrigin: "https://iframe-app.com",
});
```

Tool Execution \[#tool-execution]

Tools are executed in the iframe's context, keeping sensitive operations sandboxed:

```tsx
registry.addTool({
  toolName: "accessDatabase",
  description: "Query the database",
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    // This runs in the iframe with iframe's permissions
    // Parent cannot directly access the database
    const results = await db.query(query);
    return results;
  },
});
```

API Reference \[#api-reference]

AssistantFrameProvider \[#assistantframeprovider]

Static class that manages model context providers in an iframe.

Methods \[#methods]

addModelContextProvider(provider, targetOrigin?) \[#addmodelcontextproviderprovider-targetorigin]

Registers a model context provider to share with parent windows.

```tsx
const unsubscribe = AssistantFrameProvider.addModelContextProvider(
  registry,
  "https://parent-domain.com", // Optional origin restriction
);
```

dispose() \[#dispose]

Cleans up all resources and removes all providers.

```tsx
AssistantFrameProvider.dispose();
```

AssistantFrameHost \[#assistantframehost]

Class that connects to an iframe's model context providers.

Constructor \[#constructor]

```tsx
const host = new AssistantFrameHost(
  iframeWindow,
  targetOrigin? // Optional origin restriction
);
```

Methods \[#methods-1]

getModelContext() \[#getmodelcontext]

Returns the current merged model context from the iframe.

```tsx
const context = host.getModelContext();
// { system: "...", tools: { ... } }
```

subscribe(callback) \[#subscribecallback]

Subscribes to model context changes.

```tsx
const unsubscribe = host.subscribe(() => {
  console.log("Context updated:", host.getModelContext());
});
```

dispose() \[#dispose-1]

Cleans up the connection to the iframe.

```tsx
host.dispose();
```

useAssistantFrameHost \[#useassistantframehost]

React hook that manages the lifecycle of an AssistantFrameHost.

```tsx
useAssistantFrameHost({
  iframeRef: RefObject<HTMLIFrameElement>,
  targetOrigin?: string,
});
```

ModelContextRegistry \[#modelcontextregistry-1]

A flexible registry for managing model context with dynamic updates.

Methods \[#methods-2]

addTool(tool) \[#addtooltool]

Adds a tool and returns a handle for updates/removal.

```tsx
const handle = registry.addTool({
  toolName: string,
  description?: string,
  parameters: ZodSchema | JSONSchema,
  execute: (args, context) => Promise<any>,
});

handle.update(newTool); // Update the tool
handle.remove(); // Remove the tool
```

addInstruction(instruction) \[#addinstructioninstruction]

Adds a system instruction and returns a handle.

```tsx
const handle = registry.addInstruction("Be concise.");
handle.update("Be detailed."); // Update instruction
handle.remove(); // Remove instruction
```

addProvider(provider) \[#addproviderprovider]

Adds another model context provider.

```tsx
const handle = registry.addProvider(anotherProvider);
handle.remove(); // Remove provider
```

Use Cases \[#use-cases]

Embedded Analytics Dashboard \[#embedded-analytics-dashboard]

An analytics iframe can provide data query tools to the parent assistant:

```tsx
// In analytics iframe
registry.addTool({
  toolName: "queryMetrics",
  description: "Query analytics data",
  parameters: z.object({
    metric: z.string(),
    timeRange: z.string(),
  }),
  execute: async ({ metric, timeRange }) => {
    const data = await analyticsAPI.query(metric, timeRange);
    return { data, visualization: createChart(data) };
  },
});
```

Plugin System \[#plugin-system]

Third-party plugins can extend the assistant's capabilities:

```tsx
// In plugin iframe
registry.addTool({
  toolName: "translateText",
  description: "Translate text to another language",
  parameters: z.object({
    text: z.string(),
    targetLanguage: z.string(),
  }),
  execute: async ({ text, targetLanguage }) => {
    return await pluginAPI.translate(text, targetLanguage);
  },
});
```

Data Visualization \[#data-visualization]

Provide data visualization tools in an iframe:

```tsx
// In visualization iframe
registry.addTool({
  toolName: "createChart",
  description: "Generate a chart from data",
  parameters: z.object({
    data: z.array(
      z.object({
        label: z.string(),
        value: z.number(),
      }),
    ),
    chartType: z.enum(["bar", "line", "pie"]),
    title: z.string().optional(),
  }),
  execute: async ({ data, chartType, title }) => {
    // Generate chart using a library like Chart.js or D3
    const chartUrl = await generateChart(data, chartType, title);
    return {
      chartUrl,
      summary: `Created ${chartType} chart with ${data.length} data points`,
    };
  },
});
```


# makeAssistantVisible
URL: /docs/copilots/make-assistant-readable

Make React components visible and interactive to assistants via higher-order component wrapping.

`makeAssistantVisible` is a higher-order component (HOC) that makes React components "visible" by the assistant, allowing it to understand and interact with the component's HTML structure.

Usage \[#usage]

```tsx
import { makeAssistantVisible } from "@assistant-ui/react";

const Button = ({ onClick, children }) => (
  <button onClick={onClick}>{children}</button>
);

// Basic usage - makes component HTML readable
const ReadableButton = makeAssistantVisible(Button);

// With clickable configuration
const ClickableButton = makeAssistantVisible(Button, {
  clickable: true, // Enables the click tool
});
```

API Reference \[#api-reference]

Parameters \[#parameters]

* `Component`: The base React component to enhance
* `config`: Optional configuration object
  * `clickable`: When true, enables the assistant to programmatically click the component

Behavior \[#behavior]

The HOC will:

1. Make the component's HTML structure available to the assistant via the system context
2. Optionally provide a `click` tool if `clickable` is true
3. Handle nested readable components (only the outermost component's HTML is provided)
4. Forward refs and maintain component props

Example \[#example]

```tsx
// Create a readable form input
const Input = ({ label, ...props }) => (
  <div>
    <label>{label}</label>
    <input {...props} />
  </div>
);

const ReadableInput = makeAssistantVisible(Input);

// Use in your component
function Form() {
  return (
    <ReadableInput label="Email" type="email" placeholder="Enter your email" />
  );
}
```

Technical Details \[#technical-details]

When a component is made readable:

* It's wrapped in a `ReadableContext.Provider` to handle nesting
* The component's `outerHTML` is provided as system context
* If `clickable` is true, a unique `data-click-id` is added and a `click` tool is provided
* The click tool uses `querySelector` and simulates a click event
* All props and refs are properly forwarded to maintain component functionality


# makeAssistantToolUI
URL: /docs/copilots/make-assistant-tool-ui

Register custom UI components to render tool executions and their status.

The `makeAssistantToolUI` utility is used to register a tool UI component with the Assistant.

Usage \[#usage]

```tsx
import { makeAssistantToolUI } from "@assistant-ui/react";

const MyToolUI = makeAssistantToolUI({
  toolName: "myTool",
  render: ({ args, result, status }) => {
    // render your tool UI here
  },
});
```

API \[#api]

Parameters \[#parameters]

<ParametersTable
  type="AssistantToolUIProps<TArgs, TResult>"
  parameters={[
{
  name: "toolName",
  type: "string",
  description:
    "The name of the tool. This must match the name of the tool defined in the assistant.",
},
{
  name: "render",
  type: "ComponentType<ToolCallMessagePartProps<TArgs, TResult>>",
  description:
    "A React component that renders the tool UI. Receives the following props:",
  required: true,
  children: [
    {
      type: "ToolCallMessagePartProps<TArgs, TResult>",
      parameters: [
        {
          name: "type",
          type: '"tool-call"',
          description: "The message part type",
        },
        {
          name: "toolCallId",
          type: "string",
          description: "Unique identifier for this tool call",
        },
        {
          name: "toolName",
          type: "string",
          description: "The name of the tool being called",
        },
        {
          name: "args",
          type: "TArgs",
          description: "The arguments passed to the tool",
        },
        {
          name: "argsText",
          type: "string",
          description: "String representation of the arguments",
        },
        {
          name: "result",
          type: "TResult | undefined",
          description: "The result of the tool execution (if complete)",
        },
        {
          name: "isError",
          type: "boolean | undefined",
          description: "Whether the result is an error",
        },
        {
          name: "status",
          type: "ToolCallMessagePartStatus",
          description:
            'The execution status object with a type property: "running", "complete", "incomplete", or "requires_action"',
        },
        {
          name: "addResult",
          type: "(result: TResult | ToolResponse<TResult>) => void",
          description:
            "Function to add a result (useful for human-in-the-loop tools)",
        },
        {
          name: "artifact",
          type: "unknown",
          description:
            "Optional artifact data associated with the tool call",
        },
      ],
    },
  ],
},
]}
/>

Returns \[#returns]

A React functional component that should be included in your component tree. This component doesn't render anything itself, but it registers the tool UI with the Assistant.

Example \[#example]

```tsx
import { makeAssistantToolUI } from "@assistant-ui/react";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const GetWeatherUI = makeAssistantToolUI({
  toolName: "get_weather",
  render: ({ args, result, status }) => {
    if (status.type === "requires_action")
      return <p>Getting weather for {args.location}...</p>;
    if (status.type === "running") return <p>Loading...</p>;
    if (status.type === "incomplete" && status.reason === "error")
      return <p>Error getting weather.</p>;
    if (status.type === "complete")
      return <p>The weather is {result.weather}.</p>;
    return null;
  },
});

function App() {
  return (
    <AssistantRuntimeProvider>
      {/* ...your other components */}
      <GetWeatherUI />
    </AssistantRuntimeProvider>
  );
}
```

This example shows how to create a simple UI for a `get_weather` tool. The UI will display different messages depending on the status of the tool execution.


# makeAssistantTool
URL: /docs/copilots/make-assistant-tool

Create React components that provide reusable tools to the assistant.

`makeAssistantTool` creates a React component that provides a tool to the assistant. This is useful for defining reusable tools that can be composed into your application.

Usage \[#usage]

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

// Define the tool using the tool() helper
const submitForm = tool({
  parameters: z.object({
    email: z.string().email(),
    name: z.string(),
  }),
  execute: async ({ email, name }) => {
    // Implementation
    return { success: true };
  },
});

// Create a tool component
const SubmitFormTool = makeAssistantTool({
  ...submitForm,
  toolName: "submitForm",
});

// Use in your component
function Form() {
  return (
    <div>
      <form>{/* form fields */}</form>
      <SubmitFormTool />
    </div>
  );
}
```

API Reference \[#api-reference]

Parameters \[#parameters]

<ParametersTable
  type="AssistantToolProps<TArgs, TResult>"
  parameters={[
{
  name: "toolName",
  type: "string",
  description: "The unique identifier for the tool",
  required: true,
},
{
  name: "parameters",
  type: "StandardSchemaV1<TArgs> | JSONSchema7",
  description:
    "Schema defining the tool's parameters (typically a Zod schema)",
  required: true,
},
{
  name: "execute",
  type: "(args: TArgs, context: ToolExecutionContext) => TResult | Promise<TResult>",
  description:
    "Function that implements the tool's behavior (required for frontend tools)",
  required: true,
},
{
  name: "description",
  type: "string",
  description: "Optional description of the tool's purpose",
},
{
  name: "render",
  type: "ComponentType<ToolCallMessagePartProps<TArgs, TResult>>",
  description:
    "Optional custom UI component for rendering the tool execution. Receives the following props:",
  children: [
    {
      type: "ToolCallMessagePartProps<TArgs, TResult>",
      parameters: [
        {
          name: "type",
          type: '"tool-call"',
          description: "The message part type",
        },
        {
          name: "toolCallId",
          type: "string",
          description: "Unique identifier for this tool call",
        },
        {
          name: "toolName",
          type: "string",
          description: "The name of the tool being called",
        },
        {
          name: "args",
          type: "TArgs",
          description: "The arguments passed to the tool",
        },
        {
          name: "argsText",
          type: "string",
          description: "String representation of the arguments",
        },
        {
          name: "result",
          type: "TResult | undefined",
          description: "The result of the tool execution (if complete)",
        },
        {
          name: "isError",
          type: "boolean | undefined",
          description: "Whether the result is an error",
        },
        {
          name: "status",
          type: "ToolCallMessagePartStatus",
          description:
            'The execution status object with a type property: "running", "complete", "incomplete", or "requires_action"',
        },
        {
          name: "addResult",
          type: "(result: TResult | ToolResponse<TResult>) => void",
          description:
            "Function to add a result (useful for human-in-the-loop tools)",
        },
        {
          name: "artifact",
          type: "unknown",
          description:
            "Optional artifact data associated with the tool call",
        },
      ],
    },
  ],
},
]}
/>

Returns \[#returns]

Returns a React component that:

* Provides the tool to the assistant when mounted
* Automatically removes the tool when unmounted
* Renders nothing in the DOM (returns null)

Example with Multiple Tools \[#example-with-multiple-tools]

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

// Define tools
const validateEmail = tool({
  parameters: z.object({
    email: z.string(),
  }),
  execute: ({ email }) => {
    const isValid = email.includes("@");
    return { isValid, reason: isValid ? "Valid email" : "Missing @" };
  },
});

const sendEmail = tool({
  parameters: z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string(),
  }),
  execute: async (params) => {
    // Tool logic
    return { sent: true };
  },
});

// Create tool components
const EmailValidator = makeAssistantTool({
  ...validateEmail,
  toolName: "validateEmail",
});
const EmailSender = makeAssistantTool({
  ...sendEmail,
  toolName: "sendEmail",
});

// Use together
function EmailForm() {
  return (
    <div>
      <form>{/* form fields */}</form>
      <EmailValidator />
      <EmailSender />
    </div>
  );
}
```

Best Practices \[#best-practices]

1. **Parameter Validation**

   * Always use Zod schemas to define parameters
   * Be specific about parameter types and constraints
   * Add helpful error messages to schema validations

2. **Error Handling**

   * Return meaningful error messages
   * Consider returning partial results when possible
   * Handle async errors appropriately

3. **Composition**
   * Break complex tools into smaller, focused ones
   * Consider tool dependencies and interactions
   * Use multiple tools together for complex functionality


# Model Context
URL: /docs/copilots/model-context

Configure assistant behavior through system instructions, tools, and context providers.

Model Context is the foundation of intelligence in assistant-ui components. It provides configuration and capabilities to the assistant through a context provider system.

Core Concepts \[#core-concepts]

System Instructions \[#system-instructions]

System instructions define the base behavior and knowledge available to the assistant. These can be provided in several ways:

```tsx
import {
  useAssistantInstructions,
  makeAssistantVisible,
} from "@assistant-ui/react";

// Via useAssistantInstructions
useAssistantInstructions("You are a helpful assistant...");

// Via makeAssistantVisible
const ReadableComponent = makeAssistantVisible(MyComponent);
// Automatically provides component HTML as system context
```

Tools \[#tools]

Tools are functions that the assistant can use to interact with your application. They can be provided through various mechanisms:

```tsx
import {
  makeAssistantVisible,
  makeAssistantTool,
  tool,
} from "@assistant-ui/react";
import { z } from "zod";

// Via makeAssistantVisible's clickable option
const ClickableButton = makeAssistantVisible(Button, {
  clickable: true, // Provides a click tool
});

// Via makeAssistantTool
const submitForm = tool({
  parameters: z.object({
    email: z.string().email(),
    name: z.string(),
  }),
  execute: async ({ email, name }) => {
    // Implementation
    return { success: true };
  },
});

const SubmitFormTool = makeAssistantTool({
  ...submitForm,
  toolName: "submitForm"
});

// Use in your component
function Form() {
  return (
    <div>
      <form>{/* form fields */}</form>
      <SubmitFormTool />
    </div>
  );
}
```

Context Provider System \[#context-provider-system]

The context provider system allows components to contribute to the model context. Here's a typical usage pattern:

```tsx
import { useAui, tool } from "@assistant-ui/react";
import { useEffect } from "react";
import { z } from "zod";

function MyComponent() {
  const aui = useAui();

  // Define tool using the tool() helper
  const myTool = tool({
    parameters: z.object({
      query: z.string(),
    }),
    execute: async ({ query }) => {
      const result = await searchDatabase(query);
      return { result };
    },
  });

  useEffect(() => {
    // Register context provider
    return aui.modelContext().register({
      getModelContext: () => ({
        system: "You are a helpful search assistant...",
        tools: { myTool },
      }),
    });
  }, [aui]); // Re-register if api changes

  return <div>{/* component content */}</div>;
}
```

Provider Composition \[#provider-composition]

Multiple providers can be registered, and their contexts will be composed:

* System instructions are concatenated
* Tool sets are merged
* Nested readable components only contribute their context at the outermost level

Best Practices \[#best-practices]

1. **System Instructions**

   * Keep them focused and specific to the component's purpose
   * Use useAssistantInstructions for explicit instructions
   * Let makeAssistantVisible handle component structure

2. **Tools**

   * Use the tool() helper to define tool schemas and behavior
   * Prefer makeAssistantTool for reusable tools
   * Handle errors gracefully
   * Consider async operations and loading states
   * Use the built-in click tool when possible

3. **Context Management**
   * Register providers in useEffect for proper cleanup
   * Clean up providers when components unmount
   * Avoid deeply nested readable components
   * Consider performance implications of large HTML structures


# Intelligent Components
URL: /docs/copilots/motivation

Add intelligence to React components through readable interfaces and assistant tools.

React revolutionized web development with components that combine logic, structure, and style. Now, with assistant-ui, we're adding a fourth dimension: intelligence. Let's learn how to build smart components through a practical banking app example.

The Evolution of Components \[#the-evolution-of-components]

Traditional React components combine three elements:

```tsx
// Traditional React Component
function TransactionHistory({ transactions }) {
  // 1. Logic (JavaScript/TypeScript)
  const handleRefund = (transactionId) => {
    // Process refund...
  };

  // 2. Structure (JSX/TSX)
  return (
    // 3. Style (CSS via className)
    <div className="transaction-list">
      {transactions.map((transaction) => (
        <div key={transaction.id} className="transaction-item">
          <span>${transaction.amount}</span>
          <span>{transaction.merchant}</span>
          <button onClick={() => handleRefund(transaction.id)}>
            Request Refund
          </button>
        </div>
      ))}
    </div>
  );
}
```

Adding Intelligence \[#adding-intelligence]

With assistant-ui, we can enhance this component with intelligence using four powerful APIs:

1. Making Components Readable (makeAssistantVisible) \[#1-making-components-readable-makeassistantvisible]

First, let's make our buttons "readable" and interactive:

```tsx
import { makeAssistantVisible } from "@assistant-ui/react";

// Make the refund button intelligent
const SmartButton = makeAssistantVisible(
  ({ onClick, children }) => <button onClick={onClick}>{children}</button>,
  {
    clickable: true, // Allow the assistant to click the button
  },
);

function TransactionHistory({ transactions }) {
  return (
    <div className="transaction-list">
      {transactions.map((transaction) => (
        <div key={transaction.id} className="transaction-item">
          <span>${transaction.amount}</span>
          <span>{transaction.merchant}</span>
          <SmartButton onClick={() => handleRefund(transaction.id)}>
            Request Refund
          </SmartButton>
        </div>
      ))}
    </div>
  );
}
```

Now the assistant can:

* Understand the transaction history structure
* Interact with refund buttons
* Help users manage their transactions

2. Adding System Instructions (useAssistantInstructions) \[#2-adding-system-instructions-useassistantinstructions]

Next, let's give the assistant specific instructions about its role:

```tsx
import { useAssistantInstructions } from "@assistant-ui/react";

function SmartTransactionHistory() {
  useAssistantInstructions(`
    You are a helpful banking assistant that:
    1. Helps users understand their transactions
    2. Explains refund policies
    3. Identifies suspicious transactions
    4. Guides users through the refund process
  `);

  return <TransactionHistory transactions={transactions} />;
}
```

3. Creating Tools (makeAssistantTool) \[#3-creating-tools-makeassistanttool]

Let's add transaction-specific tools for the assistant:

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

// Define a tool to analyze transactions
const analyzeTransaction = tool({
  parameters: z.object({
    transactionId: z.string(),
    merchantName: z.string(),
  }),
  execute: async ({ transactionId, merchantName }) => {
    // Analyze transaction patterns, merchant reputation, etc.
    return {
      isSuspicious: false,
      merchantRating: 4.5,
      similarTransactions: 3,
      refundEligible: true,
    };
  },
});

// Create a tool component
const TransactionAnalyzer = makeAssistantTool({
  ...analyzeTransaction,
  toolName: "analyzeTransaction",
});

function SmartTransactionHistory() {
  // Previous instructions...
  return (
    <>
      <TransactionHistory transactions={transactions} />
      <TransactionAnalyzer />
    </>
  );
}
```

4. Adding Custom Context (Model Context) \[#4-adding-custom-context-model-context]

Finally, let's add dynamic context based on the user's transaction patterns:

```tsx
import { useAui } from "@assistant-ui/react";
import { useEffect } from "react";

function SmartTransactionHistory({ userProfile }) {
  const aui = useAui();

  useEffect(() => {
    return aui.modelContext().register({
      getModelContext: () => ({
        system: `
          User spending patterns:
          - Average transaction: ${userProfile.avgTransaction}
          - Common merchants: ${userProfile.frequentMerchants.join(", ")}
          - Refund history: ${userProfile.refundCount} requests
        `,
      }),
    });
  }, [api, userProfile]);

  // Previous components...
}
```

The Result: An Intelligent Banking Experience \[#the-result-an-intelligent-banking-experience]

This enhanced component now provides:

* Natural language interaction with transaction history
* Contextual help for understanding transactions
* Automated transaction analysis
* Smart refund assistance

The assistant can now:

1. Read and understand transaction details
2. Follow banking-specific guidelines
3. Use tools to analyze transactions
4. Access user patterns for personalized help

This creates a more intuitive and safer banking experience while maintaining the familiar React component model.

Next Steps \[#next-steps]

Learn more about each API:

* [makeAssistantVisible](make-assistant-readable) for component understanding
* [makeAssistantTool](make-assistant-tool) for transaction analysis
* [useAssistantInstructions](use-assistant-instructions) for behavior guidance
* [Model Context](model-context) for dynamic context management


# useAssistantInstructions
URL: /docs/copilots/use-assistant-instructions

React hook for setting system instructions to guide assistant behavior.

`useAssistantInstructions` is a React hook that allows you to set system instructions for your assistant-ui components.

Usage \[#usage]

```tsx
import { useAssistantInstructions } from "@assistant-ui/react";

function MyComponent() {
  // Simple string usage
  useAssistantInstructions("You are a helpful form assistant...");

  // With configuration object
  useAssistantInstructions({
    instruction: "You are a helpful form assistant...",
    disabled: false, // Optional: disable the instructions
  });

  return <div>My Component</div>;
}
```

API Reference \[#api-reference]

Parameters \[#parameters]

The hook accepts either:

* A string containing the system instructions
* A configuration object with:
  * `instruction`: The system instructions
  * `disabled`: Optional boolean to disable the instructions

Behavior \[#behavior]

The hook will:

1. Register the provided instructions as system instructions in the model context
2. Automatically clean up when the component unmounts
3. Update when the instructions change
4. Do nothing if disabled is set to true

Example \[#example]

```tsx
function SmartForm() {
  useAssistantInstructions({
    instruction: `
      You are a form assistant that:
      - Validates user input
      - Provides helpful suggestions
      - Explains any errors
      - Guides users through complex fields
    `,
  });

  return <form>{/* Your form fields here */}</form>;
}
```


# Attachments
URL: /docs/guides/attachments

Let users attach files, images, and documents to messages.

import { AttachmentSample } from "@/components/docs/samples/attachment";

Enable users to attach files to their messages, enhancing conversations with images, documents, and other content.

<AttachmentSample />

Overview \[#overview]

The attachment system in assistant-ui provides a flexible framework for handling file uploads in your AI chat interface. It consists of:

* **Attachment Adapters**: Backend logic for processing attachment files
* **UI Components**: Pre-built components for attachment display and interaction
* **Runtime Integration**: Seamless integration with all assistant-ui runtimes

Getting Started \[#getting-started]

<Steps>
  <Step>
    Install UI Components \[#install-ui-components]

    First, add the attachment UI components to your project:

    <InstallCommand shadcn={["attachment"]} />

    This adds `/components/assistant-ui/attachment.tsx` to your project.

    <Callout type="tip">
      **Next steps:** Feel free to adjust these auto-generated components (styling,
      layout, behavior) to match your application's design system.
    </Callout>
  </Step>

  <Step>
    Set up Runtime (No Configuration Required) \[#set-up-runtime-no-configuration-required]

    For `useChatRuntime`, attachments work automatically without additional configuration:

    ```tsx title="/app/MyRuntimeProvider.tsx"
    import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

    const runtime = useChatRuntime();
    ```

    <Callout type="info">
      **Note:** The AI SDK runtime handles attachments automatically. For other runtimes like `useLocalRuntime`, you may still need to configure attachment adapters as shown in the [Creating Custom Attachment Adapters](#creating-custom-attachment-adapters) section below.
    </Callout>
  </Step>

  <Step>
    Add UI Components \[#add-ui-components]

    Integrate attachment components into your chat interface:

    ```tsx title="/components/assistant-ui/thread.tsx"
    // In your Composer component
    import {
      ComposerAttachments,
      ComposerAddAttachment,
    } from "@/components/assistant-ui/attachment";

    const Composer = () => {
      return (
        <ComposerPrimitive.Root>
          <ComposerAttachments />
          <ComposerAddAttachment />
          <ComposerPrimitive.Input placeholder="Type a message..." />
        </ComposerPrimitive.Root>
      );
    };

    // In your UserMessage component
    import { UserMessageAttachments } from "@/components/assistant-ui/attachment";

    const UserMessage = () => {
      return (
        <MessagePrimitive.Root>
          <UserMessageAttachments />
          <MessagePrimitive.Parts />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>
</Steps>

Built-in Attachment Adapters \[#built-in-attachment-adapters]

SimpleImageAttachmentAdapter \[#simpleimageattachmentadapter]

Handles image files and converts them to data URLs for display in the chat UI. By default, images are shown inline but not sent to the LLM - use the VisionImageAdapter example above to send images to vision-capable models.

```tsx
const imageAdapter = new SimpleImageAttachmentAdapter();
// Accepts: image/* (JPEG, PNG, GIF, etc.)
// Output: { type: "image", url: "data:image/..." }
```

SimpleTextAttachmentAdapter \[#simpletextattachmentadapter]

Processes text files and wraps content in formatted tags:

```tsx
const textAdapter = new SimpleTextAttachmentAdapter();
// Accepts: text/plain, text/html, text/markdown, etc.
// Output: Content wrapped in <attachment>...</attachment> tags
```

CompositeAttachmentAdapter \[#compositeattachmentadapter]

Combines multiple adapters to support various file types:

```tsx
const compositeAdapter = new CompositeAttachmentAdapter([
  new SimpleImageAttachmentAdapter(),
  new SimpleTextAttachmentAdapter(),
  // Add more adapters as needed
]);
```

Creating Custom Attachment Adapters \[#creating-custom-attachment-adapters]

Build your own adapters for specialized file handling. Below are complete examples for common use cases.

Vision-Capable Image Adapter \[#vision-capable-image-adapter]

Send images to vision-capable LLMs like GPT-4V, Claude 3, or Gemini Pro Vision:

```tsx
import {
  AttachmentAdapter,
  PendingAttachment,
  CompleteAttachment,
} from "@assistant-ui/react";

class VisionImageAdapter implements AttachmentAdapter {
  accept = "image/jpeg,image/png,image/webp,image/gif";

  async add({ file }: { file: File }): Promise<PendingAttachment> {
    // Validate file size (e.g., 20MB limit for most LLMs)
    const maxSize = 20 * 1024 * 1024; // 20MB
    if (file.size > maxSize) {
      throw new Error("Image size exceeds 20MB limit");
    }

    // Return pending attachment while processing
    return {
      id: crypto.randomUUID(),
      type: "image",
      name: file.name,
      file,
      status: { type: "running" },
    };
  }

  async send(attachment: PendingAttachment): Promise<CompleteAttachment> {
    // Convert image to base64 data URL
    const base64 = await this.fileToBase64DataURL(attachment.file);

    // Return in assistant-ui format with image content
    return {
      id: attachment.id,
      type: "image",
      name: attachment.name,
      content: [
        {
          type: "image",
          image: base64, // data:image/jpeg;base64,... format
        },
      ],
      status: { type: "complete" },
    };
  }

  async remove(attachment: PendingAttachment): Promise<void> {
    // Cleanup if needed (e.g., revoke object URLs if you created any)
  }

  private async fileToBase64DataURL(file: File): Promise<string> {
    return new Promise((resolve, reject) => {
      const reader = new FileReader();
      reader.onload = () => {
        // FileReader result is already a data URL
        resolve(reader.result as string);
      };
      reader.onerror = reject;
      reader.readAsDataURL(file);
    });
  }
}
```

PDF Document Adapter \[#pdf-document-adapter]

Handle PDF files by extracting text or converting to base64 for processing:

```tsx
import {
  AttachmentAdapter,
  PendingAttachment,
  CompleteAttachment,
} from "@assistant-ui/react";

class PDFAttachmentAdapter implements AttachmentAdapter {
  accept = "application/pdf";

  async add({ file }: { file: File }): Promise<PendingAttachment> {
    // Validate file size
    const maxSize = 10 * 1024 * 1024; // 10MB limit
    if (file.size > maxSize) {
      throw new Error("PDF size exceeds 10MB limit");
    }

    return {
      id: crypto.randomUUID(),
      type: "document",
      name: file.name,
      file,
      status: { type: "running" },
    };
  }

  async send(attachment: PendingAttachment): Promise<CompleteAttachment> {
    // Option 1: Extract text from PDF (requires pdf parsing library)
    // const text = await this.extractTextFromPDF(attachment.file);

    // Option 2: Convert to base64 for API processing
    const base64Data = await this.fileToBase64(attachment.file);

    return {
      id: attachment.id,
      type: "document",
      name: attachment.name,
      content: [
        {
          type: "text",
          text: `[PDF Document: ${attachment.name}]\nBase64 data: ${base64Data.substring(0, 50)}...`,
        },
      ],
      status: { type: "complete" },
    };
  }

  async remove(attachment: PendingAttachment): Promise<void> {
    // Cleanup if needed
  }

  private async fileToBase64(file: File): Promise<string> {
    const arrayBuffer = await file.arrayBuffer();
    const bytes = new Uint8Array(arrayBuffer);
    let binary = "";
    bytes.forEach((byte) => {
      binary += String.fromCharCode(byte);
    });
    return btoa(binary);
  }

  // Optional: Extract text from PDF using a library like pdf.js
  private async extractTextFromPDF(file: File): Promise<string> {
    // Implementation would use pdf.js or similar
    // This is a placeholder
    return "Extracted PDF text content";
  }
}
```

Using Custom Adapters \[#using-custom-adapters]

With LocalRuntime \[#with-localruntime]

When using `LocalRuntime`, you need to handle images in your `ChatModelAdapter` (the adapter that connects to your AI backend):

```tsx
import { useLocalRuntime, ChatModelAdapter } from "@assistant-ui/react";

// This adapter connects LocalRuntime to your AI backend
const MyModelAdapter: ChatModelAdapter = {
  async run({ messages, abortSignal }) {
    // Convert messages to format expected by your vision-capable API
    const formattedMessages = messages.map((msg) => {
      if (
        msg.role === "user" &&
        msg.content.some((part) => part.type === "image")
      ) {
        // Format for GPT-4V or similar vision models
        return {
          role: "user",
          content: msg.content.map((part) => {
            if (part.type === "text") {
              return { type: "text", text: part.text };
            }
            if (part.type === "image") {
              return {
                type: "image_url",
                image_url: { url: part.image },
              };
            }
            return part;
          }),
        };
      }

      // Regular text messages
      return {
        role: msg.role,
        content: msg.content
          .filter((c) => c.type === "text")
          .map((c) => c.text)
          .join("\n"),
      };
    });

    // Send to your vision-capable API
    const response = await fetch("/api/vision-chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ messages: formattedMessages }),
      signal: abortSignal,
    });

    const data = await response.json();
    return {
      content: [{ type: "text", text: data.message }],
    };
  },
};

// Create runtime with vision image adapter
const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: {
    attachments: new VisionImageAdapter(),
  },
});
```

Advanced Features \[#advanced-features]

Progress Updates \[#progress-updates]

Provide real-time upload progress using async generators:

```tsx
class UploadAttachmentAdapter implements AttachmentAdapter {
  accept = "*/*";

  async *add({ file }: { file: File }) {
    const id = generateId();

    // Initial pending state
    yield {
      id,
      type: "file",
      name: file.name,
      file,
      status: { type: "running", progress: 0 },
    } as PendingAttachment;

    // Simulate upload progress
    for (let progress = 10; progress <= 90; progress += 10) {
      await new Promise((resolve) => setTimeout(resolve, 100));

      yield {
        id,
        type: "file",
        name: file.name,
        file,
        status: { type: "running", progress },
      } as PendingAttachment;
    }

    // Return final pending state
    return {
      id,
      type: "file",
      name: file.name,
      file,
      status: { type: "running", progress: 100 },
    } as PendingAttachment;
  }

  async send(attachment: PendingAttachment): Promise<CompleteAttachment> {
    // Upload the file and return complete attachment
    const url = await this.uploadFile(attachment.file);

    return {
      id: attachment.id,
      type: attachment.type,
      name: attachment.name,
      content: [
        {
          type: "file",
          data: url, // or base64 data
          mimeType: attachment.file.type,
        },
      ],
      status: { type: "complete" },
    };
  }

  async remove(attachment: PendingAttachment): Promise<void> {
    // Cleanup logic
  }

  private async uploadFile(file: File): Promise<string> {
    // Your upload logic here
    return "https://example.com/file-url";
  }
}
```

Validation and Error Handling \[#validation-and-error-handling]

Implement robust validation in your adapters:

```tsx
class ValidatedImageAdapter implements AttachmentAdapter {
  accept = "image/*";
  maxSizeBytes = 5 * 1024 * 1024; // 5MB

  async add({ file }: { file: File }): Promise<PendingAttachment> {
    // Validate file size
    if (file.size > this.maxSizeBytes) {
      return {
        id: generateId(),
        type: "image",
        name: file.name,
        file,
        status: {
          type: "incomplete",
          reason: "error",
          error: new Error("File size exceeds 5MB limit"),
        },
      };
    }

    // Validate image dimensions
    try {
      const dimensions = await this.getImageDimensions(file);
      if (dimensions.width > 4096 || dimensions.height > 4096) {
        throw new Error("Image dimensions exceed 4096x4096");
      }
    } catch (error) {
      return {
        id: generateId(),
        type: "image",
        name: file.name,
        file,
        status: {
          type: "incomplete",
          reason: "error",
          error,
        },
      };
    }

    // Return valid attachment
    return {
      id: generateId(),
      type: "image",
      name: file.name,
      file,
      status: { type: "running" },
    };
  }

  private async getImageDimensions(file: File) {
    // Implementation to check image dimensions
  }
}
```

External Source Attachments \[#external-source-attachments]

Add attachments from external sources (URLs, API data, CMS references) without needing a `File` object or an `AttachmentAdapter`:

```tsx
const aui = useAui();

// Add an attachment from an external source
await aui.composer().addAttachment({
  name: "report.pdf",
  contentType: "application/pdf",
  content: [{ type: "text", text: "Extracted document content..." }],
});

// Optionally provide id and type
await aui.composer().addAttachment({
  id: "cms-doc-123",
  type: "document",
  name: "Product Spec",
  content: [{ type: "text", text: "Product specification content..." }],
});
```

External attachments are added as complete attachments directly — they skip the `AttachmentAdapter` entirely and can be removed without one.

Multiple File Selection \[#multiple-file-selection]

Enable multi-file selection with custom limits:

```tsx
const aui = useAui();

const handleMultipleFiles = async (files: FileList) => {
  const maxFiles = 5;
  const filesToAdd = Array.from(files).slice(0, maxFiles);

  for (const file of filesToAdd) {
    await aui.composer().addAttachment({ file });
  }
};
```

Backend Integration \[#backend-integration]

With Vercel AI SDK \[#with-vercel-ai-sdk]

Attachments are sent to the backend as file content parts.

Runtime Support \[#runtime-support]

Attachments work with all assistant-ui runtimes:

* **AI SDK Runtime**: `useChatRuntime`, `useAssistantRuntime`
* **External Store**: `useExternalStoreRuntime`
* **LangGraph**: `useLangGraphRuntime`
* **Custom Runtimes**: Any runtime implementing the attachment interface

<Callout type="tip">
  The attachment system is designed to be extensible. You can create adapters
  for any file type, integrate with cloud storage services, or implement custom
  processing logic to fit your specific needs.
</Callout>

Best Practices \[#best-practices]

1. **File Size Limits**: Always validate file sizes to prevent memory issues
2. **Type Validation**: Verify file types match your `accept` pattern
3. **Error Handling**: Provide clear error messages for failed uploads
4. **Progress Feedback**: Show upload progress for better UX
5. **Security**: Validate and sanitize file content before processing
6. **Accessibility**: Ensure attachment UI is keyboard navigable

Resources \[#resources]

* [Attachment UI Components](/docs/ui/attachment) - UI implementation details
* [API Reference](/docs/api-reference) - Detailed type definitions


# Message Branching
URL: /docs/guides/branching

Navigate between different conversation branches when editing or reloading messages.

import { BranchingSample } from "@/components/docs/samples/branching";

Switch between different conversation branches.

<BranchingSample />

A new branch is created when:

* a user message is edited
* an assistant message is reloaded

Branches are automatically tracked by assistant-ui by observing changes to the `messages` array.

Enabling branch support \[#enabling-branch-support]

You can show a branch picker by using `BranchPickerPrimitive`.

```tsx {1, 8, 15-30}
import { BranchPickerPrimitive } from "@assistant-ui/react";


const Message = () => {
  return (
    <MessagePrimitive.Root>
      ...
      <BranchPicker /> {/* <-- show the branch picker */}
      ...
    </EditComposerPrimitive.Root>
  );
};


const BranchPicker = () => {
  return (
    <BranchPickerPrimitive.Root hideWhenSingleBranch>
      <BranchPickerPrimitive.Previous />
      <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
      <BranchPickerPrimitive.Next />
    </BranchPickerPrimitive.Root>
  );
};
```

API \[#api]

You can access the current branch state or navigate via the API as well.\
These APIs rely on the message state and may only be called inside a message component.

```tsx
const hasBranches = useMessageIf({ hasBranches: true }); // whether branchCount is >= 2

// navigation
const goToNextBranch = useGoToNextBranch(); // null if there is no next branch
const goToPreviousBranch = useGoToPreviousBranch(); // null if there is no previous branch
```


# Chain of Thought
URL: /docs/guides/chain-of-thought

Group reasoning and tool calls into a collapsible accordion UI.

LLMs often produce reasoning steps and tool calls in succession. Chain of Thought lets you visually group these consecutive parts into a single collapsible accordion, giving users a clean "thinking" UI.

Overview \[#overview]

When a model like OpenAI's `o4-mini` responds, it may emit a sequence of reasoning tokens and tool calls before producing its final text answer. By default, these parts render individually. `ChainOfThoughtPrimitive` groups consecutive reasoning + tool-call parts together and renders them through a single component.

Key benefits:

* **Cleaner UI** — Collapse intermediate steps behind a "Thinking" toggle
* **Better context** — Users see that reasoning and tool calls are related
* **Built-in accordion** — Expand/collapse with a single click; collapsed by default

Quick Start \[#quick-start]

<Steps>
  <Step>
    Pass a ChainOfThought component to MessagePrimitive.Parts \[#pass-a-chainofthought-component-to-messageprimitiveparts]

    `MessagePrimitive.Parts` accepts a `ChainOfThought` component. When provided, consecutive reasoning and tool-call parts are automatically grouped and rendered through it.

    ```tsx
    import {
      AuiIf,
      ChainOfThoughtPrimitive,
      MessagePrimitive,
    } from "@assistant-ui/react";
    import type { FC } from "react";

    const Reasoning: FC<{ text: string }> = ({ text }) => {
      return (
        <p className="whitespace-pre-wrap px-4 py-2 text-muted-foreground text-sm italic">
          {text}
        </p>
      );
    };

    const ChainOfThought: FC = () => {
      return (
        <ChainOfThoughtPrimitive.Root className="my-2 rounded-lg border">
          <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 font-medium text-sm hover:bg-muted/50">
            Thinking
          </ChainOfThoughtPrimitive.AccordionTrigger>
          <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
            <ChainOfThoughtPrimitive.Parts
              components={{ Reasoning, tools: { Fallback: ToolFallback } }}
            />
          </AuiIf>
        </ChainOfThoughtPrimitive.Root>
      );
    };

    const AssistantMessage: FC = () => {
      return (
        <MessagePrimitive.Root>
          <MessagePrimitive.Parts
            components={{
              Text: MarkdownText,
              ChainOfThought, // groups reasoning + tool parts
            }}
          />
        </MessagePrimitive.Root>
      );
    };
    ```
  </Step>

  <Step>
    Use a reasoning model \[#use-a-reasoning-model]

    Chain of Thought is most useful with models that produce reasoning tokens (e.g. OpenAI `o4-mini`). Here's an example backend route using the Vercel AI SDK:

    ```tsx title="app/api/chat/route.ts"
    import { openai } from "@ai-sdk/openai";
    import { streamText, convertToModelMessages } from "ai";

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = streamText({
        model: openai("o4-mini"),
        messages: await convertToModelMessages(messages),
      });

      return result.toUIMessageStreamResponse();
    }
    ```
  </Step>
</Steps>

API Reference \[#api-reference]

ChainOfThoughtPrimitive.Root \[#chainofthoughtprimitiveroot]

Container element for the chain of thought group. Renders a `<div>`.

ChainOfThoughtPrimitive.AccordionTrigger \[#chainofthoughtprimitiveaccordiontrigger]

A button that toggles the collapsed/expanded state. Collapsed by default.

ChainOfThoughtPrimitive.Parts \[#chainofthoughtprimitiveparts]

Renders the grouped parts when expanded (nothing when collapsed).

```tsx
<AuiIf condition={(s) => !s.chainOfThought.collapsed}>
  <ChainOfThoughtPrimitive.Parts
    components={{
      Reasoning,
      tools: { Fallback: ToolFallback },
      Layout: ({ children }) => (
        <div className="border-l-2 border-muted pl-4">{children}</div>
      ),
    }}
  />
</AuiIf>
```

| Prop                        | Type                               | Description                                               |
| --------------------------- | ---------------------------------- | --------------------------------------------------------- |
| `components.Reasoning`      | `FC<{ text: string }>`             | Component to render reasoning parts                       |
| `components.tools.Fallback` | `ToolCallMessagePartComponent`     | Fallback component for tool-call parts                    |
| `components.Layout`         | `ComponentType<PropsWithChildren>` | Wrapper component around each rendered part when expanded |

Reading Collapsed State \[#reading-collapsed-state]

Use `AuiIf` to conditionally render based on the accordion state:

```tsx
import { AuiIf, ChainOfThoughtPrimitive } from "@assistant-ui/react";
import { ChevronDownIcon, ChevronRightIcon } from "lucide-react";

const ChainOfThoughtAccordionTrigger = () => {
  return (
    <ChainOfThoughtPrimitive.AccordionTrigger className="flex w-full cursor-pointer items-center gap-2 px-4 py-2 text-sm">
      <AuiIf condition={(s) => s.chainOfThought.collapsed}>
        <ChevronRightIcon className="size-4" />
      </AuiIf>
      <AuiIf condition={(s) => !s.chainOfThought.collapsed}>
        <ChevronDownIcon className="size-4" />
      </AuiIf>
      Thinking
    </ChainOfThoughtPrimitive.AccordionTrigger>
  );
};
```

Full Example \[#full-example]

See the complete [with-chain-of-thought example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-chain-of-thought) for a working implementation with tool calls and reasoning.

Related Guides \[#related-guides]

* [Generative UI](/docs/guides/tool-ui) — Custom UI for tool calls
* [Tools](/docs/guides/tools) — Defining and using tools


# Context API
URL: /docs/guides/context-api

Read and update assistant state to build custom components.

The Context API provides direct access to assistant-ui's state management system, enabling you to build custom components that integrate seamlessly with the assistant runtime.

Introduction \[#introduction]

The Context API is assistant-ui's powerful state management system that enables you to build custom components with full access to the assistant's state and capabilities. It provides:

* **Reactive state access** - Subscribe to state changes with automatic re-renders
* **Action execution** - Trigger operations like sending messages or reloading responses
* **Event listening** - React to user interactions and system events
* **Scope-aware design** - Components automatically know their context (message, thread, etc.)

It's the foundation that powers all assistant-ui primitives. When the built-in components don't meet your needs, you can use the Context API to create custom components with the same capabilities.

The Context API is backed by the runtime you provide to `<AssistantRuntimeProvider>`. This runtime acts as a unified store that manages all assistant state, handles actions, and dispatches events across your entire application.

Core Concepts \[#core-concepts]

Scopes and Hierarchy \[#scopes-and-hierarchy]

assistant-ui organizes state into **scopes** - logical boundaries that provide access to relevant data and actions. Each scope corresponds to a specific part of the chat interface and automatically provides context-aware functionality.

```
🗂️  ThreadList (threads) - Manages the list of conversations
    ├── 📄 ThreadListItem (threadListItem) - Individual thread in the list
    └── 💬 Thread (thread) - Active conversation with messages
        ├── 🔵 Message (message) - User or assistant message
        │   ├── 📝 Part (part) - Content within a message (text, tool calls, etc.)
        │   ├── 📎 Attachment (attachment) - Files attached to messages
        │   └── ✏️  Composer (composer) - Edit mode for existing messages
        │       └── 📎 Attachment (attachment) - Files in edit mode
        └── ✏️  Composer (composer) - New message input
            └── 📎 Attachment (attachment) - Files being added

🔧 Tools (tools) - Custom UI components for tool calls
```

**How scopes work:**

* Scopes are **automatically determined** by where your component is rendered
* A button inside a `<ThreadPrimitive.Messages>` automatically gets `message` scope
* A button inside a `<ComposerPrimitive.Attachments>` automatically gets `attachment` scope
* Child scopes can access parent scope data (e.g., a `message` component can access `thread` data)

```tsx
// Inside a message component
function MessageButton() {
  // ✅ Available: message scope (current message)
  const role = useAuiState((s) => s.message.role);

  // ✅ Available: thread scope (parent)
  const isRunning = useAuiState((s) => s.thread.isRunning);
}
```

State Management Model \[#state-management-model]

The Context API follows a predictable state management pattern:

1. **State** is immutable and flows down through scopes
2. **Actions** are methods that trigger state changes
3. **Events** notify components of state changes and user interactions
4. **Subscriptions** let components react to changes

Essential Hooks \[#essential-hooks]

useAuiState \[#useauistate]

Read state reactively with automatic re-renders when values change. This hook works like Zustand's selector pattern - you provide a function that extracts the specific data you need, and your component only re-renders when that data changes.

```tsx
import { useAuiState } from "@assistant-ui/react";

// Basic usage - extract a single property
const role = useAuiState((s) => s.message.role); // "user" | "assistant"
const isRunning = useAuiState((s) => s.thread.isRunning); // boolean

// Access nested data
const attachmentCount = useAuiState(
  (s) => s.composer.attachments.length,
);
const lastMessage = useAuiState((s) => s.thread.messages.at(-1));
```

The selector function receives all available scopes for your component's location and should return a specific value. The component re-renders only when that returned value changes.

**Common patterns:**

```tsx
// Access multiple scopes
const canSend = useAuiState(
  (s) => !s.thread.isRunning && s.composer.text.length > 0,
);

// Compute derived state
const messageCount = useAuiState((s) => s.thread.messages.length);
```

**Important:** Never create new objects in selectors. Return primitive values or stable references to avoid infinite re-renders.

```tsx
// ❌ Bad - creates new object every time
const data = useAuiState((s) => ({
  role: s.message.role,
  content: s.message.content,
}));

// ✅ Good - returns stable values
const role = useAuiState((s) => s.message.role);
const content = useAuiState((s) => s.message.content);
```

useAui \[#useaui]

Access the API instance for imperative operations and actions. Unlike `useAuiState`, this hook returns a stable object that never changes, making it perfect for event handlers and imperative operations.

```tsx
import { useAui } from "@assistant-ui/react";

function CustomMessageActions() {
  const aui = useAui();

  // Perform actions in event handlers
  const handleSend = () => {
    aui.composer().send();
  };

  const handleReload = () => {
    aui.message().reload();
  };

  // Read state imperatively when needed
  const handleConditionalAction = () => {
    const { isRunning } = aui.thread().getState();
    const { text } = aui.composer().getState();

    if (!isRunning && text.length > 0) {
      aui.composer().send();
    }
  };

  return (
    <div>
      <button onClick={handleSend}>Send</button>
      <button onClick={handleReload}>Reload</button>
      <button onClick={handleConditionalAction}>Smart Send</button>
    </div>
  );
}
```

The API object is stable and doesn't cause re-renders. Use it for:

* **Triggering actions** in event handlers and callbacks
* **Reading current state** imperatively when you don't need subscriptions
* **Accessing nested scopes** programmatically
* **Checking scope availability** before performing actions

**Available actions by scope:**

```tsx
// Thread actions
aui.thread().append(message);
aui.thread().startRun(config);
aui.thread().cancelRun();
aui.thread().switchToNewThread();
aui.thread().switchToThread(threadId);
aui.thread().getState();
aui.thread().message(idOrIndex);
aui.thread().composer;

// Message actions
aui.message().reload();
aui.message().speak();
aui.message().stopSpeaking();
aui.message().submitFeedback({ type: "positive" | "negative" });
aui.message().switchToBranch({ position, branchId });
aui.message().getState();
aui.message().part(indexOrToolCallId);
aui.message().composer;

// Part actions
api.part().addResult(result);
api.part().getState();

// Composer actions
aui.composer().send();
aui.composer().setText(text);
aui.composer().setRole(role);
aui.composer().addAttachment(file); // File object
aui.composer().addAttachment({ name, content }); // external source
aui.composer().clearAttachments();
aui.composer().reset();
aui.composer().getState();

// Attachment actions
aui.attachment().remove();
aui.attachment().getState();

// ThreadList actions
aui.threads().switchToNewThread();
aui.threads().switchToThread(threadId);
aui.threads().getState();

// ThreadListItem actions
aui.threadListItem().switchTo();
aui.threadListItem().rename(title);
aui.threadListItem().archive();
aui.threadListItem().unarchive();
aui.threadListItem().delete();
aui.threads().getState();

// Tools actions
aui.tools().setToolUI(toolName, render);
aui.tools().getState();
```

useAuiEvent \[#useauievent]

Subscribe to events with automatic cleanup on unmount. This hook is perfect for reacting to user interactions, system events, or integrating with external analytics.

```tsx
import { useAuiEvent } from "@assistant-ui/react";

// Listen to current scope events (most common)
useAuiEvent("composer.send", (event) => {
  console.log("Current composer sent message:", event.message);
});

// Listen to all events of a type across all scopes
useAuiEvent({ event: "composer.send", scope: "*" }, (event) => {
  console.log("Any composer sent a message:", event);
});

// Listen to ALL events (useful for debugging or analytics)
useAuiEvent("*", (event) => {
  console.log("Event occurred:", event.type, "from:", event.source);
  // Send to analytics, logging, etc.
});

// Practical example: Track user interactions
function AnalyticsTracker() {
  useAuiEvent("composer.send", (event) => {
    analytics.track("message_sent", {
      messageLength: event.message.content.length,
      hasAttachments: event.message.attachments.length > 0,
    });
  });

  return null; // This component only tracks events
}
```

**Event name patterns:**

* Event names follow `source.action` format in camelCase (e.g., `composer.send`, `thread.runStart`)
* Use `"*"` as the event name to listen to all events
* The `scope` parameter controls which instances trigger the event

Working with Scopes \[#working-with-scopes]

Available Scopes \[#available-scopes]

Each scope provides access to specific state and actions:

* **ThreadList** (`threads`): Collection and management of threads
* **ThreadListItem** (`threadListItem`): Individual thread in the list
* **Thread** (`thread`): Conversation with messages
* **Message** (`message`): Individual message (user or assistant)
* **Part** (`part`): Content part within a message (text, tool calls, etc.)
* **Composer** (`composer`): Text input for sending or editing messages
* **Attachment** (`attachment`): File or media attached to a message or composer
* **Tools** (`tools`): Tool UI components

Scope Resolution \[#scope-resolution]

The Context API automatically resolves the current scope based on component location:

```tsx
function MessageButton() {
  const aui = useAui();

  // Automatically uses the current message scope
  const handleReload = () => {
    aui.message().reload();
  };

  return <button onClick={handleReload}>Reload</button>;
}
```

Checking Scope Availability \[#checking-scope-availability]

Before accessing a scope, check if it's available:

```tsx
const aui = useAui();

// Check if message scope exists
if (api.message.source) {
  // Safe to use message scope
  const { role } = aui.message().getState();
}
```

Accessing Nested Scopes \[#accessing-nested-scopes]

Navigate through the scope hierarchy programmatically:

```tsx
const aui = useAui();

// Access specific message by ID or index
const messageById = aui.thread().message({ id: "msg_123" });
const messageByIndex = aui.thread().message({ index: 0 });

// Access part by index or tool call ID
const partByIndex = aui.message().part({ index: 0 });
const partByToolCall = aui.message().part({ toolCallId: "call_123" });

// Access attachment by index
const attachment = aui.composer().attachment({ index: 0 }).getState();

// Access thread from thread list
const thread = aui.threads().thread("main");
const threadItem = aui.threads().item({ id: "thread_123" });
```

Common Patterns \[#common-patterns]

Conditional Rendering \[#conditional-rendering]

```tsx
function RunIndicator() {
  const isRunning = useAuiState((s) => s.thread.isRunning);

  if (!isRunning) return null;
  return <div>Assistant is thinking...</div>;
}
```

Custom Action Buttons \[#custom-action-buttons]

```tsx
function CopyButton() {
  const aui = useAui();

  const handleCopy = () => {
    navigator.clipboard.writeText(aui.message().getCopyText());
  };

  return <button onClick={handleCopy}>Copy</button>;
}
```

State-Aware Components \[#state-aware-components]

```tsx
function SmartComposer() {
  const aui = useAui();
  const isRunning = useAuiState((s) => s.thread.isRunning);
  const text = useAuiState((s) => s.composer.text);

  const canSend = !isRunning && text.length > 0;

  return (
    <div>
      <textarea
        value={text}
        onChange={(e) => aui.composer().setText(e.target.value)}
        disabled={isRunning}
      />
      <button onClick={() => aui.composer().send()} disabled={!canSend}>
        Send
      </button>
    </div>
  );
}
```

Event-Driven Updates \[#event-driven-updates]

```tsx
function MessageCounter() {
  const [sendCount, setSendCount] = useState(0);

  useAuiEvent("composer.send", () => {
    setSendCount((c) => c + 1);
  });

  return <div>Messages sent: {sendCount}</div>;
}
```

Advanced Topics \[#advanced-topics]

Resolution Dynamics \[#resolution-dynamics]

When you call `api.scope()`, the API resolves the current scope at that moment. This resolution happens each time you call the function, which matters when dealing with changing contexts:

```tsx
const aui = useAui();

// Get current thread
const thread1 = aui.thread();
thread1.append({ role: "user", content: "Hello" });

// User might switch threads here

// This could be a different thread
const thread2 = aui.thread();
thread2.cancelRun(); // Cancels the current thread's run, not necessarily thread1's
```

For most use cases, this behavior is intuitive. In advanced scenarios where you need to track specific instances, store the resolved reference.

Performance Optimization \[#performance-optimization]

**Selector optimization:**

```tsx
// ❌ Expensive computation in selector (runs on every store update)
const result = useAuiState(
  (s) => s.thread.messages.filter((m) => m.role === "user").length,
);

// ✅ Memoize expensive computations
const messages = useAuiState((s) => s.thread.messages);
const userCount = useMemo(
  () => messages.filter((m) => m.role === "user").length,
  [messages],
);
```

**Minimize re-renders:**

```tsx
// ❌ Subscribes to entire thread state
const thread = useAuiState((s) => s.thread);

// ✅ Subscribe only to needed values
const isRunning = useAuiState((s) => s.thread.isRunning);
```

API Reference \[#api-reference]

Hooks \[#hooks]

| Hook                          | Purpose                    | Returns        |
| ----------------------------- | -------------------------- | -------------- |
| `useAuiState(selector)`       | Subscribe to state changes | Selected value |
| `useAui()`                    | Get API instance           | API object     |
| `useAuiEvent(event, handler)` | Subscribe to events        | void           |

Scope States \[#scope-states]

| Scope          | Key State Properties                                                              | Description                                      |
| -------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
| ThreadList     | `mainThreadId`, `threadIds`, `isLoading`, `threadItems`                           | Manages all available conversation threads       |
| ThreadListItem | `id`, `title`, `status`, `remoteId`, `externalId`                                 | Individual thread metadata and status            |
| Thread         | `isRunning`, `isLoading`, `isDisabled`, `messages`, `capabilities`, `suggestions` | Active conversation state and message history    |
| Message        | `role`, `content`, `status`, `attachments`, `parentId`, `branchNumber`, `isLast`  | Individual message content and metadata          |
| Composer       | `text`, `role`, `attachments`, `isEmpty`, `canCancel`, `type`, `isEditing`        | Text input state for new/edited messages         |
| Part           | `type`, `content`, `status`, `text`, `toolCallId`, `toolName`                     | Content parts within messages (text, tool calls) |
| Attachment     | `id`, `type`, `name`, `url`, `size`, `mimeType`                                   | File attachments metadata and content            |

Available Actions by Scope \[#available-actions-by-scope]

| Scope          | Actions                                                                   | Use Cases                                 |
| -------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
| ThreadList     | `switchToNewThread()`, `switchToThread(id)`, `getState()`                 | Thread navigation and creation            |
| ThreadListItem | `switchTo()`, `rename(title)`, `archive()`, `unarchive()`, `delete()`     | Thread management operations              |
| Thread         | `append(message)`, `startRun()`, `cancelRun()`, `switchToNewThread()`     | Message handling and conversation control |
| Message        | `reload()`, `speak()`, `stopSpeaking()`, `submitFeedback(feedback)`       | Message interactions and regeneration     |
| Composer       | `send()`, `setText(text)`, `addAttachment(file \| attachment)`, `reset()` | Text input and message composition        |
| Part           | `addResult(result)`, `getState()`                                         | Tool call result handling                 |
| Attachment     | `remove()`, `getState()`                                                  | File management                           |

Common Events \[#common-events]

| Event                         | Description                   |
| ----------------------------- | ----------------------------- |
| `thread.runStart`             | Assistant starts generating   |
| `thread.runEnd`               | Assistant finishes generating |
| `thread.initialize`           | Thread is initialized         |
| `thread.modelContextUpdate`   | Model context is updated      |
| `composer.send`               | Message is sent               |
| `composer.attachmentAdd`      | Attachment added to composer  |
| `threadListItem.switchedTo`   | Switched to a thread          |
| `threadListItem.switchedAway` | Switched away from a thread   |

Troubleshooting \[#troubleshooting]

Common Errors \[#common-errors]

**"Cannot access \[scope] outside of \[scope] context"**

```tsx
// ❌ This will throw if not inside a message component
const role = useAuiState((s) => s.message.role);

// ✅ Check scope availability first
function SafeMessageButton() {
  const aui = useAui();

  const role = useAuiState((s) =>
    api.message.source !== undefined ? s.message.role : "none",
  );

  return <div>Role: {role}</div>;
}
```

**"Maximum update depth exceeded" / Infinite re-renders**

```tsx
// ❌ Creating new objects in selectors causes infinite re-renders
const data = useAuiState((s) => ({
  role: s.message.role,
  content: s.message.content, // New object every time!
}));

// ✅ Return primitive values or use separate selectors
const role = useAuiState((s) => s.message.role);
const content = useAuiState((s) => s.message.content);
```

**"Scope resolution failed" / Stale scope references**

```tsx
// ❌ Storing scope references can lead to stale data
const aui = useAui();
const thread = aui.thread(); // This reference might become stale

useEffect(() => {
  // This might reference the wrong thread if user switched
  thread.cancelRun();
}, [thread]);

// ✅ Resolve scopes fresh each time
const aui = useAui();

useEffect(() => {
  // Always gets the current thread
  aui.thread().cancelRun();
}, [aui]);
```

Quick Reference \[#quick-reference]

```tsx
// Read state
const value = useAuiState((s) => s.scope.property);

// Perform action
const aui = useAui();
api.scope().action();

// Listen to events
useAuiEvent("source.event", (e) => {});

// Check scope availability
if (api.scope.source) {
  /* scope exists */
}

// Get state imperatively
const state = api.scope().getState();

// Navigate scopes
aui.thread().message({ id: "..." }).getState();
```


# Speech-to-Text (Dictation)
URL: /docs/guides/dictation

import { DictationSample } from "@/components/docs/samples/dictation";

assistant-ui supports speech-to-text (dictation) via the `DictationAdapter` interface. This allows users to input messages using their voice.

<DictationSample />

DictationAdapter \[#dictationadapter]

Currently, the following dictation adapters are supported:

* `WebSpeechDictationAdapter`: Uses the browser's `Web Speech API` (SpeechRecognition)

The `WebSpeechDictationAdapter` is supported in Chrome, Edge, and Safari. Check [browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#browser_compatibility) for details.

Configuration \[#configuration]

```tsx
import { WebSpeechDictationAdapter } from "@assistant-ui/react";

const runtime = useChatRuntime({
  adapters: {
    dictation: new WebSpeechDictationAdapter({
      // Optional configuration
      language: "en-US",         // Language for recognition (default: browser language)
      continuous: true,          // Keep recording after user stops (default: true)
      interimResults: true,      // Return interim results (default: true)
    }),
  },
});
```

UI \[#ui]

The dictation feature uses `ComposerPrimitive.Dictate` and `ComposerPrimitive.StopDictation` components.

```tsx
import { ComposerPrimitive } from "@assistant-ui/react";
import { MicIcon, SquareIcon } from "lucide-react";

const ComposerWithDictation = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.Input />

    {/* Show Dictate button when not dictating */}
    <ComposerPrimitive.If dictation={false}>
      <ComposerPrimitive.Dictate>
        <MicIcon />
      </ComposerPrimitive.Dictate>
    </ComposerPrimitive.If>

    {/* Show Stop button when dictating */}
    <ComposerPrimitive.If dictation>
      <ComposerPrimitive.StopDictation>
        <SquareIcon className="animate-pulse" />
      </ComposerPrimitive.StopDictation>
    </ComposerPrimitive.If>

    <ComposerPrimitive.Send />
  </ComposerPrimitive.Root>
);
```

Browser Compatibility Check \[#browser-compatibility-check]

You can check if the browser supports dictation:

```tsx
import { WebSpeechDictationAdapter } from "@assistant-ui/react";

if (WebSpeechDictationAdapter.isSupported()) {
  // Dictation is available
}
```

Disabling Input During Dictation \[#disabling-input-during-dictation]

Some dictation services (like ElevenLabs Scribe) return cumulative transcripts that conflict with simultaneous typing. You can disable the text input during dictation:

```tsx
import type { DictationAdapter } from "@assistant-ui/react";

class MyAdapter implements DictationAdapter {
  // Set to true to disable typing while dictating
  disableInputDuringDictation = true;

  listen() { /* ... */ }
}
```

<Callout type="info">
  When a message is sent during an active dictation session, the session is automatically stopped.
</Callout>

Custom Adapters \[#custom-adapters]

You can create custom adapters to integrate with any dictation service by implementing the `DictationAdapter` interface.

DictationAdapter Interface \[#dictationadapter-interface]

```tsx
import type { DictationAdapter } from "@assistant-ui/react";

class MyCustomDictationAdapter implements DictationAdapter {
  // Optional: disable text input while dictating (default: false)
  disableInputDuringDictation?: boolean;

  listen(): DictationAdapter.Session {
    // Return a session object that manages the dictation
    return {
      status: { type: "starting" },

      stop: async () => {
        // Stop recognition and finalize results
      },

      cancel: () => {
        // Cancel recognition without finalizing
      },

      onSpeechStart: (callback) => {
        // Called when speech is detected
        return () => {}; // Return unsubscribe function
      },

      onSpeechEnd: (callback) => {
        // Called when recognition ends with final result
        return () => {};
      },

      onSpeech: (callback) => {
        // Called with transcription results
        // callback({ transcript: "text", isFinal: true })
        //
        // isFinal: true  → Append to composer input (default)
        // isFinal: false → Show as preview only
        return () => {};
      },
    };
  }
}
```

Interim vs Final Results \[#interim-vs-final-results]

The `onSpeech` callback receives results with an optional `isFinal` flag:

```tsx
onSpeech: (callback) => {
  // callback({ transcript: "text", isFinal: true })
  // - isFinal: true  → Text is committed to the input
  // - isFinal: false → Text is shown as preview in the input
  return () => {};
},
```

**Both interim and final results are displayed directly in the input field**, just like native dictation on iOS/Android. Interim results replace each other until a final result commits the text. This provides seamless real-time feedback while the user speaks.

Example: ElevenLabs Scribe v2 Realtime \[#example-elevenlabs-scribe-v2-realtime]

[ElevenLabs Scribe](https://elevenlabs.io/docs/capabilities/speech-to-text) provides ultra-low latency (\~150ms) real-time transcription via WebSocket.

Install Dependencies \[#install-dependencies]

```bash
npm install @elevenlabs/client
```

Backend API Route \[#backend-api-route]

Create an API route to generate single-use tokens:

```ts title="app/api/scribe-token/route.ts"
export async function POST() {
  const response = await fetch(
    "https://api.elevenlabs.io/v1/single-use-token/realtime_scribe",
    {
      method: "POST",
      headers: {
        "xi-api-key": process.env.ELEVENLABS_API_KEY!,
      },
    }
  );

  const data = await response.json();
  return Response.json({ token: data.token });
}
```

Frontend Adapter \[#frontend-adapter]

```tsx title="lib/elevenlabs-scribe-adapter.ts"
import type { DictationAdapter } from "@assistant-ui/react";
import { Scribe, RealtimeEvents } from "@elevenlabs/client";

export class ElevenLabsScribeAdapter implements DictationAdapter {
  private tokenEndpoint: string;
  private languageCode: string;

  // ElevenLabs returns cumulative transcripts, so we disable typing during dictation
  public disableInputDuringDictation: boolean;

  constructor(options: {
    tokenEndpoint: string;
    languageCode?: string;
    disableInputDuringDictation?: boolean;
  }) {
    this.tokenEndpoint = options.tokenEndpoint;
    this.languageCode = options.languageCode ?? "en";
    this.disableInputDuringDictation = options.disableInputDuringDictation ?? true;
  }

  listen(): DictationAdapter.Session {
    const callbacks = {
      start: new Set<() => void>(),
      end: new Set<(r: DictationAdapter.Result) => void>(),
      speech: new Set<(r: DictationAdapter.Result) => void>(),
    };

    let connection: ReturnType<typeof Scribe.connect> | null = null;
    let fullTranscript = "";

    const session: DictationAdapter.Session = {
      status: { type: "starting" },

      stop: async () => {
        if (connection) {
          connection.commit();
          await new Promise((r) => setTimeout(r, 500));
          connection.close();
        }
        if (fullTranscript) {
          for (const cb of callbacks.end) cb({ transcript: fullTranscript });
        }
      },

      cancel: () => {
        connection?.close();
      },

      onSpeechStart: (cb) => {
        callbacks.start.add(cb);
        return () => callbacks.start.delete(cb);
      },

      onSpeechEnd: (cb) => {
        callbacks.end.add(cb);
        return () => callbacks.end.delete(cb);
      },

      onSpeech: (cb) => {
        callbacks.speech.add(cb);
        return () => callbacks.speech.delete(cb);
      },
    };

    this.connect(session, callbacks, {
      setConnection: (c) => { connection = c; },
      getFullTranscript: () => fullTranscript,
      setFullTranscript: (t) => { fullTranscript = t; },
    });

    return session;
  }

  private async connect(
    session: DictationAdapter.Session,
    callbacks: {
      start: Set<() => void>;
      end: Set<(r: DictationAdapter.Result) => void>;
      speech: Set<(r: DictationAdapter.Result) => void>;
    },
    refs: {
      setConnection: (c: ReturnType<typeof Scribe.connect>) => void;
      getFullTranscript: () => string;
      setFullTranscript: (t: string) => void;
    }
  ) {
    try {
      // 1. Get token from backend
      const tokenRes = await fetch(this.tokenEndpoint, { method: "POST" });
      const { token } = await tokenRes.json();

      // 2. Connect to Scribe with microphone
      const connection = Scribe.connect({
        token,
        modelId: "scribe_v2_realtime",
        languageCode: this.languageCode,
        microphone: {
          echoCancellation: true,
          noiseSuppression: true,
        },
      });
      refs.setConnection(connection);

      // 3. Handle events
      connection.on(RealtimeEvents.SESSION_STARTED, () => {
        (session as { status: DictationAdapter.Status }).status = {
          type: "running",
        };
        for (const cb of callbacks.start) cb();
      });

      // Partial transcripts → preview (isFinal: false)
      connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => {
        if (data.text) {
          for (const cb of callbacks.speech)
            cb({ transcript: data.text, isFinal: false });
        }
      });

      // Committed transcripts → append to input (isFinal: true)
      connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
        if (data.text?.trim()) {
          refs.setFullTranscript(refs.getFullTranscript() + data.text + " ");
          for (const cb of callbacks.speech)
            cb({ transcript: data.text, isFinal: true });
        }
      });

      connection.on(RealtimeEvents.ERROR, (error) => {
        console.error("Scribe error:", error);
        (session as { status: DictationAdapter.Status }).status = {
          type: "ended",
          reason: "error",
        };
      });

    } catch (error) {
      console.error("ElevenLabs Scribe connection failed:", error);
      (session as { status: DictationAdapter.Status }).status = {
        type: "ended",
        reason: "error",
      };
    }
  }
}
```

Usage \[#usage]

```tsx
const runtime = useChatRuntime({
  adapters: {
    dictation: new ElevenLabsScribeAdapter({
      tokenEndpoint: "/api/scribe-token",
      languageCode: "en", // Optional: supports 90+ languages
      disableInputDuringDictation: true, // Default: true (recommended for ElevenLabs)
    }),
  },
});
```

Real-time Preview \[#real-time-preview]

The transcription is displayed directly in the input field as the user speaks — just like native dictation. No additional UI components are needed for basic use cases.

<Callout type="info">
  For advanced customization, `composer.dictation?.transcript` contains the current interim transcript, and `ComposerPrimitive.DictationTranscript` can display it separately if desired.
</Callout>

<Callout type="info">
  For more details, see the [ElevenLabs Scribe documentation](https://elevenlabs.io/docs/capabilities/speech-to-text).
</Callout>


# Message Editing
URL: /docs/guides/editing

Allow users to edit their messages with custom editor interfaces.

Give the user the ability to edit their message.

Enabling edit support \[#enabling-edit-support]

You can show an editor interface by using `ComposerPrimitive`.

```tsx {1,11,25,31-43}
import { ComposerPrimitive } from "@assistant-ui/react";
...

const Thread = () => {
  return (
    <ThreadPrimitive.Root>
      <ThreadPrimitive.Viewport>
        ...
        <ThreadPrimitive.Messages components={{
          ...,
          EditComposer, // <-- Show our new component during edit mode
        }} />
      </ThreadPrimitive.Viewport>
      ...
    </ThreadPrimitive.Root>
  );
};

const UserMessage = () => {
  return (
    <MessagePrimitive.Root>
      ...
      <ActionBarPrimitive.Root>
        ...
        <ActionBarPrimitive.Edit /> {/* <-- add a button to enable edit mode */}
      </ActionBarPrimitive.Root>
    </MessagePrimitive.Root>
  );
};

// define a new component
const EditComposer = () => {
  return (
    // you can return a MessagePrimitive including a ComposerPrimitive, or only a ComposerPrimitive
    <MessagePrimitive.Root>
      ...
      <ComposerPrimitive.Root>
        <ComposerPrimitive.Input />
        <ComposerPrimitive.Cancel />
        <ComposerPrimitive.Send />
      </ComposerPrimitive.Root>
    </MessagePrimitive.Root>
  );
};
```


# LaTeX
URL: /docs/guides/latex

Render mathematical expressions in chat messages using KaTeX.

Render LaTeX mathematical expressions in chat messages using KaTeX.

<Callout type="warn">
  LaTeX rendering is not enabled in markdown by default.
</Callout>

<Steps>
  <Step>
    Install dependencies \[#install-dependencies]

    ```bash
    npm i katex rehype-katex remark-math
    ```
  </Step>

  <Step>
    Add KaTeX CSS to your layout \[#add-katex-css-to-your-layout]

    ```tsx title="/app/layout.tsx"
    import "katex/dist/katex.min.css"; // [!code ++]
    ```
  </Step>

  <Step>
    Update markdown-text.tsx \[#update-markdown-texttsx]

    ```tsx title="/components/assistant-ui/markdown-text.tsx"
    import remarkMath from "remark-math";     // [!code ++]
    import rehypeKatex from "rehype-katex";   // [!code ++]

    const MarkdownTextImpl = () => {
      return (
        <MarkdownTextPrimitive
          remarkPlugins={[remarkGfm, remarkMath]} // add remarkMath // [!code ++]
          rehypePlugins={[rehypeKatex]}           // add rehypeKatex // [!code ++]
          className="aui-md"
          components={defaultComponents}
        />
      );
    };

    export const MarkdownText = memo(MarkdownTextImpl);
    ```
  </Step>
</Steps>

Supported Formats \[#supported-formats]

By default, remark-math supports:

* `$...$` for inline math
* `$$...$$` for display math
* Fenced code blocks with the `math` language identifier

Supporting Alternative LaTeX Delimiters \[#supporting-alternative-latex-delimiters]

Many language models generate LaTeX using different delimiter formats:

* `\(...\)` for inline math
* `\[...\]` for display math
* Custom formats like `[/math]...[/math]`

You can use the `preprocess` prop to normalize these formats:

```tsx title="/components/assistant-ui/markdown-text.tsx"
const MarkdownTextImpl = () => {
  return (
    <MarkdownTextPrimitive
      remarkPlugins={[remarkGfm, remarkMath]}
      rehypePlugins={[rehypeKatex]}
      preprocess={normalizeCustomMathTags} // [!code ++]
      className="aui-md"
      components={defaultComponents}
    />
  );
};

// Your LaTeX preprocessing function
function normalizeCustomMathTags(input: string): string {
  return (
    input
      // Convert [/math]...[/math] to $$...$$
      .replace(/\[\/math\]([\s\S]*?)\[\/math\]/g, (_, content) => `$$${content.trim()}$$`)

      // Convert [/inline]...[/inline] to $...$
      .replace(/\[\/inline\]([\s\S]*?)\[\/inline\]/g, (_, content) => `$${content.trim()}$`)

      // Convert \( ... \) to $...$ (inline math) - handles both single and double backslashes
      .replace(/\\{1,2}\(([\s\S]*?)\\{1,2}\)/g, (_, content) => `$${content.trim()}$`)

      // Convert \[ ... \] to $$...$$ (block math) - handles both single and double backslashes
      .replace(/\\{1,2}\[([\s\S]*?)\\{1,2}\]/g, (_, content) => `$$${content.trim()}$$`)
  );
}
```

<Callout type="tip">
  The preprocessing function runs before markdown parsing, allowing you to transform any delimiter format into the standard `$` and `$$` format.
</Callout>


# Message Timing
URL: /docs/guides/message-timing

Display stream timing metadata like duration, tokens per second, and time to first token.

Display stream performance metrics — duration, tokens per second, TTFT — on assistant messages.

<Callout type="info">
  The [`MessageTiming`](/docs/ui/message-timing) registry component provides a ready-made badge + popover UI. This guide covers the underlying `useMessageTiming()` hook for custom implementations and runtime-specific setup.
</Callout>

Reading Timing Data \[#reading-timing-data]

Use `useMessageTiming()` inside a message component to access timing data:

```tsx
import { useMessageTiming } from "@assistant-ui/react";

const MessageTimingDisplay: FC = () => {
  const timing = useMessageTiming();
  if (!timing?.totalStreamTime) return null;

  const formatMs = (ms: number) =>
    ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;

  return (
    <span className="text-xs text-muted-foreground">
      {formatMs(timing.totalStreamTime)}
      {timing.tokensPerSecond !== undefined &&
        ` · ${timing.tokensPerSecond.toFixed(1)} tok/s`}
    </span>
  );
};
```

Place it inside `MessagePrimitive.Root`, typically near the action bar:

```tsx {8}
const AssistantMessage: FC = () => {
  return (
    <MessagePrimitive.Root>
      <MessagePrimitive.Parts components={{ ... }} />
      <ActionBarPrimitive.Root>
        <ActionBarPrimitive.Copy />
        <ActionBarPrimitive.Reload />
        <MessageTimingDisplay />
      </ActionBarPrimitive.Root>
    </MessagePrimitive.Root>
  );
};
```

useMessageTiming() Return Fields \[#usemessagetiming-return-fields]

| Field             | Type      | Description                                                          |
| ----------------- | --------- | -------------------------------------------------------------------- |
| `streamStartTime` | `number`  | Unix timestamp when stream started                                   |
| `firstTokenTime`  | `number?` | Time to first text token (ms)                                        |
| `totalStreamTime` | `number?` | Total stream duration (ms)                                           |
| `tokenCount`      | `number?` | Real or estimated output token count                                 |
| `tokensPerSecond` | `number?` | Throughput (tokens/sec); see [accuracy note](#ai-sdk-usechatruntime) |
| `totalChunks`     | `number`  | Total stream chunks received                                         |
| `toolCallCount`   | `number`  | Number of tool calls                                                 |

Runtime Support \[#runtime-support]

| Runtime                   | Supported | Notes                                        |
| ------------------------- | :-------: | -------------------------------------------- |
| DataStream                |    Yes    | Automatic via `AssistantMessageAccumulator`  |
| AI SDK (`useChatRuntime`) |    Yes    | Automatic via client-side tracking           |
| Local (`useLocalRuntime`) |    Yes    | Pass timing in `ChatModelRunResult.metadata` |
| ExternalStore             |    Yes    | Pass timing in `ThreadMessageLike.metadata`  |
| LangGraph                 |     No    | Not yet implemented                          |
| AG-UI                     |     No    | Not yet implemented                          |

DataStream \[#datastream]

Timing is tracked automatically inside `AssistantMessageAccumulator`. No setup required.

```tsx
import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";

const runtime = useDataStreamRuntime({ api: "/api/chat" });
// useMessageTiming() works out of the box
```

AI SDK (useChatRuntime) \[#ai-sdk-usechatruntime]

Timing is tracked automatically on the client side by observing streaming state transitions and content changes. Timing is finalized when each stream completes.

<Callout type="warn">
  `tokenCount` and `tokensPerSecond` are **estimated** using a 4 characters per token approximation — real token counts from the server are not extracted. This can overcount significantly for short messages.
</Callout>

```tsx
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime();
// useMessageTiming() works out of the box
```

Local (useLocalRuntime) \[#local-uselocalruntime]

Pass timing in the `metadata` field of your `ChatModelRunResult`:

```tsx
import type { ChatModelAdapter } from "@assistant-ui/react";

const myAdapter: ChatModelAdapter = {
  async run({ messages, abortSignal }) {
    const startTime = Date.now();
    const result = await callMyAPI(messages, abortSignal);
    const totalStreamTime = Date.now() - startTime;

    return {
      content: [{ type: "text", text: result.text }],
      metadata: {
        timing: {
          streamStartTime: startTime,
          totalStreamTime,
          tokenCount: result.usage?.completionTokens,
          tokensPerSecond:
            result.usage?.completionTokens
              ? result.usage.completionTokens / (totalStreamTime / 1000)
              : undefined,
          totalChunks: 1,
          toolCallCount: 0,
        },
      },
    };
  },
};
```

ExternalStore (useExternalStoreRuntime) \[#externalstore-useexternalstoreruntime]

Pass timing in the `metadata.timing` field of your `ThreadMessageLike` messages:

```tsx
import type { ThreadMessageLike } from "@assistant-ui/react";

const message: ThreadMessageLike = {
  role: "assistant",
  content: [{ type: "text", text: fullText }],
  metadata: {
    timing: {
      streamStartTime: startTime,
      firstTokenTime,
      totalStreamTime,
      tokenCount,
      tokensPerSecond,
      totalChunks: chunks,
      toolCallCount: 0,
    },
  },
};
```

API Reference \[#api-reference]

useMessageTiming() \[#usemessagetiming]

```tsx
const timing: MessageTiming | undefined = useMessageTiming();
```

Returns timing metadata for the current assistant message, or `undefined` for non-assistant messages or when no timing data is available.

Must be used inside a `MessagePrimitive.Root` context.


# Quote Selected Text
URL: /docs/guides/quoting

Let users select and quote text from messages, similar to Claude's quoting experience.

Allow users to select text in assistant messages and reply with a quote reference — just like Claude, ChatGPT, and other modern AI interfaces.

How It Works \[#how-it-works]

1. User selects text in a message
2. A floating toolbar appears near the selection with a **Quote** button
3. User clicks it — a quote preview appears in the composer
4. User types their reply and sends
5. The sent message displays the quoted text above the user's reply

Quote data is stored in `metadata.custom.quote` and is **not** injected into message content. Your backend decides how to present the quoted context to the LLM.

Quick Start \[#quick-start]

1. Add the Floating Selection Toolbar \[#1-add-the-floating-selection-toolbar]

Place `SelectionToolbarPrimitive` inside your `ThreadPrimitive.Root`. It renders a floating toolbar near the user's text selection — only when text is selected within a message.

```tsx {1,13-20}
import { SelectionToolbarPrimitive, ThreadPrimitive } from "@assistant-ui/react";
import { QuoteIcon } from "lucide-react";

const Thread = () => {
  return (
    <ThreadPrimitive.Root>
      <ThreadPrimitive.Viewport>
        <ThreadPrimitive.Messages components={{ ... }} />
        ...
      </ThreadPrimitive.Viewport>

      {/* Floating toolbar — appears on text selection */}
      <SelectionToolbarPrimitive.Root className="flex items-center gap-1 rounded-lg border bg-popover px-1 py-1 shadow-md">
        <SelectionToolbarPrimitive.Quote className="flex items-center gap-1.5 rounded-md px-2.5 py-1 text-sm hover:bg-accent">
          <QuoteIcon className="size-3.5" />
          Quote
        </SelectionToolbarPrimitive.Quote>
      </SelectionToolbarPrimitive.Root>
    </ThreadPrimitive.Root>
  );
};
```

The `Root` component:

* Listens for `mouseup` and `keyup` events to detect text selections
* Validates the selection is within a single message (cross-message selections are ignored)
* Renders a portal positioned above the selection
* Prevents `mousedown` from clearing the selection when clicking the toolbar
* Hides automatically on scroll or when the selection is cleared

2. Show Quote Preview in Composer \[#2-show-quote-preview-in-composer]

Add `ComposerPrimitive.Quote` inside the composer to show what's being quoted:

```tsx {1,8-13}
import { ComposerPrimitive } from "@assistant-ui/react";

const Composer = () => {
  return (
    <ComposerPrimitive.Root>
      {/* Quote preview — only renders when a quote is set */}
      <ComposerPrimitive.Quote className="flex items-start gap-2 border-l-4 border-primary/40 bg-muted/50 px-3 py-2 text-sm">
        <ComposerPrimitive.QuoteText className="line-clamp-2 flex-1 italic text-muted-foreground" />
        <ComposerPrimitive.QuoteDismiss>
          ×
        </ComposerPrimitive.QuoteDismiss>
      </ComposerPrimitive.Quote>

      <ComposerPrimitive.Input placeholder="Send a message..." />
      <ComposerPrimitive.Send />
    </ComposerPrimitive.Root>
  );
};
```

3. Display Quotes in Sent Messages \[#3-display-quotes-in-sent-messages]

Use `useMessageQuote()` to render quoted text in user messages:

```tsx {1,4-5,11}
import { MessagePrimitive, useMessageQuote } from "@assistant-ui/react";

const QuoteBlock = () => {
  const quote = useMessageQuote();
  if (!quote) return null;

  return (
    <div className="mb-1 border-l-4 border-primary/40 pl-3 text-xs italic text-muted-foreground">
      {quote.text}
    </div>
  );
};

const UserMessage = () => {
  return (
    <MessagePrimitive.Root>
      <QuoteBlock />
      <MessagePrimitive.Parts />
    </MessagePrimitive.Root>
  );
};
```

Backend Handling \[#backend-handling]

The quote is stored in message metadata — **not** in message content. This gives your backend full control over how to present quoted context to the LLM.

Data Shape \[#data-shape]

```typescript
type QuoteInfo = {
  readonly text: string;       // selected plain text
  readonly messageId: string;  // source message ID
};

// Stored at: message.metadata.custom.quote
```

Example: Prepend as Markdown Blockquote \[#example-prepend-as-markdown-blockquote]

A simple approach is to prepend the quoted text as a `>` blockquote before converting to model messages:

```typescript title="app/api/chat/route.ts" {1,9}
import { convertToModelMessages, streamText } from "ai";
import type { UIMessage } from "ai";

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: myModel,
    messages: await convertToModelMessages(injectQuoteContext(messages)),
  });

  return result.toUIMessageStreamResponse();
}

function injectQuoteContext(messages: UIMessage[]): UIMessage[] {
  return messages.map((msg) => {
    const quote = (msg.metadata as Record<string, unknown>)?.custom;
    if (
      !quote ||
      typeof quote !== "object" ||
      !("quote" in (quote as Record<string, unknown>))
    )
      return msg;

    const q = (quote as Record<string, unknown>).quote;
    if (
      !q ||
      typeof q !== "object" ||
      !("text" in (q as Record<string, unknown>))
    )
      return msg;

    const text = (q as { text: unknown }).text;
    if (typeof text !== "string") return msg;

    return {
      ...msg,
      parts: [{ type: "text" as const, text: `> ${text}\n\n` }, ...msg.parts],
    };
  });
}
```

Example: Claude-Style Citation Source \[#example-claude-style-citation-source]

For Claude's API, you can pass the quoted text as a citation source. This enables Claude to produce citations that reference the quoted text:

```typescript title="app/api/chat/route.ts"
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

export async function POST(req: Request) {
  const { messages } = await req.json();

  // Transform messages: extract quotes into Claude source blocks
  const claudeMessages = messages.map((msg) => {
    const quote = msg.metadata?.custom?.quote;
    if (!quote?.text) {
      return { role: msg.role, content: extractText(msg) };
    }

    return {
      role: "user",
      content: [
        {
          type: "text",
          text: quote.text,
          cache_control: { type: "ephemeral" },
          citations: { enabled: true },
        },
        {
          type: "text",
          text: extractText(msg),
        },
      ],
    };
  });

  const response = await client.messages.create({
    model: "claude-sonnet-4-5-20250929",
    max_tokens: 1024,
    messages: claudeMessages,
  });

  // ... stream response back
}
```

Example: OpenAI-Style System Context \[#example-openai-style-system-context]

For OpenAI's API, inject the quote as additional context in the user message:

```typescript title="app/api/chat/route.ts"
function injectQuoteForOpenAI(messages) {
  return messages.map((msg) => {
    const quote = msg.metadata?.custom?.quote;
    if (!quote?.text || msg.role !== "user") return msg;

    return {
      ...msg,
      content: `[Referring to: "${quote.text}"]\n\n${msg.content}`,
    };
  });
}
```

Programmatic API \[#programmatic-api]

You can set or clear quotes programmatically via the composer runtime:

```tsx
import { useAui } from "@assistant-ui/react";

function MyComponent() {
  const aui = useAui();

  const quoteText = () => {
    aui.thread().composer.setQuote({
      text: "The text to quote",
      messageId: "msg-123",
    });
  };

  const clearQuote = () => {
    aui.thread().composer.setQuote(undefined);
  };

  return (
    <>
      <button onClick={quoteText}>Set Quote</button>
      <button onClick={clearQuote}>Clear Quote</button>
    </>
  );
}
```

API Reference \[#api-reference]

SelectionToolbarPrimitive.Root \[#selectiontoolbarprimitiveroot]

A floating container that appears when text is selected within a message. Renders as a portal positioned above the selection.

* Listens for `mouseup` / `keyup` to detect selection
* Validates selection is within a single message
* Hides on scroll or when selection is cleared
* Prevents `mousedown` from clearing the selection
* Provides selection context to child components

SelectionToolbarPrimitive.Quote \[#selectiontoolbarprimitivequote]

A button inside the floating toolbar that captures the selection as a quote.

* Reads selection info from the toolbar context (not `window.getSelection()`)
* Stores `{ text, messageId }` in the thread composer
* Clears the text selection after quoting

ComposerPrimitive.Quote \[#composerprimitivequote]

A container that only renders when a quote is set.

ComposerPrimitive.QuoteText \[#composerprimitivequotetext]

Renders the quoted text. Defaults to `<span>`.

ComposerPrimitive.QuoteDismiss \[#composerprimitivequotedismiss]

A button that clears the quote by calling `setQuote(undefined)`. Supports `asChild`.

useMessageQuote() \[#usemessagequote]

```tsx
const quote: QuoteInfo | undefined = useMessageQuote();
```

Returns the quote attached to the current message, or `undefined`.

ComposerRuntime.setQuote() \[#composerruntimesetquote]

```tsx
setQuote(quote: QuoteInfo | undefined): void
```

Set or clear the quote on the composer. The quote is automatically cleared when the message is sent.

Design Notes \[#design-notes]

* **Single quote** — `setQuote` replaces, not appends. Only one quote at a time.
* **Snapshot text** — The selected text is captured at quote time, not linked to the source message.
* **Cross-message selection** — Rejected. The toolbar only appears when the selection is within a single message.
* **Streaming messages** — The floating toolbar works during streaming since it reads from the captured selection, not message status.
* **`isEmpty` unchanged** — A quote alone doesn't make the composer non-empty. The user must type a reply.
* **Scroll hides toolbar** — The floating toolbar hides when any scroll event occurs, since the position would become stale.

Related \[#related]

* [Message Editing](/docs/guides/editing) — Edit user messages
* [Thread Component](/docs/ui/thread) — Main chat container
* [ComposerPrimitive](/docs/reference/primitives/Composer) — Composer primitive reference
* [ActionBarPrimitive](/docs/reference/primitives/ActionBar) — Action bar primitive reference


# Text-to-Speech (Speech Synthesis)
URL: /docs/guides/speech

Read messages aloud with Web Speech API or custom TTS.

import { SpeechSample } from "@/components/docs/samples/speech";

assistant-ui supports text-to-speech via the `SpeechSynthesisAdapter` interface.

<SpeechSample />

SpeechSynthesisAdapter \[#speechsynthesisadapter]

Currently, the following speech synthesis adapters are supported:

* `WebSpeechSynthesisAdapter`: Uses the browser's `Web Speech API`

Support for other speech synthesis adapters is planned for the future.

Passing a `SpeechSynthesisAdapter` to the runtime will enable text-to-speech support.

UI \[#ui]

By default, a `Read aloud` button will be shown in the assistant message action bar.

This is implemented using `AssistantActionBar.SpeechControl` which is a wrapper around `AssistantActionBar.Speak` and `AssistantActionBar.StopSpeaking`.
The underlying primitives are `ActionBarPrimitive.Speak` and `ActionBarPrimitive.StopSpeaking`.

Example \[#example]

The following example uses the `WebSpeechSynthesisAdapter`.

```tsx
import { WebSpeechSynthesisAdapter } from "@assistant-ui/react";

const runtime = useChatRuntime({
  adapters: {
    speech: new WebSpeechSynthesisAdapter(),
  },
});
```


# Suggestions
URL: /docs/guides/suggestions

Display suggested prompts to help users get started with your assistant.

Suggestions are pre-defined prompts that help users discover what your assistant can do. They appear in the welcome screen and provide a quick way to start conversations.

Overview \[#overview]

The Suggestions API allows you to configure a list of suggested prompts that are displayed when the thread is empty. Users can click on a suggestion to either populate the composer or immediately send the message.

Quick Start \[#quick-start]

Configure suggestions using the `Suggestions()` API in your runtime provider:

```tsx
import { useAui, Tools, Suggestions } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();

  const aui = useAui({
    tools: Tools({ toolkit: myToolkit }),
    suggestions: Suggestions([
      "What can you help me with?",
      "Tell me a joke",
      "Explain quantum computing",
    ]),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

Suggestion Format \[#suggestion-format]

Suggestions can be provided as either strings or objects with title, label, and prompt:

Simple Strings \[#simple-strings]

```tsx
const aui = useAui({
  suggestions: Suggestions([
    "What's the weather today?",
    "Help me write an email",
    "Explain React hooks",
  ]),
});
```

Objects with Title and Description \[#objects-with-title-and-description]

For more detailed suggestions with separate display text and prompts:

```tsx
const aui = useAui({
  suggestions: Suggestions([
    {
      title: "Weather",
      label: "in San Francisco",
      prompt: "What's the weather in San Francisco?",
    },
    {
      title: "React Hooks",
      label: "useState and useEffect",
      prompt: "Explain React hooks like useState and useEffect",
    },
    {
      title: "Travel Tips",
      label: "for Tokyo",
      prompt: "Give me travel tips for visiting Tokyo",
    },
  ]),
});
```

Displaying Suggestions \[#displaying-suggestions]

The default Thread component from the shadcn registry already includes suggestion rendering. The suggestions are displayed in the welcome screen when the thread is empty.

Customizing Suggestion Display \[#customizing-suggestion-display]

If you want to customize how suggestions are displayed, you can modify your Thread component:

```tsx
import {
  ThreadPrimitive,
  SuggestionPrimitive,
  AuiIf,
} from "@assistant-ui/react";

const ThreadWelcome = () => {
  return (
    <div className="flex flex-col items-center justify-center">
      <h1>Welcome!</h1>
      <p>How can I help you today?</p>

      {/* Display suggestions */}
      <div className="grid grid-cols-2 gap-2">
        <ThreadPrimitive.Suggestions
          components={{
            Suggestion: SuggestionItem,
          }}
        />
      </div>
    </div>
  );
};

const SuggestionItem = () => {
  return (
    <SuggestionPrimitive.Trigger send asChild>
      <button className="rounded-lg border p-3 hover:bg-muted">
        <div className="font-medium">
          <SuggestionPrimitive.Title />
        </div>
        <div className="text-muted-foreground text-sm">
          <SuggestionPrimitive.Description />
        </div>
      </button>
    </SuggestionPrimitive.Trigger>
  );
};
```

Suggestion Primitives \[#suggestion-primitives]

ThreadPrimitive.Suggestions \[#threadprimitivesuggestions]

Renders all suggestions from the suggestions scope.

```tsx
<ThreadPrimitive.Suggestions
  components={{
    Suggestion: CustomSuggestionComponent,
  }}
/>
```

SuggestionPrimitive.Title \[#suggestionprimitivetitle]

Displays the suggestion's title (the first part when using object format, or the full text when using strings).

```tsx
<SuggestionPrimitive.Title />
```

SuggestionPrimitive.Description \[#suggestionprimitivedescription]

Displays the suggestion's description/label (only shown when using object format).

```tsx
<SuggestionPrimitive.Description />
```

SuggestionPrimitive.Trigger \[#suggestionprimitivetrigger]

A button that triggers the suggestion action when clicked.

```tsx
<SuggestionPrimitive.Trigger
  send={true}
  clearComposer={true}
  asChild
>
  <button>Click me</button>
</SuggestionPrimitive.Trigger>
```

**Props:**

* `send` (boolean): When true, automatically sends the message. When false, only populates the composer.
* `clearComposer` (boolean, default: true): When `send` is false, determines if the composer is cleared before adding the suggestion (true) or if the suggestion is appended (false).
* `asChild` (boolean): Merge props with child element instead of rendering a button.

Dynamic Suggestions \[#dynamic-suggestions]

You can dynamically change suggestions based on your application state:

```tsx
import { useMemo } from "react";

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();
  const user = useUser(); // Your user hook

  const suggestions = useMemo(() => {
    if (user.isPremium) {
      return [
        "Analyze my business data",
        "Generate a detailed report",
        "Create a custom workflow",
      ];
    }
    return [
      "What can you do?",
      "Tell me a joke",
      "Help me get started",
    ];
  }, [user.isPremium]);

  const aui = useAui({
    tools: Tools({ toolkit: myToolkit }),
    suggestions: Suggestions(suggestions),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

Context-Aware Suggestions \[#context-aware-suggestions]

Suggestions can be tailored to different contexts or user intents:

```tsx
const suggestions = [
  {
    title: "Code Review",
    label: "Get feedback on your code",
    prompt: "Can you review this code for me?",
  },
  {
    title: "Debug Help",
    label: "Find and fix issues",
    prompt: "Help me debug this error",
  },
  {
    title: "Best Practices",
    label: "Learn recommended patterns",
    prompt: "What are the best practices for this?",
  },
];
```

Best Practices \[#best-practices]

1. **Keep suggestions concise**: Use clear, actionable prompts that users can understand at a glance
2. **Show capabilities**: Use suggestions to highlight your assistant's key features
3. **Provide variety**: Offer suggestions across different use cases
4. **Use the object format for complex suggestions**: When you need separate title/description, use the object format
5. **Limit the number**: 3-6 suggestions work best to avoid overwhelming users
6. **Make them actionable**: Each suggestion should lead to a meaningful interaction

Migration from Legacy API \[#migration-from-legacy-api]

If you're using the deprecated `ThreadPrimitive.Suggestion` component, migrate to the new API:

Before (Deprecated) \[#before-deprecated]

```tsx
<ThreadPrimitive.Suggestion
  prompt="What's the weather?"
  send
/>
```

After (Recommended) \[#after-recommended]

1. Configure suggestions in your runtime provider:

```tsx
const aui = useAui({
  suggestions: Suggestions(["What's the weather?"]),
});
```

2. Display suggestions using the primitives:

```tsx
<ThreadPrimitive.Suggestions
  components={{
    Suggestion: SuggestionItem,
  }}
/>
```

The new API provides:

* **Centralized configuration**: Define suggestions once in your runtime provider
* **Better separation of concerns**: Configuration separate from presentation
* **Type safety**: Full TypeScript support
* **Consistency**: Follows the same pattern as the Tools API

Related \[#related]

* [Thread Component](/docs/ui/thread) - Main chat interface
* [Tools Guide](/docs/guides/tools) - Configure assistant actions
* [Context API](/docs/guides/context-api) - Access assistant state


# Generative UI
URL: /docs/guides/tool-ui

Render tool calls as interactive UI instead of plain text.

import { ToolUISample } from "@/components/docs/samples/tool-ui";

Create custom UI components for AI tool calls, providing visual feedback and interactive experiences when tools are executed.

<ToolUISample />

Overview \[#overview]

Tool UIs in assistant-ui allow you to create custom interfaces that appear when AI tools are called. These generative UI components enhance the user experience by:

* **Visualizing tool execution** with loading states and progress indicators
* **Displaying results** in rich, formatted layouts
* **Enabling user interaction** through forms and controls
* **Providing error feedback** with helpful recovery options

This guide demonstrates building tool UIs with the **Vercel AI SDK**.

Creating Tool UIs \[#creating-tool-uis]

There are two main approaches to creating tool UIs in assistant-ui:

1. Client-Defined Tools (makeAssistantTool) \[#1-client-defined-tools-makeassistanttool]

If you're creating tools on the client side, use `makeAssistantTool` to register them with the assistant context. Then create a UI component with `makeAssistantToolUI`:

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

// Define the tool
const weatherTool = tool({
  description: "Get current weather for a location",
  parameters: z.object({
    location: z.string(),
    unit: z.enum(["celsius", "fahrenheit"]),
  }),
  execute: async ({ location, unit }) => {
    const weather = await fetchWeatherAPI(location, unit);
    return weather;
  },
});

// Register the tool
const WeatherTool = makeAssistantTool({
  ...weatherTool,
  toolName: "getWeather",
});

// Create the UI
const WeatherToolUI = makeAssistantToolUI<
  { location: string; unit: "celsius" | "fahrenheit" },
  { temperature: number; description: string }
>({
  toolName: "getWeather",
  render: ({ args, result, status }) => {
    if (status.type === "running") {
      return <div>Checking weather in {args.location}...</div>;
    }

    return (
      <div className="weather-card">
        <h3>{args.location}</h3>
        <p>
          {result.temperature}°{args.unit === "celsius" ? "C" : "F"}
        </p>
        <p>{result.description}</p>
      </div>
    );
  },
});
```

<Callout type="tip">
  Tools defined with `makeAssistantTool` can be passed to your backend using the
  `frontendTools` utility
</Callout>

Learn more about creating tools in the [Tools Guide](/docs/guides/tools).

2. UI-Only for Existing Tools (makeAssistantToolUI) \[#2-ui-only-for-existing-tools-makeassistanttoolui]

If your tool is defined elsewhere (e.g., in your backend API, MCP server, or LangGraph), use `makeAssistantToolUI` to create just the UI component:

```tsx
import { makeAssistantToolUI } from "@assistant-ui/react";

const WeatherToolUI = makeAssistantToolUI<
  { location: string; unit: "celsius" | "fahrenheit" },
  { temperature: number; description: string }
>({
  toolName: "getWeather", // Must match the backend tool name
  render: ({ args, result, status }) => {
    // UI rendering logic only
  },
});
```

Quick Start Example \[#quick-start-example]

This example shows how to implement the UI-only approach using `makeAssistantToolUI`:

<Steps>
  <Step>
    Create a Tool UI Component \[#create-a-tool-ui-component]

    ```tsx
    import { makeAssistantToolUI } from "@assistant-ui/react";
    import { z } from "zod";

    type WeatherArgs = {
      location: string;
      unit: "celsius" | "fahrenheit";
    };

    type WeatherResult = {
      temperature: number;
      description: string;
      humidity: number;
      windSpeed: number;
    };

    const WeatherToolUI = makeAssistantToolUI<WeatherArgs, WeatherResult>({
      toolName: "getWeather",
      render: ({ args, status, result }) => {
        if (status.type === "running") {
          return (
            <div className="flex items-center gap-2">
              <Spinner />
              <span>Checking weather in {args.location}...</span>
            </div>
          );
        }

        if (status.type === "incomplete" && status.reason === "error") {
          return (
            <div className="text-red-500">
              Failed to get weather for {args.location}
            </div>
          );
        }

        return (
          <div className="weather-card rounded-lg bg-blue-50 p-4">
            <h3 className="text-lg font-bold">{args.location}</h3>
            <div className="mt-2 grid grid-cols-2 gap-4">
              <div>
                <p className="text-2xl">
                  {result.temperature}°{args.unit === "celsius" ? "C" : "F"}
                </p>
                <p className="text-gray-600">{result.description}</p>
              </div>
              <div className="text-sm">
                <p>Humidity: {result.humidity}%</p>
                <p>Wind: {result.windSpeed} km/h</p>
              </div>
            </div>
          </div>
        );
      },
    });
    ```
  </Step>

  <Step>
    Register the Tool UI \[#register-the-tool-ui]

    Place the component inside your `AssistantRuntimeProvider`:

    ```tsx
    function App() {
      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <Thread />
          <WeatherToolUI />
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Define the Backend Tool (Vercel AI SDK) \[#define-the-backend-tool-vercel-ai-sdk]

    When using the Vercel AI SDK, define the corresponding tool in your API route:

    ```tsx title="/app/api/chat/route.ts"
    import { streamText, tool, zodSchema } from "ai";
    import { z } from "zod";

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = streamText({
        model: openai("gpt-4o"),
        messages: convertToModelMessages(messages),
        tools: {
          getWeather: tool({
            description: "Get current weather for a location",
            inputSchema: zodSchema(
              z.object({
                location: z.string(),
                unit: z.enum(["celsius", "fahrenheit"]),
              }),
            ),
            execute: async ({ location, unit }) => {
              const weather = await fetchWeatherAPI(location);
              return {
                temperature: weather.temp,
                description: weather.condition,
                humidity: weather.humidity,
                windSpeed: weather.wind,
              };
            },
          }),
        },
      });

      return result.toUIMessageStreamResponse();
    }
    ```
  </Step>
</Steps>

Tool UI Patterns \[#tool-ui-patterns]

Component Pattern \[#component-pattern]

Create standalone tool UI components:

```tsx
export const WebSearchToolUI = makeAssistantToolUI<
  { query: string },
  { results: SearchResult[] }
>({
  toolName: "webSearch",
  render: ({ args, status, result }) => {
    return (
      <div className="search-container">
        <div className="mb-3 flex items-center gap-2">
          <SearchIcon />
          <span>Search results for: "{args.query}"</span>
        </div>

        {status.type === "running" && <LoadingSpinner />}

        {result && (
          <div className="space-y-2">
            {result.results.map((item, index) => (
              <div key={index} className="rounded border p-3">
                <a href={item.url} className="font-medium text-blue-600">
                  {item.title}
                </a>
                <p className="text-sm text-gray-600">{item.snippet}</p>
              </div>
            ))}
          </div>
        )}
      </div>
    );
  },
});
```

Hook Pattern \[#hook-pattern]

Use hooks for dynamic tool UI registration:

<Callout type="tip">
  When you assign your `makeAssistantToolUI({...})` call to a constant starting with `use…`, you can call it directly as a hook inside your component. This pattern lets you access local props or state when rendering the tool UI.
</Callout>

```tsx
import { useAssistantToolUI } from "@assistant-ui/react";

function DynamicToolUI() {
  const [theme, setTheme] = useState("light");

  useAssistantToolUI({
    toolName: "analyzeData",
    render: ({ args, result, status }) => {
      // Hook allows access to component state
      return (
        <DataVisualization
          data={result}
          theme={theme}
          loading={status.type === "running"}
        />
      );
    },
  });

  return null;
}
```

Inline Pattern \[#inline-pattern]

For tools that need access to parent component props:

<Callout type="tip">
  **Why `useInlineRender`?** By default, a tool UI's `render` function is
  static. Use `useInlineRender` when your UI needs access to dynamic component
  props (for example, to pass in an `id` or other contextual data).
</Callout>

```tsx
import { useAssistantToolUI, useInlineRender } from "@assistant-ui/react";

function ProductPage({ productId, productName }) {
  useAssistantToolUI({
    toolName: "checkInventory",
    render: useInlineRender(({ args, result }) => {
      // Access parent component props
      return (
        <div className="inventory-status">
          <h4>{productName} Inventory</h4>
          <p>
            Stock for {productId}: {result.quantity} units
          </p>
          <p>Location: {result.warehouse}</p>
        </div>
      );
    }),
  });

  return <div>Product details...</div>;
}
```

Interactive Tool UIs \[#interactive-tool-uis]

User Input Collection \[#user-input-collection]

Create tools that collect user input during execution:

<Callout type="tip">
  **Pro tip:** Call `addResult(...)` exactly once to complete the tool call.
  After it's invoked, the assistant will resume the conversation with your
  provided data.
</Callout>

```tsx
const DatePickerToolUI = makeAssistantToolUI<
  { prompt: string },
  { date: string }
>({
  toolName: "selectDate",
  render: ({ args, result, addResult }) => {
    if (result) {
      return (
        <div className="rounded bg-green-50 p-3">
          ✅ Selected date: {new Date(result.date).toLocaleDateString()}
        </div>
      );
    }

    return (
      <div className="rounded border p-4">
        <p className="mb-3">{args.prompt}</p>
        <DatePicker
          onChange={(date) => {
            addResult({ date: date.toISOString() });
          }}
        />
      </div>
    );
  },
});
```

Multi-Step Interactions \[#multi-step-interactions]

Build complex workflows with human-in-the-loop patterns for multi-step user interactions:

```tsx
const DeleteProjectTool = makeAssistantTool({
  toolName: "deleteProject",
  execute: async ({ projectId }, { human }) => {
    const response = await human({ action, details });
    if (!response.approved) throw new Error("Project deletion cancelled");

    await deleteProject(projectId);
    return { success: true };
  },
});

const ApprovalTool = makeAssistantTool({
  ...tool({
    description: "Request user approval for an action",
    parameters: z.object({
      action: z.string(),
      details: z.any(),
    }),
    execute: async ({ action, details }, { human }) => {
      // Request approval from user
      const response = await human({ action, details });

      return {
        approved: response.approved,
        reason: response.reason,
      };
    },
  }),
  toolName: "requestApproval",
  render: ({ args, result, interrupt, resume }) => {
    const [reason, setReason] = useState("");

    // Show result after approval/rejection
    if (result) {
      return (
        <div className={result.approved ? "text-green-600" : "text-red-600"}>
          {result.approved ? "✅ Approved" : `❌ Rejected: ${result.reason}`}
        </div>
      );
    }

    // Show approval UI when waiting for user input
    if (interrupt) {
      return (
        <div className="rounded border-2 border-yellow-400 p-4">
          <h4 className="font-bold">Approval Required</h4>
          <p className="my-2">{interrupt.payload.action}</p>
          <pre className="rounded bg-gray-100 p-2 text-sm">
            {JSON.stringify(interrupt.payload.details, null, 2)}
          </pre>

          <div className="mt-4 flex gap-2">
            <button
              onClick={() => resume({ approved: true })}
              className="rounded bg-green-500 px-4 py-2 text-white"
            >
              Approve
            </button>
            <button
              onClick={() => resume({ approved: false, reason })}
              className="rounded bg-red-500 px-4 py-2 text-white"
            >
              Reject
            </button>
            <input
              type="text"
              placeholder="Rejection reason..."
              value={reason}
              onChange={(e) => setReason(e.target.value)}
              className="flex-1 rounded border px-2"
            />
          </div>
        </div>
      );
    }

    return <div>Processing...</div>;
  },
});
```

<Callout type="tip">
  Use tool human input (`human()` / `resume()`) for workflows that need to
  pause tool execution and wait for user input. Use `addResult()` for "human
  tools" where the AI requests a tool call but the entire execution happens
  through user interaction.
</Callout>

Advanced Features \[#advanced-features]

Tool Status Handling \[#tool-status-handling]

The `status` prop provides detailed execution state:

```tsx
render: ({ status, args }) => {
  switch (status.type) {
    case "running":
      return <LoadingState />;

    case "requires-action":
      return <UserInputRequired reason={status.reason} />;

    case "incomplete":
      if (status.reason === "cancelled") {
        return <div>Operation cancelled</div>;
      }
      if (status.reason === "error") {
        return <ErrorDisplay error={status.error} />;
      }
      return <div>Failed: {status.reason}</div>;

    case "complete":
      return <SuccessDisplay />;
  }
};
```

Field-Level Validation \[#field-level-validation]

Use `useToolArgsFieldStatus` to show validation states:

```tsx
import { useToolArgsFieldStatus } from "@assistant-ui/react";

const FormToolUI = makeAssistantToolUI({
  toolName: "submitForm",
  render: ({ args }) => {
    const emailStatus = useToolArgsFieldStatus("email");
    const phoneStatus = useToolArgsFieldStatus("phone");

    return (
      <form className="space-y-4">
        <div>
          <input
            type="email"
            value={args.email}
            className={emailStatus.type === "running" ? "loading" : ""}
            disabled
          />
          {emailStatus.type === "incomplete" && (
            <span className="text-red-500">Invalid email</span>
          )}
        </div>

        <div>
          <input
            type="tel"
            value={args.phone}
            className={phoneStatus.type === "running" ? "loading" : ""}
            disabled
          />
        </div>
      </form>
    );
  },
});
```

Partial Results & Streaming \[#partial-results--streaming]

Display results as they stream in:

```tsx
const AnalysisToolUI = makeAssistantToolUI<
  { data: string },
  { progress: number; insights: string[] }
>({
  toolName: "analyzeData",
  render: ({ result, status }) => {
    const progress = result?.progress || 0;
    const insights = result?.insights || [];

    return (
      <div className="analysis-container">
        {status.type === "running" && (
          <div className="mb-4">
            <div className="mb-1 flex justify-between">
              <span>Analyzing...</span>
              <span>{progress}%</span>
            </div>
            <div className="w-full rounded bg-gray-200">
              <div
                className="h-2 rounded bg-blue-500"
                style={{ width: `${progress}%` }}
              />
            </div>
          </div>
        )}

        <div className="space-y-2">
          {insights.map((insight, i) => (
            <div key={i} className="rounded bg-gray-50 p-2">
              {insight}
            </div>
          ))}
        </div>
      </div>
    );
  },
});
```

Custom Tool Fallback \[#custom-tool-fallback]

Provide a custom UI for tools without specific UIs:

```tsx
<Thread
  components={{
    ToolFallback: ({ toolName, args, result }) => (
      <div className="tool-fallback rounded bg-gray-100 p-3">
        <code className="text-sm">
          {toolName}({JSON.stringify(args)})
        </code>
        {result && (
          <pre className="mt-2 text-xs">{JSON.stringify(result, null, 2)}</pre>
        )}
      </div>
    ),
  }}
/>
```

Execution Context \[#execution-context]

Generative UI components have access to execution context through props:

```tsx
type ToolUIRenderProps<TArgs, TResult> = {
  // Tool arguments
  args: TArgs;
  argsText: string; // JSON stringified args

  // Execution status
  status: ToolCallMessagePartStatus;
  isError?: boolean;

  // Tool result (may be partial during streaming)
  result?: TResult;

  // Tool metadata
  toolName: string;
  toolCallId: string;

  // Interactive callbacks
  addResult: (result: TResult) => void;
  resume: (payload: unknown) => void;

  // Interrupt state
  interrupt?: { type: "human"; payload: unknown }; // Payload from context.human()

  // Optional artifact data
  artifact?: unknown;
};
```

Human Input Handling \[#human-input-handling]

When a tool calls `human()` during execution, the payload becomes available in the render function as `interrupt.payload`:

```tsx
const ConfirmationToolUI = makeAssistantToolUI<
  { action: string },
  { confirmed: boolean }
>({
  toolName: "confirmAction",
  render: ({ args, result, interrupt, resume }) => {
    // Tool is waiting for user input
    if (interrupt) {
      return (
        <div className="confirmation-dialog">
          <p>Confirm: {interrupt.payload.message}</p>
          <button onClick={() => resume(true)}>Yes</button>
          <button onClick={() => resume(false)}>No</button>
        </div>
      );
    }

    // Tool completed
    if (result) {
      return <div>Action {result.confirmed ? "confirmed" : "cancelled"}</div>;
    }

    return <div>Processing...</div>;
  },
});
```

Learn more about tool human input in the [Tools Guide](/docs/guides/tools#tool-human-input).

Best Practices \[#best-practices]

1. Handle All Status States \[#1-handle-all-status-states]

Always handle loading, error, and success states:

```tsx
render: ({ status, result, args }) => {
  if (status.type === "running") return <Skeleton />;
  if (status.type === "incomplete") return <ErrorState />;
  if (!result) return null;
  return <ResultDisplay result={result} />;
};
```

2. Provide Visual Feedback \[#2-provide-visual-feedback]

Use animations and transitions for better UX:

```tsx
<div
  className={cn(
    "transition-all duration-300",
    status.type === "running" && "opacity-50",
    status.type === "complete" && "opacity-100",
  )}
>
  {/* Tool UI content */}
</div>
```

3. Make UIs Accessible \[#3-make-uis-accessible]

Ensure keyboard navigation and screen reader support:

```tsx
<button
  onClick={() => addResult(value)}
  aria-label="Confirm selection"
  className="focus:outline-none focus:ring-2"
>
  Confirm
</button>
```

4. Optimize Performance \[#4-optimize-performance]

Use `useInlineRender` to prevent unnecessary re-renders:

```tsx
useAssistantToolUI({
  toolName: "heavyComputation",
  render: useInlineRender(({ result }) => {
    // Expensive rendering logic
    return <ComplexVisualization data={result} />;
  }),
});
```

<Callout>
  Generative UI components are only displayed in the chat interface. The actual
  tool execution happens on the backend. This separation allows you to create
  rich, interactive experiences while keeping sensitive logic secure on the
  server.
</Callout>

Related Guides \[#related-guides]

* [Tools Guide](/docs/guides/tools) - Learn how to create and use tools with AI models
* [Tool Fallback](/docs/ui/tool-fallback) - Default UI for tools without custom components
* [API Reference](/docs/api-reference/primitives/message-part) - Detailed type definitions and component APIs
* [Message Primitive](/docs/api-reference/primitives/message) - Complete Message component documentation


# Tools
URL: /docs/guides/tools

Give your assistant actions like API calls, database queries, and more.

Tools enable LLMs to take actions and interact with external systems. assistant-ui provides a comprehensive toolkit for creating, managing, and visualizing tool interactions in real-time.

Overview \[#overview]

Tools in assistant-ui are functions that the LLM can call to perform specific tasks. They bridge the gap between the LLM's reasoning capabilities and real-world actions like:

* Fetching data from APIs
* Performing calculations
* Interacting with databases
* Controlling UI elements
* Executing workflows

When tools are executed, you can display custom generative UI components that provide rich, interactive visualizations of the tool's execution and results. Learn more in the [Generative UI guide](/docs/guides/tool-ui).

<Callout type="tip">
  If you haven't provided a custom UI for a tool, assistant-ui offers a
  [`ToolFallback`](/docs/ui/tool-fallback) component that you can add to your
  codebase to render a default UI for tool executions. You can customize this by
  creating your own Tool UI component for the tool's name.
</Callout>

Recommended: Tools() API \[#recommended-tools-api]

The `Tools()` API is the recommended way to register tools in assistant-ui. It provides centralized tool registration that prevents duplicate registrations and works seamlessly with all runtimes.

Quick Start \[#quick-start]

Create a toolkit object containing all your tools, then register it using `useAui()`:

```tsx
import { useAui, Tools, type Toolkit } from "@assistant-ui/react";
import { z } from "zod";

// Define your toolkit
const myToolkit: Toolkit = {
  getWeather: {
    description: "Get current weather for a location",
    parameters: z.object({
      location: z.string().describe("City name or zip code"),
      unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
    }),
    execute: async ({ location, unit }) => {
      const weather = await fetchWeatherAPI(location, unit);
      return weather;
    },
    render: ({ args, result }) => {
      if (!result) return <div>Fetching weather for {args.location}...</div>;
      return (
        <div className="weather-card">
          <h3>{args.location}</h3>
          <p>{result.temperature}° {args.unit}</p>
          <p>{result.conditions}</p>
        </div>
      );
    },
  },
  // Add more tools here
};

// Register tools in your runtime provider
function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();

  // Register all tools
  const aui = useAui({
    tools: Tools({ toolkit: myToolkit }),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

Benefits \[#benefits]

* **No Duplicate Registrations**: Tools are registered once, preventing the "tool already exists" error
* **Centralized Definition**: All your tools in one place, easier to manage and test
* **Type-Safe**: Full TypeScript support with proper type inference
* **Flexible**: Works with all runtimes (AI SDK, LangGraph, custom, etc.)
* **Composable**: Easily split toolkits across files and merge them

Tool Definition \[#tool-definition]

Each tool in the toolkit is a `ToolDefinition` object with these properties:

```tsx
type ToolDefinition = {
  description: string;
  parameters: z.ZodType; // Zod schema for parameters
  execute: (args, context) => Promise<any>;
  render?: (props) => React.ReactNode; // Optional UI component
};
```

Organizing Large Toolkits \[#organizing-large-toolkits]

For larger applications, split tools across multiple files:

```tsx
// lib/tools/weather.tsx
export const weatherTools: Toolkit = {
  getWeather: { /* ... */ },
  getWeatherForecast: { /* ... */ },
};

// lib/tools/database.tsx
export const databaseTools: Toolkit = {
  queryData: { /* ... */ },
  insertData: { /* ... */ },
};

// lib/toolkit.tsx
import { weatherTools } from "./tools/weather";
import { databaseTools } from "./tools/database";

export const appToolkit: Toolkit = {
  ...weatherTools,
  ...databaseTools,
};

// App.tsx
import { appToolkit } from "./lib/toolkit";

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();

  const aui = useAui({
    tools: Tools({ toolkit: appToolkit }),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

UI-Only Tools \[#ui-only-tools]

For tools where execution happens elsewhere (e.g., backend MCP tools), omit the `execute` function:

```tsx
const uiOnlyToolkit: Toolkit = {
  webSearch: {
    description: "Search the web",
    parameters: z.object({
      query: z.string(),
    }),
    // No execute - handled by backend
    render: ({ args, result }) => {
      return (
        <div>
          <h3>Search: {args.query}</h3>
          {result?.results.map((item) => (
            <div key={item.id}>
              <a href={item.url}>{item.title}</a>
            </div>
          ))}
        </div>
      );
    },
  },
};
```

Tool Execution Context \[#tool-execution-context]

Tools receive additional context during execution:

```tsx
execute: async (args, context) => {
  // context.abortSignal - AbortSignal for cancellation
  // context.toolCallId - Unique identifier for this invocation
  // context.human - Function to request human input

  // Example: Respect cancellation
  const response = await fetch(url, { signal: context.abortSignal });

  // Example: Request user confirmation
  const userResponse = await context.human({
    message: "Are you sure?",
  });
};
```

Human-in-the-Loop \[#human-in-the-loop]

Tools can pause execution to request user input or approval:

```tsx
const confirmationToolkit: Toolkit = {
  sendEmail: {
    description: "Send an email with confirmation",
    parameters: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
    execute: async ({ to, subject, body }, { human }) => {
      // Request user confirmation before sending
      const confirmed = await human({
        type: "confirmation",
        action: "send-email",
        details: { to, subject },
      });

      if (!confirmed) {
        return { status: "cancelled" };
      }

      await sendEmail({ to, subject, body });
      return { status: "sent" };
    },
    render: ({ args, result, interrupt, resume }) => {
      // Show confirmation dialog when waiting for user input
      if (interrupt) {
        return (
          <div>
            <h3>Confirm Email</h3>
            <p>Send to: {interrupt.payload.details.to}</p>
            <p>Subject: {interrupt.payload.details.subject}</p>
            <button onClick={() => resume(true)}>Confirm</button>
            <button onClick={() => resume(false)}>Cancel</button>
          </div>
        );
      }

      // Show result
      if (result) {
        return <div>Status: {result.status}</div>;
      }

      return <div>Preparing email...</div>;
    },
  },
};
```

Alternative Methods (Legacy) \[#alternative-methods-legacy]

<Callout type="warning">
  The following methods are supported for backwards compatibility but are not
  recommended for new code. They can cause duplicate registration errors and are
  harder to maintain. Use the `Tools()` API instead.
</Callout>

Using makeAssistantTool (Deprecated) \[#using-makeassistanttool-deprecated]

Register tools with the assistant context. Returns a React component that registers the tool when rendered:

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

const weatherTool = tool({
  description: "Get current weather for a location",
  parameters: z.object({
    location: z.string(),
  }),
  execute: async ({ location }) => {
    const weather = await fetchWeatherAPI(location);
    return weather;
  },
});

const WeatherTool = makeAssistantTool({
  ...weatherTool,
  toolName: "getWeather",
});

// Place inside AssistantRuntimeProvider
function App() {
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <WeatherTool />
      <Thread />
    </AssistantRuntimeProvider>
  );
}
```

**Why this is deprecated**: Component-based registration can lead to duplicate registrations if components are remounted or if the same tool is defined in multiple places.

Using useAssistantTool Hook (Deprecated) \[#using-useassistanttool-hook-deprecated]

Register tools dynamically using React hooks:

```tsx
import { useAssistantTool } from "@assistant-ui/react";
import { z } from "zod";

function DynamicTools() {
  useAssistantTool({
    toolName: "searchData",
    description: "Search through the data",
    parameters: z.object({
      query: z.string(),
    }),
    execute: async ({ query }) => {
      return await searchDatabase(query);
    },
  });

  return null;
}
```

**Why this is deprecated**: Hook-based registration ties tool definitions to component lifecycle, making them harder to test and potentially causing duplicate registrations.

Using makeAssistantToolUI (Deprecated) \[#using-makeassistanttoolui-deprecated]

Create UI-only components for tools defined elsewhere:

```tsx
import { makeAssistantToolUI } from "@assistant-ui/react";

const SearchResultsUI = makeAssistantToolUI<
  { query: string },
  { results: Array<any> }
>({
  toolName: "webSearch",
  render: ({ args, result }) => {
    return (
      <div>
        <h3>Search: {args.query}</h3>
        {result.results.map((item) => (
          <div key={item.id}>{item.title}</div>
        ))}
      </div>
    );
  },
});

function App() {
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <SearchResultsUI />
      <Thread />
    </AssistantRuntimeProvider>
  );
}
```

**Why this is deprecated**: Component-based UI registration can cause issues with tool UI not appearing or appearing multiple times.

Tool Paradigms \[#tool-paradigms]

Frontend Tools \[#frontend-tools]

Tools that execute in the browser:

```tsx
const frontendToolkit: Toolkit = {
  screenshot: {
    description: "Capture a screenshot of the current page",
    parameters: z.object({
      selector: z.string().optional(),
    }),
    execute: async ({ selector }) => {
      const element = selector ? document.querySelector(selector) : document.body;
      const screenshot = await captureElement(element);
      return { dataUrl: screenshot };
    },
  },
};
```

Backend Tools \[#backend-tools]

Tools executed server-side:

```tsx
// Backend route (AI SDK)
export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    messages: convertToModelMessages(messages),
    tools: {
      queryDatabase: {
        description: "Query the application database",
        inputSchema: zodSchema(
          z.object({
            query: z.string(),
            table: z.string(),
          }),
        ),
        execute: async ({ query, table }) => {
          const results = await db.query(query, { table });
          return results;
        },
      },
    },
  });

  return result.toUIMessageStreamResponse();
}
```

Client-Defined Tools with frontendTools \[#client-defined-tools-with-frontendtools]

The Vercel AI SDK adapter implements automatic serialization of client-defined tools. Tools registered via the `Tools()` API are automatically included in API requests:

```tsx
// Frontend: Define tools with Tools() API
const clientToolkit: Toolkit = {
  calculate: {
    description: "Perform calculations",
    parameters: z.object({
      expression: z.string(),
    }),
    execute: async ({ expression }) => {
      return eval(expression); // Use proper parser in production
    },
  },
};

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();

  const aui = useAui({
    tools: Tools({ toolkit: clientToolkit }),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}

// Backend: Use frontendTools to receive client tools
import { frontendTools } from "@assistant-ui/react-ai-sdk";

export async function POST(req: Request) {
  const { messages, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    messages: convertToModelMessages(messages),
    tools: {
      ...frontendTools(tools), // Client-defined tools
      // Additional server-side tools
      queryDatabase: {
        description: "Query the database",
        inputSchema: zodSchema(z.object({ query: z.string() })),
        execute: async ({ query }) => {
          return await db.query(query);
        },
      },
    },
  });

  return result.toUIMessageStreamResponse();
}
```

MCP (Model Context Protocol) Tools \[#mcp-model-context-protocol-tools]

Integration with MCP servers using AI SDK's experimental MCP support:

```tsx
import { experimental_createMCPClient, streamText } from "ai";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

export async function POST(req: Request) {
  const client = await experimental_createMCPClient({
    transport: new StdioClientTransport({
      command: "npx",
      args: ["@modelcontextprotocol/server-github"],
    }),
  });

  try {
    const tools = await client.tools();

    const result = streamText({
      model: openai("gpt-4o"),
      tools,
      messages: convertToModelMessages(messages),
    });

    return result.toUIMessageStreamResponse();
  } finally {
    await client.close();
  }
}
```

Best Practices \[#best-practices]

1. **Use Tools() API**: Always prefer the `Tools()` API over legacy component/hook-based registration
2. **Centralize Definitions**: Keep all tools in a toolkit file for easy management
3. **Clear Descriptions**: Write descriptive tool descriptions that help the LLM understand when to use each tool
4. **Parameter Validation**: Use Zod schemas to ensure type safety
5. **Error Handling**: Handle errors gracefully with user-friendly messages
6. **Loading States**: Provide visual feedback during tool execution
7. **Security**: Validate permissions and sanitize inputs
8. **Performance**: Use abort signals for cancellable operations
9. **Testing**: Test tools in isolation and with the full assistant flow

Migration from Legacy APIs \[#migration-from-legacy-apis]

To migrate from legacy APIs to the `Tools()` API:

1. **Create a toolkit object** with all your tools
2. **Move tool definitions** from `makeAssistantTool`/`useAssistantTool` calls into the toolkit
3. **Register once** using `useAui({ tools: Tools({ toolkit }) })` in your runtime provider
4. **Remove component registrations** (`<WeatherTool />`, etc.)
5. **Test** to ensure all tools work as expected

Example migration:

```tsx
// Before (Legacy)
const WeatherTool = makeAssistantTool({
  toolName: "getWeather",
  description: "Get weather",
  parameters: z.object({ location: z.string() }),
  execute: async ({ location }) => { /* ... */ },
});

function App() {
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <WeatherTool />
      <Thread />
    </AssistantRuntimeProvider>
  );
}

// After (Recommended)
const toolkit: Toolkit = {
  getWeather: {
    description: "Get weather",
    parameters: z.object({ location: z.string() }),
    execute: async ({ location }) => { /* ... */ },
  },
};

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();

  const aui = useAui({
    tools: Tools({ toolkit }),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```


# Overview
URL: /docs/api-reference/overview

API reference for primitives, runtime hooks, and context providers.

import { Component, ContextLevel, RuntimeHooks } from "./context";

export const contextColors = {
  "Assistant Context": "#4a86e8",
  "Thread Context": "#45a049",
  "Composer Context": "#ff9933",
  "Message Context": "#bb2244",
  "MessagePart Context": "#268bd2",
  "Attachment Context": "#FFB6C1",
  "ThreadListItem Context": "#c678dd",
};

<Callout title="Work in progress" type="warn">
  This page is under construction. Most links will not work yet.
</Callout>

Cloud \[#cloud]

* [`AssistantCloud`](#assistant-cloud)

Runtime API \[#runtime-api]

AI SDK \[#ai-sdk]

* [`useChatRuntime`](#use-chat-runtime)
* [`useAISDKRuntime`](#use-aisdk-runtime)

Data Stream \[#data-stream]

* [`useDataStreamRuntime`](#use-data-stream-runtime)
* [`useCloudRuntime`](#use-cloud-runtime)
* [`toLanguageModelMessages`](#to-language-model-messages) (AI SDK specific)

assistant-stream (Framework-Agnostic) \[#assistant-stream-framework-agnostic]

* [`toGenericMessages`](#to-generic-messages)
* [`toToolsJSONSchema`](#to-tools-json-schema)
* [`GenericMessage`](#generic-message)

LangGraph \[#langgraph]

* [`useLangGraphRuntime`](#use-lang-graph-runtime)

Local Runtime \[#local-runtime]

* [`useLocalRuntime`](#use-local-runtime)

External Store Runtime \[#external-store-runtime]

* [`useExternalStoreRuntime`](#use-external-store-runtime)
* [`createMessageConverter`](#create-message-converter)

Thread List Runtime \[#thread-list-runtime]

* [`useRemoteThreadListRuntime`](#use-remote-thread-list-runtime)
* [`useCloudThreadListRuntime`](#use-cloud-thread-list-runtime)

Runtime Adapters \[#runtime-adapters]

Attachment \[#attachment]

* [`AttachmentAdapter`](#attachment-adapter)
* [`SimpleImageAttachmentAdapter`](#simple-image-attachment-adapter)
* [`SimpleTextAttachmentAdapter`](#simple-text-attachment-adapter)
* [`CompositeAttachmentAdapter`](#composite-attachment-adapter)

Feedback \[#feedback]

* [`FeedbackAdapter`](#feedback-adapter)

Speech \[#speech]

* [`SpeechSynthesisAdapter`](#speech-synthesis-adapter)
* [`WebSpeechSynthesisAdapter`](#web-speech-synthesis-adapter)

Highest Level Context Providers \[#highest-level-context-providers]

<Component
  name="AssistantRuntimeProvider"
  isContextProvider={true}
  providedContexts={[
{ name: "Assistant Context", color: contextColors["Assistant Context"] },
{ name: "Thread Context", color: contextColors["Thread Context"] },
{
  name: "Thread Composer Context",
  color: contextColors["Composer Context"],
  link: "#composer-context",
},
]}
  docsLink="./context-providers/AssistantRuntimeProvider"
  tooltip="Provides the highest level context for the assistant-ui"
  props="runtime={runtime}"
>
  <Component name="Thread" isLink={true} />

  <Component name="ThreadList" isLink={true} />
</Component>

<Component
  name="TextMessagePartProvider"
  isContextProvider={true}
  providedContexts={[
{
  name: "Text MessagePart Context",
  color: contextColors["MessagePart Context"],
  link: "#MessagePart-context",
},
]}
  docsLink="./context-providers/TextMessagePartProvider"
  tooltip="Provides context for text message parts"
  props="text={text}"
>
  <Component name="MessagePart" isLink={true} />
</Component>

<ContextLevel color={contextColors["Assistant Context"]}>
  Assistant Context \[#assistant-context]

  The context available to components inside `<AssistantRuntimeProvider />`. You usually wrap your entire application in this context.

  AssistantRuntime \[#assistantruntime]

  Programmatically access the assistant's state and actions.

  * [`useAssistantRuntime`](#use-assistant-runtime)

  Instructions \[#instructions]

  Add system prompt instructions

  * [`useAssistantInstructions`](#use-assistant-instructions)

  Tool UI \[#tool-ui]

  Register tool UIs

  * [`makeAssistantTool`](#make-assistant-tool)
  * [`makeAssistantToolUI`](#make-assistant-tool-ui)
  * [`useAssistantTool`](#use-assistant-tool)
  * [`useAssistantToolUI`](#use-assistant-tool-ui)

  Programmatically access the list of registered tool UIs (Experimental)

  * [`useToolUIs`](#use-tool-uis)
  * [`useToolUIsStore`](#use-tool-uis-store)

  ThreadListPrimitive \[#threadlistprimitive]

  Shows a list of threads and allows the user to switch between them.

  <Component name="ThreadListPrimitive.Root" docsLink="#thread-list-primitive-root" tooltip="Root component for the thread list">
    <Component name="ThreadListPrimitive.New" docsLink="#thread-list-primitive-new" tooltip="Component for creating a new thread" />

    <Component
      name="ThreadListPrimitive.Items"
      isContextProvider={true}
      providedContexts={[
  {
    name: "ThreadListItem Context",
    color: contextColors["ThreadListItem Context"],
  },
]}
      docsLink="#thread-list-primitive-items"
      tooltip="Container for thread list items, provides context for individual items"
      props="components={...}"
    />
  </Component>
</ContextLevel>

<ContextLevel color={contextColors["Thread Context"]}>
  Thread Context \[#thread-context]

  The context for a single thread. Currently always corresponds to the runtime's main thread.

  ThreadRuntime \[#threadruntime]

  Programmatically access the thread's state and actions.

  * [`useThread`](#use-thread)
  * [`useThreadComposer`](#use-thread-composer)
  * [`useThreadRuntime`](#use-thread-runtime)

  ModelContext \[#modelcontext]

  * [`useThreadModelContext`](#use-thread-model-context)

  ThreadViewportStore \[#threadviewportstore]

  * [`useThreadViewport`](#use-thread-viewport)
  * [`useThreadViewportStore`](#use-thread-viewport-store)

  ThreadPrimitive \[#threadprimitive]

  A conversation thread.

  <Component name="ThreadPrimitive.Root" docsLink="#thread-primitive-root" tooltip="Root component for a thread">
    <Component name="ThreadPrimitive.Viewport" docsLink="#thread-primitive-viewport" tooltip="Viewport for the thread content">
      <Component
        name="ThreadPrimitive.Messages"
        isContextProvider={true}
        providedContexts={[
    { name: "Message Context", color: contextColors["Message Context"] },
    {
      name: "Edit Composer Context",
      color: contextColors["Composer Context"],
      link: "#composer-context",
    },
  ]}
        docsLink="#thread-primitive-messages"
        tooltip="Container for thread messages, provides context for messages and edit composer"
      >
        <Component name="Message" isLink={true} />
      </Component>

      <Component name="ThreadPrimitive.ScrollToBottom" docsLink="#thread-primitive-scroll-to-bottom" tooltip="Scrolls to the bottom of the thread" />

      <Component name="ThreadPrimitive.Empty" docsLink="#thread-primitive-empty" tooltip="Displayed when the thread is empty" />

      <Component name="AuiIf" docsLink="#assistant-if" tooltip="Conditional rendering based on assistant state" />

      <Component name="ThreadPrimitive.Suggestion" docsLink="#thread-primitive-suggestion" tooltip="Displays suggestions in the thread" />

      <Component name="Composer" isLink={true} />
    </Component>
  </Component>

  AssistantModalPrimitive \[#assistantmodalprimitive]

  A floating modal that usually appears in the lower right corner of the screen. Common for support use cases.

  <Component name="AssistantModalPrimitive.Root" docsLink="#assistant-modal-primitive-root" tooltip="Root component for the assistant modal">
    <Component name="AssistantModalPrimitive.Trigger" docsLink="#assistant-modal-primitive-trigger" tooltip="Trigger to open the assistant modal" />

    <Component name="AssistantModalPrimitive.Anchor" docsLink="#assistant-modal-primitive-anchor" tooltip="Anchor point for the assistant modal" />

    <Component name="AssistantModalPrimitive.Content" docsLink="#assistant-modal-primitive-content" tooltip="Content of the assistant modal" />
  </Component>
</ContextLevel>

<ContextLevel color={contextColors["Composer Context"]}>
  Composer Context \[#composer-context]

  Manages the state and actions for the message composer

  ComposerRuntime \[#composerruntime]

  * [`useComposer`](#use-composer)
  * [`useComposerRuntime`](#use-composer-runtime)

  ComposerPrimitive \[#composerprimitive]

  <Component name="ComposerPrimitive.Root" docsLink="#composer-primitive-root" tooltip="Root component for the composer">
    <Component name="ComposerPrimitive.Input" docsLink="#composer-primitive-input" tooltip="Input field for composing messages" />

    <Component name="ComposerPrimitive.Send" docsLink="#composer-primitive-send" tooltip="Button to send the composed message" />

    <Component name="ComposerPrimitive.Cancel" docsLink="#composer-primitive-cancel" tooltip="Button to cancel composing" />

    <Component
      name="ComposerPrimitive.Attachments"
      isContextProvider={true}
      providedContexts={[
  {
    name: "Attachment Context",
    color: contextColors["Attachment Context"],
  },
]}
      docsLink="#composer-primitive-attachments"
      tooltip="Manages attachments in the composer"
    />

    <Component name="ComposerPrimitive.AddAttachment" docsLink="#composer-primitive-add-attachment" tooltip="Button to add an attachment" />
  </Component>
</ContextLevel>

<ContextLevel color={contextColors["Message Context"]}>
  Message Context \[#message-context]

  Manages the state and actions for individual messages

  MessageRuntime \[#messageruntime]

  * [`useMessage`](#use-message)
  * [`useEditComposer`](#use-edit-composer)
  * [`useMessageRuntime`](#use-message-runtime)

  MessageUtilsStore \[#messageutilsstore]

  * [`useMessageUtils`](#use-message-utils)
  * [`useMessageUtilsStore`](#use-message-utils-store)

  MessagePrimitive \[#messageprimitive]

  <Component name="MessagePrimitive.Root" docsLink="#message-primitive-root" tooltip="Root component for a message">
    <Component
      name="MessagePrimitive.Parts"
      isContextProvider={true}
      providedContexts={[
  {
    name: "MessagePart Context",
    color: contextColors["MessagePart Context"],
  },
]}
      docsLink="#message-primitive-parts"
      tooltip="Displays the parts of the message"
    />

    <Component
      name="MessagePrimitive.Attachments"
      isContextProvider={true}
      providedContexts={[
  {
    name: "Attachment Context",
    color: contextColors["Attachment Context"],
  },
]}
      docsLink="#message-primitive-attachments"
      tooltip="Displays attachments in the message"
    />

    <Component name="AuiIf" docsLink="#assistant-if" tooltip="Conditional rendering based on assistant state" />
  </Component>

  ActionBarPrimitive \[#actionbarprimitive]

  <Component name="ActionBarPrimitive.Root" docsLink="#action-bar-primitive-root" tooltip="Root component for the action bar">
    <Component name="ActionBarPrimitive.Copy" docsLink="#action-bar-primitive-copy" tooltip="Copies the message content" />

    <Component name="ActionBarPrimitive.Edit" docsLink="#action-bar-primitive-edit" tooltip="Edits the message" />

    <Component name="ActionBarPrimitive.Reload" docsLink="#action-bar-primitive-reload" tooltip="Reloads the message" />

    <Component name="ActionBarPrimitive.Speak" docsLink="#action-bar-primitive-speak" tooltip="Speaks the message content" />

    <Component name="ActionBarPrimitive.StopSpeaking" docsLink="#action-bar-primitive-stop-speaking" tooltip="Stops speaking the message" />

    <Component name="ActionBarPrimitive.FeedbackPositive" docsLink="#action-bar-primitive-feedback-positive" tooltip="Provides positive feedback" />

    <Component name="ActionBarPrimitive.FeedbackNegative" docsLink="#action-bar-primitive-feedback-negative" tooltip="Provides negative feedback" />
  </Component>

  BranchPickerPrimitive \[#branchpickerprimitive]

  <Component name="BranchPickerPrimitive.Root" docsLink="#branch-picker-primitive-root" tooltip="Root component for the branch picker">
    <Component name="BranchPickerPrimitive.Previous" docsLink="#branch-picker-primitive-previous" tooltip="Navigates to the previous branch" />

    <Component name="BranchPickerPrimitive.Number" docsLink="#branch-picker-primitive-number" tooltip="Displays the current branch number" />

    <Component name="BranchPickerPrimitive.Next" docsLink="#branch-picker-primitive-next" tooltip="Navigates to the next branch" />
  </Component>
</ContextLevel>

<ContextLevel color={contextColors["MessagePart Context"]}>
  MessagePart Context \[#messagepart-context]

  Manages the state and actions for message parts within messages

  MessagePartRuntime \[#messagepartruntime]

  * [`useMessagePart`](#use-content-part)
  * [`useMessagePartText`](#use-content-part-text)
  * [`useMessagePartReasoning`](#use-content-part-reasoning)
  * [`useMessagePartRuntime`](#use-content-part-runtime)

  MessagePartPrimitive \[#messagepartprimitive]

  <Component name="MessagePartPrimitive.Text" docsLink="#content-part-text" tooltip="Represents a text part of the message content" />

  MarkdownText \[#markdowntext]

  <Component name="MarkdownText" docsLink="#markdown-text" tooltip="Renders markdown text in the message" />
</ContextLevel>

<ContextLevel color={contextColors["Attachment Context"]}>
  Attachment Context \[#attachment-context]

  Manages the state and actions for attachments in messages and composer

  AttachmentRuntime \[#attachmentruntime]

  * [`useAttachment`](#use-attachment)
  * [`useAttachmentRuntime`](#use-attachment-runtime)

  AttachmentPrimitive \[#attachmentprimitive]

  <Component name="AttachmentPrimitive.Root" docsLink="#attachment-primitive-root" tooltip="Root component for an attachment">
    <Component name="AttachmentPrimitive.Name" docsLink="#attachment-primitive-name" tooltip="Displays the name of the attachment" />

    <Component name="AttachmentPrimitive.Delete" docsLink="#attachment-primitive-delete" tooltip="Deletes the attachment" />

    <Component name="AttachmentPrimitive.Thumb" docsLink="#attachment-primitive-thumb" tooltip="Displays a thumbnail of the attachment" />
  </Component>
</ContextLevel>

<ContextLevel color={contextColors["ThreadListItem Context"]}>
  ThreadListItem Context \[#threadlistitem-context]

  Manages the state and actions for individual thread list items

  ThreadListItemRuntime \[#threadlistitemruntime]

  * [`useThreadListItem`](#use-thread-list-item)
  * [`useThreadListItemRuntime`](#use-thread-list-item-runtime)

  ThreadListItem \[#threadlistitem]

  <Component name="ThreadListItemPrimitive.Root" docsLink="#thread-list-item-primitive-root" tooltip="Root component for a thread list item">
    <Component name="ThreadListItemPrimitive.Trigger" docsLink="#thread-list-item-primitive-trigger" tooltip="Trigger for thread list item actions">
      <Component name="ThreadListItemPrimitive.Name" docsLink="#thread-list-item-primitive-name" tooltip="Displays the name of the thread" />
    </Component>

    <Component name="ThreadListItemPrimitive.Archive" docsLink="#thread-list-item-primitive-archive" tooltip="Archives the thread" />

    <Component name="ThreadListItemPrimitive.Unarchive" docsLink="#thread-list-item-primitive-unarchive" tooltip="Unarchives the thread" />

    <Component name="ThreadListItemPrimitive.Delete" docsLink="#thread-list-item-primitive-delete" tooltip="Deletes the thread" />

    <Component name="ThreadListItemPrimitive.Rename" docsLink="#thread-list-item-primitive-rename" tooltip="Renames the thread" />
  </Component>
</ContextLevel>

Utilities \[#utilities]

* [`useThreadViewportAutoscroll`](#use-thread-viewport-autoscroll)
* [`useInlineRender`](#use-inline-render)


# Deprecation Policy
URL: /docs/migrations/deprecation-policy

Stability guarantees and deprecation timelines for assistant-ui features.

assistant-ui is committed to providing a stable API, so you can spend your time building amazing things on top of it.

Rarely, we need to deprecate a feature we've already shipped, because it is causing performance, usability, or security issues.
In such cases, we will communicate the intent to unship as soon as possible by marking the feature as `@deprecated` and publishing a notice in the documentation.

Deprecations and breaking changes primarily affect new features released. The longer an API has been in the library, the less likely it is to be deprecated.
For features that have long existed in the library, we will provide a longer deprecation notice period (as described below).

Below is a list of features considered stable and those considered experimental.

Experimental Features \[#experimental-features]

These features may be removed at any time without notice.

* Anything marked as `unstable_`, `experimental_`, or `internal`
* The `RuntimeCore` API (considered internal)

Beta Features \[#beta-features]

A deprecation of these features will undergo a short (\<1) month deprecation notice period.

* TailwindCSS Plugins (e.g. `@assistant-ui/react-ui/tailwindcss`)
* Context API
* Runtime API
* Message types
* Styled UI components
* Primitive Hooks (e.g. useBranchPickerNext)
* Attachment APIs
* shadcn/ui styles

Stable Features \[#stable-features]

A deprecation of these features will undergo a long (>3 month) deprecation notice period.

The following features are considered stable:

* Primitives (except for `AttachmentPrimitive`)


# Migrating to react-langgraph v0.7
URL: /docs/migrations/react-langgraph-v0-7

Guide to upgrading to the simplified LangGraph integration API.

Overview \[#overview]

This guide helps you migrate from the previous LangGraph integration pattern to the new simplified API introduced in `@assistant-ui/react-langgraph` v0.7. The new API consolidates thread management directly into `useLangGraphRuntime`, eliminating the need for separate runtime hooks and manual thread state management.

Key Changes \[#key-changes]

1. Simplified Thread Management \[#1-simplified-thread-management]

The `useLangGraphRuntime` hook now directly handles thread lifecycle:

* No more `useRemoteThreadListRuntime` wrapper
* No more separate runtime hook functions
* Thread management is built into the core runtime

2. New initialize Parameter \[#2-new-initialize-parameter]

The `stream` function now receives an `initialize` parameter that handles thread creation and loading automatically.

3. Direct Cloud Integration \[#3-direct-cloud-integration]

Cloud persistence can now be configured directly in `useLangGraphRuntime` with the `cloud` parameter.

Migration Steps \[#migration-steps]

<Steps>
  <Step>
    Update Your Runtime Implementation \[#update-your-runtime-implementation]

    Before (Old Pattern) \[#before-old-pattern]

    ```tsx
    import {
      useCloudThreadListRuntime,
      useThreadListItemRuntime,
    } from "@assistant-ui/react";
    import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";

    const useMyLangGraphRuntime = () => {
      const threadListItemRuntime = useThreadListItemRuntime();

      const runtime = useLangGraphRuntime({
        stream: async function* (messages) {
          const { externalId } = await threadListItemRuntime.initialize();
          if (!externalId) throw new Error("Thread not found");

          return sendMessage({
            threadId: externalId,
            messages,
          });
        },
        onSwitchToThread: async (externalId) => {
          const state = await getThreadState(externalId);
          return {
            messages: state.values.messages,
          };
        },
      });

      return runtime;
    };

    // In your component:
    const runtime = useCloudThreadListRuntime({
      cloud,
      runtimeHook: useMyLangGraphRuntime,
      create: async () => {
        const { thread_id } = await createThread();
        return { externalId: thread_id };
      },
    });
    ```

    After (New Pattern) \[#after-new-pattern]

    ```tsx
    import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";

    // Directly in your component:
    const runtime = useLangGraphRuntime({
      cloud, // Optional: for cloud persistence
      stream: async function* (messages, { initialize }) {
        const { externalId } = await initialize();
        if (!externalId) throw new Error("Thread not found");

        return sendMessage({
          threadId: externalId,
          messages,
        });
      },
      create: async () => {
        const { thread_id } = await createThread();
        return { externalId: thread_id };
      },
      load: async (externalId) => {
        const state = await getThreadState(externalId);
        return {
          messages: state.values.messages,
        };
      },
    });
    ```
  </Step>

  <Step>
    Update Import Statements \[#update-import-statements]

    Remove unused imports:

    ```diff
    - import {
    -   useCloudThreadListRuntime,
    -   useThreadListItemRuntime,
    - } from "@assistant-ui/react";
    + import { AssistantCloud } from "@assistant-ui/react";
    ```
  </Step>

  <Step>
    Simplify Component Structure \[#simplify-component-structure]

    You no longer need a separate runtime hook function. Everything can be defined directly in your component or provider:

    ```tsx
    export function MyRuntimeProvider({ children }) {
      const cloud = useMemo(
        () => new AssistantCloud({
          baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
        }),
        []
      );

      const runtime = useLangGraphRuntime({
        cloud,
        // All configuration inline
        stream: async function* (messages, { initialize }) {
          // Your stream implementation
        },
        create: async () => {
          // Your create implementation
        },
        load: async (externalId) => {
          // Your load implementation
        },
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Update Method Names \[#update-method-names]

    Rename methods to match the new API:

    * `onSwitchToThread` → `load`
    * `onSwitchToNewThread` → handled automatically via `create`
    * Thread ID management is now automatic
  </Step>
</Steps>

API Reference Changes \[#api-reference-changes]

Old API \[#old-api]

```typescript
type OldLangGraphRuntimeOptions = {
  threadId?: string;
  stream: (messages: Message[]) => AsyncGenerator;
  onSwitchToNewThread?: () => Promise<void>;
  onSwitchToThread?: (threadId: string) => Promise<ThreadState>;
};
```

New API \[#new-api]

```typescript
type NewLangGraphRuntimeOptions = {
  cloud?: AssistantCloud;
  stream: (
    messages: Message[],
    context: {
      initialize: () => Promise<{
        remoteId: string;
        externalId: string | undefined;
      }>
    }
  ) => AsyncGenerator;
  create?: () => Promise<{ externalId: string }>;
  load?: (externalId: string) => Promise<ThreadState>;
  delete?: (externalId: string) => Promise<void>;
};
```

Benefits of the New API \[#benefits-of-the-new-api]

1. **Simpler Setup**: No need for multiple runtime hooks and wrappers
2. **Cleaner Code**: All configuration in one place
3. **Better Type Safety**: More explicit types for thread management
4. **Automatic Thread Handling**: The runtime manages thread lifecycle internally
5. **Optional Cloud Integration**: Add cloud persistence with a single parameter

Common Migration Issues \[#common-migration-issues]

<Callout type="warning">
  **Breaking Change**: The `threadId` and `onSwitchToNewThread` parameters are no longer supported. Use the new `create` and `load` methods instead.
</Callout>

Issue: threadListItemRuntime is not defined \[#issue-threadlistitemruntime-is-not-defined]

**Solution**: Remove references to `useThreadListItemRuntime()`. Use the `initialize` parameter in the stream function instead.

Issue: Thread switching doesn't work \[#issue-thread-switching-doesnt-work]

**Solution**: Ensure you've implemented both `create` and `load` functions. The runtime needs both to manage thread lifecycle.

Issue: Cloud persistence not working \[#issue-cloud-persistence-not-working]

**Solution**: Pass the `AssistantCloud` instance directly to `useLangGraphRuntime` via the `cloud` parameter.

Example: Complete Migration \[#example-complete-migration]

Here's a complete before and after example for a typical LangGraph integration:

Before \[#before]

```tsx title="runtime-provider.tsx"
import {
  AssistantCloud,
  AssistantRuntimeProvider,
  useCloudThreadListRuntime,
  useThreadListItemRuntime,
} from "@assistant-ui/react";
import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";

const useMyRuntime = () => {
  const threadListItemRuntime = useThreadListItemRuntime();

  return useLangGraphRuntime({
    stream: async function* (messages) {
      const { externalId } = await threadListItemRuntime.initialize();
      // ... implementation
    },
    onSwitchToThread: async (externalId) => {
      // ... implementation
    },
  });
};

export function Provider({ children }) {
  const cloud = new AssistantCloud({ /* config */ });

  const runtime = useCloudThreadListRuntime({
    cloud,
    runtimeHook: useMyRuntime,
    create: async () => { /* ... */ },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

After \[#after]

```tsx title="runtime-provider.tsx"
import {
  AssistantCloud,
  AssistantRuntimeProvider,
} from "@assistant-ui/react";
import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";

export function Provider({ children }) {
  const cloud = new AssistantCloud({ /* config */ });

  const runtime = useLangGraphRuntime({
    cloud,
    stream: async function* (messages, { initialize }) {
      const { externalId } = await initialize();
      // ... implementation
    },
    create: async () => { /* ... */ },
    load: async (externalId) => {
      // ... implementation (formerly onSwitchToThread)
    },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

Need Help? \[#need-help]

If you encounter issues during migration:

1. Check the updated [LangGraph documentation](/docs/runtimes/langgraph)
2. Review the [example implementation](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)
3. Report issues on [GitHub](https://github.com/assistant-ui/assistant-ui/issues)


# Migration to v0.11
URL: /docs/migrations/v0-11

ContentPart renamed to MessagePart for better semantic clarity.

ContentPart renamed to MessagePart \[#contentpart-renamed-to-messagepart]

All ContentPart-related types, hooks, and components have been renamed to MessagePart for better semantic clarity and consistency.

What changed \[#what-changed]

The following types and components have been renamed:

Core Types \[#core-types]

* `TextContentPart` → `TextMessagePart`
* `ReasoningContentPart` → `ReasoningMessagePart`
* `SourceContentPart` → `SourceMessagePart`
* `ImageContentPart` → `ImageMessagePart`
* `FileContentPart` → `FileMessagePart`
* `Unstable_AudioContentPart` → `Unstable_AudioMessagePart`
* `ToolCallContentPart` → `ToolCallMessagePart`
* `ContentPartStatus` → `MessagePartStatus`
* `ToolCallContentPartStatus` → `ToolCallMessagePartStatus`

Thread Message Parts \[#thread-message-parts]

* `ThreadUserContentPart` → `ThreadUserMessagePart`
* `ThreadAssistantContentPart` → `ThreadAssistantMessagePart`

Runtime and State Types \[#runtime-and-state-types]

* `ContentPartRuntime` → `MessagePartRuntime`
* `ContentPartState` → `MessagePartState`

Hooks \[#hooks]

* `useContentPart` → `useMessagePart`
* `useContentPartRuntime` → `useMessagePartRuntime`
* `useContentPartText` → `useMessagePartText`
* `useContentPartReasoning` → `useMessagePartReasoning`
* `useContentPartSource` → `useMessagePartSource`
* `useContentPartFile` → `useMessagePartFile`
* `useContentPartImage` → `useMessagePartImage`
* `useTextContentPart` → `useTextMessagePart`

Component Types \[#component-types]

* `EmptyContentPartComponent` → `EmptyMessagePartComponent`
* `TextContentPartComponent` → `TextMessagePartComponent`
* `ReasoningContentPartComponent` → `ReasoningMessagePartComponent`
* `SourceContentPartComponent` → `SourceMessagePartComponent`
* `ImageContentPartComponent` → `ImageMessagePartComponent`
* `FileContentPartComponent` → `FileMessagePartComponent`
* `Unstable_AudioContentPartComponent` → `Unstable_AudioMessagePartComponent`
* `ToolCallContentPartComponent` → `ToolCallMessagePartComponent`

Props Types \[#props-types]

* `EmptyContentPartProps` → `EmptyMessagePartProps`
* `TextContentPartProps` → `TextMessagePartProps`
* `ReasoningContentPartProps` → `ReasoningMessagePartProps`
* `SourceContentPartProps` → `SourceMessagePartProps`
* `ImageContentPartProps` → `ImageMessagePartProps`
* `FileContentPartProps` → `FileMessagePartProps`
* `Unstable_AudioContentPartProps` → `Unstable_AudioMessagePartProps`
* `ToolCallContentPartProps` → `ToolCallMessagePartProps`

Providers and Context \[#providers-and-context]

* `TextContentPartProvider` → `TextMessagePartProvider`
* `TextContentPartProviderProps` → `TextMessagePartProviderProps`
* `ContentPartRuntimeProvider` → `MessagePartRuntimeProvider`
* `ContentPartContext` → `MessagePartContext`
* `ContentPartContextValue` → `MessagePartContextValue`

Primitives \[#primitives]

* `ContentPartPrimitive` → `MessagePartPrimitive`
* `ContentPartPrimitiveText` → `MessagePartPrimitiveText`
* `ContentPartPrimitiveImage` → `MessagePartPrimitiveImage`
* `ContentPartPrimitiveInProgress` → `MessagePartPrimitiveInProgress`

MessagePrimitive.Content renamed to MessagePrimitive.Parts \[#messageprimitivecontent-renamed-to-messageprimitiveparts]

The `MessagePrimitive.Content` component has been renamed to `MessagePrimitive.Parts` to better reflect its purpose of rendering message parts.

```diff
-<MessagePrimitive.Content components={{ Text: MyText }} />
+<MessagePrimitive.Parts components={{ Text: MyText }} />
```

Migration \[#migration]

To migrate your codebase automatically, use the migration codemod:

```sh
# IMPORTANT: make sure to commit all changes to git / create a backup before running the codemod
npx @assistant-ui/cli upgrade
```

Or run the specific migration:

```sh
npx @assistant-ui/cli codemod v0-11/content-part-to-message-part .
```

Manual Migration Examples \[#manual-migration-examples]

If you prefer to migrate manually, here are some examples:

**Imports:**

```diff
-import { TextContentPart, useContentPart, ToolCallContentPartComponent } from "@assistant-ui/react";
+import { TextMessagePart, useMessagePart, ToolCallMessagePartComponent } from "@assistant-ui/react";
```

**Type annotations:**

```diff
-function processContent(part: TextContentPart): void {
+function processContent(part: TextMessagePart): void {
   console.log(part.text);
 }

-const MyTool: ToolCallContentPartComponent = ({ toolName }) => {
+const MyTool: ToolCallMessagePartComponent = ({ toolName }) => {
   return <div>{toolName}</div>;
 };
```

**Hooks:**

```diff
 function MyComponent() {
-  const part = useContentPart();
-  const text = useContentPartText();
-  const runtime = useContentPartRuntime();
+  const part = useMessagePart();
+  const text = useMessagePartText();
+  const runtime = useMessagePartRuntime();
   return null;
 }
```

**JSX Components:**

```diff
-<ContentPartPrimitive.Text />
-<ContentPartPrimitive.Image />
+<MessagePartPrimitive.Text />
+<MessagePartPrimitive.Image />
```

**Providers:**

```diff
-<TextContentPartProvider text="Hello" isRunning={false}>
+<TextMessagePartProvider text="Hello" isRunning={false}>
   <div>Content</div>
-</TextContentPartProvider>
+</TextMessagePartProvider>
```

Why this change? \[#why-this-change]

The ContentPart naming was inconsistent with the rest of the codebase, where "message parts" are used throughout. This change improves semantic clarity and makes the API more intuitive by aligning terminology across the entire library.

The old ContentPart APIs continue to work but are now deprecated and will be removed in a future major version.


# Migration to v0.12
URL: /docs/migrations/v0-12

Unified state API replaces individual context hooks.

Major Architecture Change: Unified State API \[#major-architecture-change-unified-state-api]

Version 0.12 introduces a complete rewrite of the state management system with a more consistent API.

Automatic Migration \[#automatic-migration]

We provide a codemod to automatically migrate your code:

```bash
npx assistant-ui@latest upgrade
```

This will automatically handle the hook renames and update your imports.

Breaking Changes \[#breaking-changes]

1. Assistant API Hooks Renamed \[#1-assistant-api-hooks-renamed]

The core hooks have been renamed for consistency and clarity:

* `useAssistantApi` → `useAui`
* `useAssistantState` → `useAuiState`
* `useAssistantEvent` → `useAuiEvent`

The variable naming convention has also changed from `api` to `aui`.

Migration \[#migration]

**Before:**

```tsx
import {
  useAssistantApi,
  useAssistantState,
  useAssistantEvent,
} from "@assistant-ui/react";

function MyComponent() {
  const api = useAssistantApi();
  const isRunning = useAssistantState(({ thread }) => thread.isRunning);

  useAssistantEvent("thread.started", () => {
    console.log("Thread started");
  });

  const handleSend = () => {
    api.composer().send();
  };

  return <button onClick={handleSend}>Send</button>;
}
```

**After:**

```tsx
import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";

function MyComponent() {
  const aui = useAui();
  const isRunning = useAuiState((s) => s.thread.isRunning);

  useAuiEvent("thread.started", () => {
    console.log("Thread started");
  });

  const handleSend = () => {
    aui.composer().send();
  };

  return <button onClick={handleSend}>Send</button>;
}
```

**Automatic Migration:**

Run the codemod to automatically update your code:

```bash
npx assistant-ui@latest upgrade
```

The codemod will:

* Rename all hook imports (`useAssistantApi` → `useAui`, etc.)
* Rename `const api = useAui()` declarations to `const aui = useAui()`
* Update all references to the `api` variable throughout your codebase
* Correctly handle scoping (won't rename `api` variables from other sources)

**Backwards Compatibility:**

The old names are still available as deprecated exports until v0.13:

```tsx
// Still works, but deprecated
import {
  useAssistantApi,
  useAssistantState,
  useAssistantEvent,
} from "@assistant-ui/react";

const api = useAssistantApi(); // deprecated but functional
```

2. Context Hooks Replaced with Unified State API \[#2-context-hooks-replaced-with-unified-state-api]

All individual context hooks have been replaced with a single `useAuiState` hook and `useAui` for actions.

What changed \[#what-changed]

The following hooks have been removed:

**Removed Hooks:**

* `useMessageUtils` → Use `useAuiState((s) => s.message.isHovering)` / `useAuiState((s) => s.message.isCopied)`
* `useMessageUtilsStore` → Use `useAui()` with `aui.message().setIsHovering()` / `aui.message().setIsCopied()`
* `useToolUIs` → Use `useAuiState((s) => s.tools)` and `useAui()` with `aui.tools()`
* `useToolUIsStore` → Use `useAui()` with `aui.tools()`

**Deprecated Hooks:**

* `useAssistantRuntime` → Use `useAui()`
* `useThread` → Use `useAuiState((s) => s.thread)`
* `useThreadRuntime` → Use `useAui()` with `aui.thread()`
* `useMessage` → Use `useAuiState((s) => s.message)`
* `useMessageRuntime` → Use `useAui()` with `aui.message()`
* `useComposer` → Use `useAuiState((s) => s.composer)`
* `useComposerRuntime` → Use `useAui()` with `aui.composer()`
* `useEditComposer` → Use `useAuiState((s) => s.message.composer)`
* `useThreadListItem` → Use `useAuiState((s) => s.threadListItem)`
* `useThreadListItemRuntime` → Use `useAui()` with `aui.threadListItem()`
* `useMessagePart` → Use `useAuiState((s) => s.part)`
* `useMessagePartRuntime` → Use `useAui()` with `aui.part()`
* `useAttachment` → Use `useAuiState((s) => s.attachment)`
* `useAttachmentRuntime` → Use `useAui()` with `aui.attachment()`
* `useThreadModelContext` / `useThreadModelConfig` → Use `useAuiState((s) => s.thread.modelContext)`
* `useThreadComposer` → Use `useAuiState((s) => s.thread.composer)`
* `useThreadList` → Use `useAuiState((s) => s.threads)`

Migration Examples \[#migration-examples]

**Before:**

```tsx
import {
  useThread,
  useThreadRuntime,
  useComposer,
  useComposerRuntime,
  useMessage,
  useMessageRuntime,
} from "@assistant-ui/react";

function MyComponent() {
  // Reading state
  const messages = useThread((t) => t.messages);
  const isRunning = useThread((t) => t.isRunning);
  const composerText = useComposer((c) => c.text);
  const messageRole = useMessage((m) => m.role);

  // Using runtime for actions
  const threadRuntime = useThreadRuntime();
  const composerRuntime = useComposerRuntime();
  const messageRuntime = useMessageRuntime();

  const handleSend = () => {
    composerRuntime.send();
  };

  const handleReload = () => {
    messageRuntime.reload();
  };

  const handleCancel = () => {
    threadRuntime.cancelRun();
  };

  return null;
}
```

**After:**

```tsx
import { useAuiState, useAui } from "@assistant-ui/react";

function MyComponent() {
  // Reading state - all through single hook
  const messages = useAuiState((s) => s.thread.messages);
  const isRunning = useAuiState((s) => s.thread.isRunning);
  const composerText = useAuiState((s) => s.composer.text);
  const messageRole = useAuiState((s) => s.message.role);

  // Using client for actions
  const aui = useAui();

  const handleSend = () => {
    aui.composer().send();
  };

  const handleReload = () => {
    aui.message().reload();
  };

  const handleCancel = () => {
    aui.thread().cancelRun();
  };

  return null;
}
```

3. Event Names Changed to camelCase \[#3-event-names-changed-to-camelcase]

Event names used with `useAuiEvent` have been standardized to use camelCase instead of kebab-case.

What changed \[#what-changed-1]

The following event names have been updated:

| Old Name (kebab-case)            | New Name (camelCase)          |
| -------------------------------- | ----------------------------- |
| `thread.run-start`               | `thread.runStart`             |
| `thread.run-end`                 | `thread.runEnd`               |
| `thread.model-context-update`    | `thread.modelContextUpdate`   |
| `composer.attachment-add`        | `composer.attachmentAdd`      |
| `thread-list-item.switched-to`   | `threadListItem.switchedTo`   |
| `thread-list-item.switched-away` | `threadListItem.switchedAway` |

Events that remain unchanged:

* `thread.initialize`
* `composer.send`

Migration \[#migration-1]

**Before:**

```tsx
import { useAuiEvent } from "@assistant-ui/react";

function MyComponent() {
  useAuiEvent("thread.run-start", () => {
    console.log("Thread started running");
  });

  useAuiEvent("thread.run-end", () => {
    console.log("Thread finished running");
  });

  useAuiEvent("composer.attachment-add", () => {
    console.log("Attachment added");
  });

  return null;
}
```

**After:**

```tsx
import { useAuiEvent } from "@assistant-ui/react";

function MyComponent() {
  useAuiEvent("thread.runStart", () => {
    console.log("Thread started running");
  });

  useAuiEvent("thread.runEnd", () => {
    console.log("Thread finished running");
  });

  useAuiEvent("composer.attachmentAdd", () => {
    console.log("Attachment added");
  });

  return null;
}
```

**Automatic Migration:**

Run the codemod to automatically update event names:

```bash
npx assistant-ui@latest upgrade
```

The codemod will automatically replace all occurrences of the old kebab-case event names with their new camelCase equivalents.

Getting Help \[#getting-help]

If you encounter issues during migration:

1. Check the updated API documentation for detailed examples
2. Review the example applications in the repository
3. Report issues at [https://github.com/assistant-ui/assistant-ui/issues](https://github.com/assistant-ui/assistant-ui/issues)


# AI SDK v4 (Legacy)
URL: /docs/runtimes/ai-sdk/v4-legacy

Legacy integration for Vercel AI SDK v4 using data stream runtime.

Overview \[#overview]

If you're using AI SDK v4 (legacy), you can integrate with assistant-ui using the `@assistant-ui/react-data-stream` package and its `useDataStreamRuntime` hook. This provides a compatible runtime that works with AI SDK v4's streaming responses.

<Callout type="warning">
  AI SDK v4 is now considered legacy. We recommend upgrading to [AI SDK
  v5](/docs/runtimes/ai-sdk/use-chat) for improved features and better
  TypeScript support. This documentation is provided for projects that haven't
  migrated yet.
</Callout>

Getting Started \[#getting-started]

Option 1: Using @assistant-ui/react-data-stream (Recommended) \[#option-1-using-assistant-uireact-data-stream-recommended]

<Steps>
  <Step>
    Install the required packages \[#install-the-required-packages]

    Install `@assistant-ui/react-data-stream` alongside assistant-ui and AI SDK v4:

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-data-stream", "ai@^4"]} />
  </Step>

  <Step>
    Setup your backend route \[#setup-your-backend-route]

    Create an API route that uses AI SDK v4's streaming capabilities:

    `@/app/api/chat/route.ts`

    ```tsx
    import { streamText } from "ai";
    import { openai } from "@ai-sdk/openai";

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = streamText({
        model: openai("gpt-4"),
        messages,
      });

      return result.toDataStreamResponse();
    }
    ```
  </Step>

  <Step>
    Use useDataStreamRuntime in your component \[#use-usedatastreamruntime-in-your-component]

    `@/app/page.tsx`

    ```tsx
    "use client";

    import { Thread } from "@assistant-ui/react";
    import { AssistantRuntimeProvider } from "@assistant-ui/react";
    import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";

    export default function Home() {
      const runtime = useDataStreamRuntime({
        api: "/api/chat",
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <div className="h-full">
            <Thread />
          </div>
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

Option 2: Using @assistant-ui/react-ai-sdk v0.1.10 (Legacy) \[#option-2-using-assistant-uireact-ai-sdk-v0110-legacy]

Alternatively, you can use the older version of the AI SDK integration package, though this version is no longer actively maintained:

<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk@0.1.10", "ai@^4"]} />

<Callout type="warning">
  Version 0.1.10 of `@assistant-ui/react-ai-sdk` is no longer actively
  maintained. We recommend using the `@assistant-ui/react-data-stream` approach
  or upgrading to AI SDK v5 for continued support.
</Callout>

With this legacy version, you would use the `useVercelUseChatRuntime` hook:

```tsx
"use client";

import { useChat } from "ai/react";
import { Thread } from "@assistant-ui/react";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useVercelUseChatRuntime } from "@assistant-ui/react-ai-sdk";

export default function Home() {
  const chat = useChat({
    api: "/api/chat",
  });
  const runtime = useVercelUseChatRuntime(chat);

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <div className="h-full">
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}
```

API Reference \[#api-reference]

useDataStreamRuntime \[#usedatastreamruntime]

The `useDataStreamRuntime` hook creates a runtime compatible with assistant-ui from AI SDK v4's streaming responses.

```tsx
import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";

const runtime = useDataStreamRuntime({
  api: "/api/chat",
  // Options similar to AI SDK v4's useChat
  initialMessages: [],
  onFinish: (message) => {
    console.log("Message completed:", message);
  },
  onError: (error) => {
    console.error("Chat error:", error);
  },
});
```

Options \[#options]

The `useDataStreamRuntime` hook accepts options similar to AI SDK v4's `useChat` hook:

* **`api`**: The API endpoint for chat requests (required)
* **`initialMessages`**: Initial messages to populate the chat
* **`onFinish`**: Callback when a message completes streaming
* **`onError`**: Callback for handling errors
* **`headers`**: Additional headers to send with requests
* **`body`**: Additional body parameters to send with requests

<Callout type="info">
  The `useDataStreamRuntime` API is designed to be familiar to developers
  already using AI SDK v4's `useChat` hook, making migration straightforward.
</Callout>

Migration to AI SDK v5 \[#migration-to-ai-sdk-v5]

When you're ready to upgrade to AI SDK v5:

1. Replace `@assistant-ui/react-data-stream` with `@assistant-ui/react-ai-sdk`
2. Update your backend to use AI SDK v5's `streamText` API
3. Switch from `useDataStreamRuntime` to `useChatRuntime`
4. Take advantage of improved TypeScript support and automatic system/tool forwarding

See our [AI SDK v5 documentation](/docs/runtimes/ai-sdk/use-chat) for the complete migration guide.

Example \[#example]

For a working example with AI SDK v4, you can adapt the patterns from our [AI SDK examples](https://github.com/assistant-ui/assistant-ui/tree/main/examples) using the `@assistant-ui/react-data-stream` package instead of the v5 integration.


# AI SDK v5 (Legacy)
URL: /docs/runtimes/ai-sdk/v5-legacy

Integrate Vercel AI SDK v5 with useChatRuntime for streaming chat.

<Callout type="error">
  AI SDK v5 is no longer supported. The `@assistant-ui/react-ai-sdk` package now requires AI SDK v6+.
  Please upgrade to [AI SDK v6](/docs/runtimes/ai-sdk/v6).
</Callout>

Overview \[#overview]

This documentation is preserved for reference. For new projects, use [AI SDK v6](/docs/runtimes/ai-sdk/v6).

Getting Started \[#getting-started]

<Steps>
  <Step>
    Create a Next.js project \[#create-a-nextjs-project]

    ```sh
    npx create-next-app@latest my-app
    cd my-app
    ```
  </Step>

  <Step>
    Install AI SDK v5 and @assistant-ui/react \[#install-ai-sdk-v5-and-assistant-uireact]

    ```sh
    npm install @assistant-ui/react @assistant-ui/react-ai-sdk@0.x ai@^5 @ai-sdk/openai@^1 zod
    ```
  </Step>

  <Step>
    Setup a backend route under /api/chat \[#setup-a-backend-route-under-apichat]

    `@/app/api/chat/route.ts`

    ```tsx
    import { openai } from "@ai-sdk/openai";
    import { streamText, tool } from "ai";
    import type { Message } from "ai";
    import { z } from "zod";

    export const maxDuration = 30;

    export async function POST(req: Request) {
      const { messages }: { messages: Message[] } = await req.json();

      const result = streamText({
        model: openai("gpt-4o"),
        messages,
        tools: {
          get_current_weather: tool({
            description: "Get the current weather",
            parameters: z.object({
              city: z.string(),
            }),
            execute: async ({ city }) => {
              return `The weather in ${city} is sunny`;
            },
          }),
        },
      });

      return result.toDataStreamResponse();
    }
    ```
  </Step>

  <Step>
    Setup the frontend \[#setup-the-frontend]

    `@/app/page.tsx`

    ```tsx
    "use client";

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

    export default function Home() {
      const runtime = useChatRuntime({
        api: "/api/chat",
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <div className="h-full">
            <Thread />
          </div>
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

Key Differences from v6 \[#key-differences-from-v6]

| Feature                    | v5                            | v6                                        |
| -------------------------- | ----------------------------- | ----------------------------------------- |
| **ai package**             | `ai@^5`                       | `ai@^6`                                   |
| **@ai-sdk/openai**         | `@ai-sdk/openai@^1`           | `@ai-sdk/openai@^3`                       |
| **Message type**           | `Message`                     | `UIMessage`                               |
| **convertToModelMessages** | Sync                          | Async (`await`)                           |
| **Tool schema**            | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |
| **Response**               | `toDataStreamResponse()`      | `toUIMessageStreamResponse()`             |

Migration to v6 \[#migration-to-v6]

See the [AI SDK v6 documentation](/docs/runtimes/ai-sdk/v6) for the latest integration guide.


# AI SDK v6
URL: /docs/runtimes/ai-sdk/v6

Integrate Vercel AI SDK v6 with assistant-ui for streaming chat.

Overview \[#overview]

Integration with the Vercel AI SDK v6 using the `useChatRuntime` hook from `@assistant-ui/react-ai-sdk`.

Getting Started \[#getting-started]

<Steps>
  <Step>
    Create a Next.js project \[#create-a-nextjs-project]

    ```sh
    npx create-next-app@latest my-app
    cd my-app
    ```
  </Step>

  <Step>
    Install dependencies \[#install-dependencies]

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ai-sdk", "ai@^6", "@ai-sdk/react@^3", "@ai-sdk/openai", "zod"]} />
  </Step>

  <Step>
    Setup a backend route under /api/chat \[#setup-a-backend-route-under-apichat]

    `@/app/api/chat/route.ts`

    ```tsx
    import { openai } from "@ai-sdk/openai";
    import {
      streamText,
      convertToModelMessages,
      tool,
      zodSchema,
    } from "ai";
    import type { UIMessage } from "ai";
    import { z } from "zod";

    export const maxDuration = 30;

    export async function POST(req: Request) {
      const { messages }: { messages: UIMessage[] } = await req.json();

      const result = streamText({
        model: openai("gpt-4o"),
        messages: await convertToModelMessages(messages), // Note: async in v6
        tools: {
          get_current_weather: tool({
            description: "Get the current weather",
            inputSchema: zodSchema(
              z.object({
                city: z.string(),
              }),
            ),
            execute: async ({ city }) => {
              return `The weather in ${city} is sunny`;
            },
          }),
        },
      });

      return result.toUIMessageStreamResponse();
    }
    ```
  </Step>

  <Step>
    Setup the frontend \[#setup-the-frontend]

    `@/app/page.tsx`

    ```tsx
    "use client";

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

    export default function Home() {
      const runtime = useChatRuntime();

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <div className="h-full">
            <Thread />
          </div>
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

Tracking Token Usage \[#tracking-token-usage]

assistant-ui exports a `useThreadTokenUsage` hook to access thread-level token usage on the client.

<Steps>
  <Step>
    Use `messageMetadata` in your Next.js route to attach `usage` from `finish` and `modelId` from `finish-step`.

    ```tsx
    import { streamText, convertToModelMessages } from "ai";
    import { frontendTools } from "@assistant-ui/react-ai-sdk";
    export async function POST(req: Request) {
      const { messages, tools, modelName } = await req.json();
      const result = streamText({
        model: getModel(modelName),
        messages: await convertToModelMessages(messages),
        tools: frontendTools(tools),
      });
      return result.toUIMessageStreamResponse({
        messageMetadata: ({ part }) => {
          if (part.type === "finish") {
            return {
              usage: part.totalUsage,
            };
          }
          if (part.type === "finish-step") {
            return {
              modelId: part.response.modelId,
            };
          }
          return undefined;
        },
      });
    }
    ```
  </Step>

  <Step>
    Use `useThreadTokenUsage` to render token usage on the client.

    ```tsx
    "use client";

    import { useThreadTokenUsage } from "@assistant-ui/react-ai-sdk";

    export function TokenCounter() {
      const usage = useThreadTokenUsage();

      if (!usage) return null;

      return <div>{usage.totalTokens} total tokens</div>;
    }
    ```
  </Step>
</Steps>

Key Changes from v5 \[#key-changes-from-v5]

| Feature                    | v5                            | v6                                        |
| -------------------------- | ----------------------------- | ----------------------------------------- |
| **ai package**             | `ai@^5`                       | `ai@^6`                                   |
| **@ai-sdk/react**          | `@ai-sdk/react@^2`            | `@ai-sdk/react@^3`                        |
| **convertToModelMessages** | Sync                          | Async (`await`)                           |
| **Tool schema**            | `parameters: z.object({...})` | `inputSchema: zodSchema(z.object({...}))` |

API Reference \[#api-reference]

useChatRuntime \[#usechatruntime]

Creates a runtime integrated with AI SDK's `useChat` hook.

```tsx
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime();
```

Custom API URL \[#custom-api-url]

To use a different endpoint, pass a custom `AssistantChatTransport`:

```tsx
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

System Messages and Frontend Tools \[#system-messages-and-frontend-tools]

`AssistantChatTransport` (used by default) automatically forwards system messages and frontend tools to your backend. To consume them, update your backend route:

Backend route with system/tools forwarding:

```tsx
import { openai } from "@ai-sdk/openai";
import { streamText, convertToModelMessages, zodSchema } from "ai";
import type { UIMessage } from "ai";
import { frontendTools } from "@assistant-ui/react-ai-sdk";

export async function POST(req: Request) {
  const {
    messages,
    system,
    tools,
  }: {
    messages: UIMessage[];
    system?: string;
    tools?: any;
  } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system,
    messages: await convertToModelMessages(messages),
    tools: {
      ...frontendTools(tools),
      // your backend tools...
    },
  });

  return result.toUIMessageStreamResponse();
}
```

useAISDKRuntime (Advanced) \[#useaisdkruntime-advanced]

For advanced use cases where you need direct access to the `useChat` hook:

```tsx
import { useChat } from "@ai-sdk/react";
import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";

const chat = useChat();
const runtime = useAISDKRuntime(chat);
```

Example \[#example]

For a complete example, check out the [AI SDK v6 example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v6) in our repository.


# Custom Thread List
URL: /docs/runtimes/custom/custom-thread-list

Plug a custom thread database for multi-thread persistence.

Overview \[#overview]

`useRemoteThreadListRuntime` lets you plug a custom thread database into assistant-ui. It keeps the UI and local runtime logic in sync while you provide persistence, archiving, and metadata for every conversation. The hook is exported as `unstable_useRemoteThreadListRuntime`; we refer to it here as **Custom Thread List**.

When to Use \[#when-to-use]

Use a Custom Thread List when you need to:

* Persist conversations in your own database or multitenant backend
* Share threads across devices, teams, or long-lived sessions
* Control thread metadata (titles, archived state, external identifiers)
* Layer additional adapters (history, attachments) around each thread runtime

How It Works \[#how-it-works]

Custom Thread List merges two pieces of state:

1. **Per-thread runtime** – powered by any runtime hook (for example `useLocalRuntime` or `useAssistantTransportRuntime`).
2. **Thread list adapter** – your adapter that reads and writes thread metadata in a remote store.

When the hook mounts it calls `list()` on your adapter, hydrates existing threads, and uses your runtime hook to spawn a runtime whenever a thread is opened. Creating a new conversation calls `initialize(threadId)` so you can create a record server-side and return the canonical `remoteId`.

<Callout type="info">
  The built-in Assistant Cloud runtime is implemented with the same API. Inspect
  `useCloudThreadListAdapter` for a production-ready reference adapter.
</Callout>

Build a Custom Thread List \[#build-a-custom-thread-list]

<Steps>
  <Step>
    Provide a runtime per thread \[#provide-a-runtime-per-thread]

    Use any runtime hook that returns an `AssistantRuntime`. In most custom setups this is `useLocalRuntime(modelAdapter)` or `useAssistantTransportRuntime(...)`.
  </Step>

  <Step>
    Implement the adapter contract \[#implement-the-adapter-contract]

    Your adapter decides how threads are stored. Implement the methods in the table below to connect to your database or API.
  </Step>

  <Step>
    Compose the provider \[#compose-the-provider]

    Wrap `AssistantRuntimeProvider` with the runtime returned from the Custom Thread List hook.

    ```tsx twoslash title="app/CustomThreadListProvider.tsx"
    // @filename: app/model-adapter.ts
    export const myModelAdapter = {} as any;

    // @filename: app/CustomThreadListProvider.tsx
    // ---cut---
    "use client";

    import type { ReactNode } from "react";
    import {
      AssistantRuntimeProvider,
      useLocalRuntime,
      unstable_useRemoteThreadListRuntime as useRemoteThreadListRuntime,
      type unstable_RemoteThreadListAdapter as RemoteThreadListAdapter,
    } from "@assistant-ui/react";
    import { createAssistantStream } from "assistant-stream";
    import { myModelAdapter } from "./model-adapter"; // your chat model adapter

    const threadListAdapter: RemoteThreadListAdapter = {
      async list() {
        const response = await fetch("/api/threads");
        const threads = await response.json();
        return {
          threads: threads.map((thread: any) => ({
            remoteId: thread.id,
            externalId: thread.external_id ?? undefined,
            status: thread.is_archived ? "archived" : "regular",
            title: thread.title ?? undefined,
          })),
        };
      },
      async initialize(localId) {
        const response = await fetch("/api/threads", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ localId }),
        });
        const result = await response.json();
        return { remoteId: result.id, externalId: result.external_id };
      },
      async rename(remoteId, title) {
        await fetch(`/api/threads/${remoteId}`, {
          method: "PATCH",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ title }),
        });
      },
      async archive(remoteId) {
        await fetch(`/api/threads/${remoteId}/archive`, { method: "POST" });
      },
      async unarchive(remoteId) {
        await fetch(`/api/threads/${remoteId}/unarchive`, { method: "POST" });
      },
      async delete(remoteId) {
        await fetch(`/api/threads/${remoteId}`, { method: "DELETE" });
      },
      async fetch(remoteId) {
        const response = await fetch(`/api/threads/${remoteId}`);
        const thread = await response.json();
        return {
          status: thread.is_archived ? "archived" : "regular",
          remoteId: thread.id,
          title: thread.title,
        };
      },
      async generateTitle(remoteId, messages) {
        return createAssistantStream(async (controller) => {
          const response = await fetch(`/api/threads/${remoteId}/title`, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ messages }),
          });
          const { title } = await response.json();
          controller.appendText(title);
        });
      },
    };

    export function CustomThreadListProvider({
      children,
    }: Readonly<{ children: ReactNode }>) {
      const runtime = useRemoteThreadListRuntime({
        runtimeHook: () => useLocalRuntime(myModelAdapter),
        adapter: threadListAdapter,
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

Adapter Responsibilities \[#adapter-responsibilities]

<ParametersTable
  type="RemoteThreadListAdapter"
  parameters={[
{
  name: "list",
  type: "() => Promise<{ threads: RemoteThreadMetadata[] }>",
  description:
    "Return the current threads. Each thread must include status, remoteId, and any metadata you want to show immediately.",
  required: true,
},
{
  name: "initialize",
  type: "(localId: string) => Promise<{ remoteId: string; externalId?: string }>",
  description:
    "Create a new remote record when the user starts a conversation. Return the canonical ids so later operations target the right thread.",
  required: true,
},
{
  name: "rename",
  type: "(remoteId: string, title: string) => Promise<void>",
  description: "Persist title changes triggered from the UI.",
  required: true,
},
{
  name: "archive",
  type: "(remoteId: string) => Promise<void>",
  description: "Mark the thread as archived in your system.",
  required: true,
},
{
  name: "unarchive",
  type: "(remoteId: string) => Promise<void>",
  description: "Restore an archived thread to the active list.",
  required: true,
},
{
  name: "delete",
  type: "(remoteId: string) => Promise<void>",
  description: "Permanently remove the thread and stop rendering it.",
  required: true,
},
{
  name: "generateTitle",
  type: "(remoteId: string, unstable_messages: readonly ThreadMessage[]) => Promise<AssistantStream>",
  description:
    "Return a streaming title generator. You can reuse your model endpoint or queue a background job.",
  required: true,
},
{
  name: "unstable_Provider",
  type: "ComponentType<PropsWithChildren>",
  description:
    "Optional wrapper rendered around all thread runtimes. Use it to inject adapters such as history or attachments (see the Cloud adapter).",
},
]}
/>

Thread Lifecycle Cheatsheet \[#thread-lifecycle-cheatsheet]

* `list()` hydrates threads on mount and during refreshes.
* Creating a new conversation calls `initialize()` once the user sends the first message.
* `archive`, `unarchive`, and `delete` are called optimistically; throw to revert the UI.
* `generateTitle()` powers the automatic title button and expects an `AssistantStream`.
* Provide a `runtimeHook` that always returns a fresh runtime instance per active thread.

Avoiding Race Conditions in History Adapters \[#avoiding-race-conditions-in-history-adapters]

<Callout type="warn">
  When implementing a custom history adapter, you must await thread initialization before saving messages. Failing to do so can cause the first message to be lost due to a race condition.
</Callout>

If you're building a history adapter that persists messages to your own database, use `aui.threadListItem().initialize()` to ensure the thread is fully initialized before saving:

```tsx
import { useAui } from "@assistant-ui/react";

// Inside your unstable_Provider component
const aui = useAui();

const history = useMemo<ThreadHistoryAdapter>(
  () => ({
    async append(message) {
      // Wait for initialization to complete and get the remoteId
      const { remoteId } = await aui.threadListItem().initialize();

      // Now safe to save the message using the remoteId
      await saveMessageToDatabase(remoteId, message);
    },
    // ...
  }),
  [aui],
);
```

The `initialize()` method:

* Can be called multiple times safely
* Always waits for the initial `initialize()` call to complete
* Returns the same `remoteId` on subsequent calls

See `AssistantCloudThreadHistoryAdapter` in the source code for a production-ready reference implementation.

Optional Adapters \[#optional-adapters]

If you need history or attachment support, expose them via `unstable_Provider`. The cloud implementation wraps each thread runtime with `RuntimeAdapterProvider` to inject:

* `history` – e.g. `useAssistantCloudThreadHistoryAdapter`
* `attachments` – e.g. `CloudFileAttachmentAdapter`

Reuse that pattern to register any capability your runtime requires.


# ExternalStoreRuntime
URL: /docs/runtimes/custom/external-store

Bring your own Redux, Zustand, or state manager.

Overview \[#overview]

`ExternalStoreRuntime` bridges your existing state management with assistant-ui components. It requires an `ExternalStoreAdapter<TMessage>` that handles communication between your state and the UI.

**Key differences from `LocalRuntime`:**

* **You own the state** - Full control over message state, thread management, and persistence logic
* **Bring your own state management** - Works with Redux, Zustand, TanStack Query, or any React state library
* **Custom message formats** - Use your backend's message structure with automatic conversion

<Callout type="warn">
  `ExternalStoreRuntime` gives you total control over state (persist, sync,
  share), but you must wire up every callback.
</Callout>

Example Implementation \[#example-implementation]

```tsx twoslash title="app/MyRuntimeProvider.tsx"
type MyMessage = {
  role: "user" | "assistant";
  content: string;
};
const backendApi = async (input: string): Promise<MyMessage> => {
  return { role: "assistant", content: "Hello, world!" };
};

// ---cut---
import { useState, ReactNode } from "react";
import {
  useExternalStoreRuntime,
  ThreadMessageLike,
  AppendMessage,
  AssistantRuntimeProvider,
} from "@assistant-ui/react";

const convertMessage = (message: MyMessage): ThreadMessageLike => {
  return {
    role: message.role,
    content: [{ type: "text", text: message.content }],
  };
};

export function MyRuntimeProvider({
  children,
}: Readonly<{
  children: ReactNode;
}>) {
  const [isRunning, setIsRunning] = useState(false);
  const [messages, setMessages] = useState<MyMessage[]>([]);

  const onNew = async (message: AppendMessage) => {
    if (message.content[0]?.type !== "text")
      throw new Error("Only text messages are supported");

    const input = message.content[0].text;
    setMessages((currentConversation) => [
      ...currentConversation,
      { role: "user", content: input },
    ]);

    setIsRunning(true);
    const assistantMessage = await backendApi(input);
    setMessages((currentConversation) => [
      ...currentConversation,
      assistantMessage,
    ]);
    setIsRunning(false);
  };

  const runtime = useExternalStoreRuntime({
    isRunning,
    messages,
    convertMessage,
    onNew,
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

When to Use \[#when-to-use]

Use `ExternalStoreRuntime` if you need:

* **Full control over message state** - Manage messages with Redux, Zustand, TanStack Query, or any React state management library
* **Custom multi-thread implementation** - Build your own thread management system with custom storage
* **Integration with existing state** - Keep chat state in your existing state management solution
* **Custom message formats** - Use your backend's message structure with automatic conversion
* **Complex synchronization** - Sync messages with external data sources, databases, or multiple clients
* **Custom persistence logic** - Implement your own storage patterns and caching strategies

Key Features \[#key-features]

<Cards>
  <Card title="State Management Integration" description="Works seamlessly with Redux, Zustand, TanStack Query, and more" />

  <Card title="Message Conversion" description="Automatic conversion between your message format and assistant-ui's format" />

  <Card title="Real-time Streaming" description="Built-in support for streaming responses and progressive updates" />

  <Card title="Thread Management" description="Multi-conversation support with archiving and thread switching" />
</Cards>

Architecture \[#architecture]

How It Works \[#how-it-works]

`ExternalStoreRuntime` acts as a bridge between your state management and assistant-ui:

<Mermaid chart="graph TD\n    A[Your State Management] -->|messages| B[ExternalStoreAdapter]\n    B --> C[ExternalStoreRuntime]\n    C --> D[assistant-ui Components]\n    D -->|user actions| B\n    B -->|state updates| A" />

Key Concepts \[#key-concepts]

1. **State Ownership** - You own and control all message state
2. **Adapter Pattern** - The adapter translates between your state and assistant-ui
3. **Capability-Based Features** - UI features are enabled based on which handlers you provide
4. **Message Conversion** - Automatic conversion between your message format and assistant-ui's format
5. **Optimistic Updates** - Built-in handling for streaming and loading states

Getting Started \[#getting-started]

<Steps>
  <Step>
    Install Dependencies \[#install-dependencies]

    <InstallCommand npm={["@assistant-ui/react"]} />
  </Step>

  <Step>
    Create Runtime Provider \[#create-runtime-provider]

    ```tsx title="app/MyRuntimeProvider.tsx"
    "use client";

    import { ThreadMessageLike } from "@assistant-ui/react";
    import { AppendMessage } from "@assistant-ui/react";
    import {
      AssistantRuntimeProvider,
      useExternalStoreRuntime,
    } from "@assistant-ui/react";
    import { useState } from "react";

    const convertMessage = (message: ThreadMessageLike) => {
      return message;
    };

    export function MyRuntimeProvider({
      children,
    }: Readonly<{
      children: React.ReactNode;
    }>) {
      const [messages, setMessages] = useState<readonly ThreadMessageLike[]>([]);

      const onNew = async (message: AppendMessage) => {
        if (message.content.length !== 1 || message.content[0]?.type !== "text")
          throw new Error("Only text content is supported");

        const userMessage: ThreadMessageLike = {
          role: "user",
          content: [{ type: "text", text: message.content[0].text }],
        };
        setMessages((currentMessages) => [...currentMessages, userMessage]);

        // normally you would perform an API call here to get the assistant response
        await new Promise((resolve) => setTimeout(resolve, 1000));

        const assistantMessage: ThreadMessageLike = {
          role: "assistant",
          content: [{ type: "text", text: "Hello, world!" }],
        };
        setMessages((currentMessages) => [...currentMessages, assistantMessage]);
      };

      const runtime = useExternalStoreRuntime<ThreadMessageLike>({
        messages,
        setMessages,
        onNew,
        convertMessage,
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Use in Your App \[#use-in-your-app]

    ```tsx title="app/page.tsx"
    import { Thread } from "@assistant-ui/react";
    import { MyRuntimeProvider } from "./MyRuntimeProvider";

    export default function Page() {
      return (
        <MyRuntimeProvider>
          <Thread />
        </MyRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

Implementation Patterns \[#implementation-patterns]

Message Conversion \[#message-conversion]

Two approaches for converting your message format:

1. Simple Conversion (Recommended) \[#1-simple-conversion-recommended]

```tsx
const convertMessage = (message: MyMessage): ThreadMessageLike => ({
  role: message.role,
  content: [{ type: "text", text: message.text }],
  id: message.id,
  createdAt: new Date(message.timestamp),
});

const runtime = useExternalStoreRuntime({
  messages: myMessages,
  convertMessage,
  onNew,
});
```

2. Advanced Conversion with useExternalMessageConverter \[#2-advanced-conversion-with-useexternalmessageconverter]

For complex scenarios with performance optimization:

```tsx
import { useExternalMessageConverter } from "@assistant-ui/react";

const convertedMessages = useExternalMessageConverter({
  messages,
  convertMessage: (message: MyMessage): ThreadMessageLike => ({
    role: message.role,
    content: [{ type: "text", text: message.text }],
    id: message.id,
    createdAt: new Date(message.timestamp),
  }),
  joinStrategy: "concat-content", // Merge adjacent assistant messages
});

const runtime = useExternalStoreRuntime({
  messages: convertedMessages,
  onNew,
  // No convertMessage needed - already converted
});
```

Join Strategy \[#join-strategy]

Controls how adjacent assistant messages are combined:

* **`concat-content`** (default): Merges adjacent assistant messages into one
* **`none`**: Keeps all messages separate

This is useful when your backend sends multiple message chunks that should appear as a single message in the UI.

<Callout type="info">
  `useExternalMessageConverter` provides performance optimization for complex
  message conversion scenarios. For simpler cases, consider using the basic
  `convertMessage` approach shown above.
</Callout>

Essential Handlers \[#essential-handlers]

Basic Chat (onNew only) \[#basic-chat-onnew-only]

```tsx
const runtime = useExternalStoreRuntime({
  messages,
  onNew: async (message) => {
    // Add user message to state
    const userMsg = { role: "user", content: message.content };
    setMessages([...messages, userMsg]);

    // Get AI response
    const response = await callAI(message);
    setMessages([...messages, userMsg, response]);
  },
});
```

Full-Featured Chat \[#full-featured-chat]

```tsx
const runtime = useExternalStoreRuntime({
  messages,
  setMessages, // Enables branch switching
  onNew, // Required
  onEdit, // Enables message editing
  onReload, // Enables regeneration
  onCancel, // Enables cancellation
});
```

<Callout type="info">
  Each handler you provide enables specific UI features: - `setMessages` →
  Branch switching - `onEdit` → Message editing - `onReload` → Regenerate button

  * `onCancel` → Cancel button during generation
</Callout>

Streaming Responses \[#streaming-responses]

Implement real-time streaming with progressive updates:

```tsx
const onNew = async (message: AppendMessage) => {
  // Add user message
  const userMessage: ThreadMessageLike = {
    role: "user",
    content: message.content,
    id: generateId(),
  };
  setMessages((prev) => [...prev, userMessage]);

  // Create placeholder for assistant message
  setIsRunning(true);
  const assistantId = generateId();
  const assistantMessage: ThreadMessageLike = {
    role: "assistant",
    content: [{ type: "text", text: "" }],
    id: assistantId,
  };
  setMessages((prev) => [...prev, assistantMessage]);

  // Stream response
  const stream = await api.streamChat(message);
  for await (const chunk of stream) {
    setMessages((prev) =>
      prev.map((m) =>
        m.id === assistantId
          ? {
              ...m,
              content: [
                {
                  type: "text",
                  text: (m.content[0] as any).text + chunk,
                },
              ],
            }
          : m,
      ),
    );
  }
  setIsRunning(false);
};
```

Message Editing \[#message-editing]

Enable message editing by implementing the `onEdit` handler:

<Callout type="info">
  You can also implement `onEdit(editedMessage)` and `onRemove(messageId)`
  callbacks to handle user-initiated edits or deletions in your external store.
  This enables features like "edit and re-run" on your backend.
</Callout>

```tsx
const onEdit = async (message: AppendMessage) => {
  // Find the index where to insert the edited message
  const index = messages.findIndex((m) => m.id === message.parentId) + 1;

  // Keep messages up to the parent
  const newMessages = [...messages.slice(0, index)];

  // Add the edited message
  const editedMessage: ThreadMessageLike = {
    role: "user",
    content: message.content,
    id: message.id || generateId(),
  };
  newMessages.push(editedMessage);

  setMessages(newMessages);

  // Generate new response
  setIsRunning(true);
  const response = await api.chat(message);
  newMessages.push({
    role: "assistant",
    content: response.content,
    id: generateId(),
  });
  setMessages(newMessages);
  setIsRunning(false);
};
```

Tool Calling \[#tool-calling]

Support tool calls with proper result handling:

```tsx
const onAddToolResult = (options: AddToolResultOptions) => {
  setMessages((prev) =>
    prev.map((message) => {
      if (message.id === options.messageId) {
        // Update the specific tool call with its result
        return {
          ...message,
          content: message.content.map((part) => {
            if (
              part.type === "tool-call" &&
              part.toolCallId === options.toolCallId
            ) {
              return {
                ...part,
                result: options.result,
              };
            }
            return part;
          }),
        };
      }
      return message;
    }),
  );
};

const runtime = useExternalStoreRuntime({
  messages,
  onNew,
  onAddToolResult,
  // ... other props
});
```

Automatic Tool Result Matching \[#automatic-tool-result-matching]

The runtime automatically matches tool results with their corresponding tool calls. When messages are converted and joined:

1. **Tool Call Tracking** - The runtime tracks tool calls by their `toolCallId`
2. **Result Association** - Tool results are automatically associated with their corresponding calls
3. **Message Grouping** - Related tool messages are intelligently grouped together

```tsx
// Example: Tool call and result in separate messages
const messages = [
  {
    role: "assistant",
    content: [
      {
        type: "tool-call",
        toolCallId: "call_123",
        toolName: "get_weather",
        args: { location: "San Francisco" },
      },
    ],
  },
  {
    role: "tool",
    content: [
      {
        type: "tool-result",
        toolCallId: "call_123",
        result: { temperature: 72, condition: "sunny" },
      },
    ],
  },
];

// These are automatically matched and grouped by the runtime
```

File Attachments \[#file-attachments]

Enable file uploads with the attachment adapter:

```tsx
const attachmentAdapter: AttachmentAdapter = {
  accept: "image/*,application/pdf,.txt,.md",
  async add(file) {
    // Upload file to your server
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch("/api/upload", {
      method: "POST",
      body: formData,
    });

    const { id, url } = await response.json();
    return {
      id,
      type: "document",
      name: file.name,
      file,
      url,
    };
  },
  async remove(attachment) {
    // Remove file from server
    await fetch(`/api/upload/${attachment.id}`, {
      method: "DELETE",
    });
  },
};

const runtime = useExternalStoreRuntime({
  messages,
  onNew,
  adapters: {
    attachments: attachmentAdapter,
  },
});
```

Thread Management \[#thread-management]

Managing Thread Context \[#managing-thread-context]

When implementing multi-thread support with `ExternalStoreRuntime`, you need to carefully manage thread context across your application. Here's a comprehensive approach:

```tsx
// Create a context for thread management
const ThreadContext = createContext<{
  currentThreadId: string;
  setCurrentThreadId: (id: string) => void;
  threads: Map<string, ThreadMessageLike[]>;
  setThreads: React.Dispatch<
    React.SetStateAction<Map<string, ThreadMessageLike[]>>
  >;
}>({
  currentThreadId: "default",
  setCurrentThreadId: () => {},
  threads: new Map(),
  setThreads: () => {},
});

// Thread provider component
export function ThreadProvider({ children }: { children: ReactNode }) {
  const [threads, setThreads] = useState<Map<string, ThreadMessageLike[]>>(
    new Map([["default", []]]),
  );
  const [currentThreadId, setCurrentThreadId] = useState("default");

  return (
    <ThreadContext.Provider
      value={{ currentThreadId, setCurrentThreadId, threads, setThreads }}
    >
      {children}
    </ThreadContext.Provider>
  );
}

// Hook for accessing thread context
export function useThreadContext() {
  const context = useContext(ThreadContext);
  if (!context) {
    throw new Error("useThreadContext must be used within ThreadProvider");
  }
  return context;
}
```

Complete Thread Implementation \[#complete-thread-implementation]

Here's a full implementation with proper context management:

```tsx
function ChatWithThreads() {
  const { currentThreadId, setCurrentThreadId, threads, setThreads } =
    useThreadContext();
  const [threadList, setThreadList] = useState<ExternalStoreThreadData[]>([
    { threadId: "default", status: "regular", title: "New Chat" },
  ]);

  // Get messages for current thread
  const currentMessages = threads.get(currentThreadId) || [];

  const threadListAdapter: ExternalStoreThreadListAdapter = {
    threadId: currentThreadId,
    threads: threadList.filter((t) => t.status === "regular"),
    archivedThreads: threadList.filter((t) => t.status === "archived"),

    onSwitchToNewThread: () => {
      const newId = `thread-${Date.now()}`;
      setThreadList((prev) => [
        ...prev,
        {
          threadId: newId,
          status: "regular",
          title: "New Chat",
        },
      ]);
      setThreads((prev) => new Map(prev).set(newId, []));
      setCurrentThreadId(newId);
    },

    onSwitchToThread: (threadId) => {
      setCurrentThreadId(threadId);
    },

    onRename: (threadId, newTitle) => {
      setThreadList((prev) =>
        prev.map((t) =>
          t.threadId === threadId ? { ...t, title: newTitle } : t,
        ),
      );
    },

    onArchive: (threadId) => {
      setThreadList((prev) =>
        prev.map((t) =>
          t.threadId === threadId ? { ...t, status: "archived" } : t,
        ),
      );
    },

    onDelete: (threadId) => {
      setThreadList((prev) => prev.filter((t) => t.threadId !== threadId));
      setThreads((prev) => {
        const next = new Map(prev);
        next.delete(threadId);
        return next;
      });
      if (currentThreadId === threadId) {
        setCurrentThreadId("default");
      }
    },
  };

  const runtime = useExternalStoreRuntime({
    messages: currentMessages,
    setMessages: (messages) => {
      setThreads((prev) => new Map(prev).set(currentThreadId, messages));
    },
    onNew: async (message) => {
      // Handle new message for current thread
      // Your implementation here
    },
    adapters: {
      threadList: threadListAdapter,
    },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <ThreadList />
      <Thread />
    </AssistantRuntimeProvider>
  );
}

// App component with proper context wrapping
export function App() {
  return (
    <ThreadProvider>
      <ChatWithThreads />
    </ThreadProvider>
  );
}
```

Thread Context Best Practices \[#thread-context-best-practices]

<Callout type="info">
  **Critical**: When using `ExternalStoreRuntime` with threads, the
  `currentThreadId` must be consistent across all components and handlers.
  Mismatched thread IDs will cause messages to appear in wrong threads or
  disappear entirely.
</Callout>

1. **Centralize Thread State**: Always use a context or global state management solution to ensure thread ID consistency:

```tsx
// ❌ Bad: Local state in multiple components
function ThreadList() {
  const [currentThreadId, setCurrentThreadId] = useState("default");
  // This won't sync with the runtime!
}

// ✅ Good: Shared context
function ThreadList() {
  const { currentThreadId, setCurrentThreadId } = useThreadContext();
  // Thread ID is synchronized everywhere
}
```

2. **Sync Thread Changes**: Ensure all thread-related operations update both the thread ID and messages:

```tsx
// ❌ Bad: Only updating thread ID
onSwitchToThread: (threadId) => {
  setCurrentThreadId(threadId);
  // Messages won't update!
};

// ✅ Good: Complete state update
onSwitchToThread: (threadId) => {
  setCurrentThreadId(threadId);
  // Messages automatically update via currentMessages = threads.get(currentThreadId)
};
```

3. **Handle Edge Cases**: Always provide fallbacks for missing threads:

```tsx
// Ensure thread always exists
const currentMessages = threads.get(currentThreadId) || [];

// Initialize new threads properly
const initializeThread = (threadId: string) => {
  if (!threads.has(threadId)) {
    setThreads((prev) => new Map(prev).set(threadId, []));
  }
};
```

4. **Persist Thread State**: For production apps, sync thread state with your backend:

```tsx
// Save thread state to backend
useEffect(() => {
  const saveThread = async () => {
    await api.saveThread(currentThreadId, threads.get(currentThreadId) || []);
  };

  const debounced = debounce(saveThread, 1000);
  debounced();

  return () => debounced.cancel();
}, [currentThreadId, threads]);
```

Integration Examples \[#integration-examples]

Redux Integration \[#redux-integration]

```tsx title="app/chatSlice.ts"
// Using Redux Toolkit (recommended)
import { createSlice, PayloadAction } from "@reduxjs/toolkit";
import { ThreadMessageLike } from "@assistant-ui/react";

interface ChatState {
  messages: ThreadMessageLike[];
  isRunning: boolean;
}

const chatSlice = createSlice({
  name: "chat",
  initialState: {
    messages: [] as ThreadMessageLike[],
    isRunning: false,
  },
  reducers: {
    setMessages: (state, action: PayloadAction<ThreadMessageLike[]>) => {
      state.messages = action.payload;
    },
    addMessage: (state, action: PayloadAction<ThreadMessageLike>) => {
      state.messages.push(action.payload);
    },
    setIsRunning: (state, action: PayloadAction<boolean>) => {
      state.isRunning = action.payload;
    },
  },
});

export const { setMessages, addMessage, setIsRunning } = chatSlice.actions;
export const selectMessages = (state: RootState) => state.chat.messages;
export const selectIsRunning = (state: RootState) => state.chat.isRunning;
export default chatSlice.reducer;

// ReduxRuntimeProvider.tsx
import { useSelector, useDispatch } from "react-redux";
import {
  selectMessages,
  selectIsRunning,
  addMessage,
  setMessages,
  setIsRunning,
} from "./chatSlice";

export function ReduxRuntimeProvider({ children }) {
  const messages = useSelector(selectMessages);
  const isRunning = useSelector(selectIsRunning);
  const dispatch = useDispatch();

  const runtime = useExternalStoreRuntime({
    messages,
    isRunning,
    setMessages: (messages) => dispatch(setMessages(messages)),
    onNew: async (message) => {
      // Add user message
      dispatch(
        addMessage({
          role: "user",
          content: message.content,
          id: `msg-${Date.now()}`,
          createdAt: new Date(),
        }),
      );

      // Generate response
      dispatch(setIsRunning(true));
      const response = await api.chat(message);
      dispatch(
        addMessage({
          role: "assistant",
          content: response.content,
          id: `msg-${Date.now()}`,
          createdAt: new Date(),
        }),
      );
      dispatch(setIsRunning(false));
    },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

Zustand Integration (v5) \[#zustand-integration-v5]

```tsx title="app/chatStore.ts"
// Using Zustand v5 with TypeScript
import { create } from "zustand";
import { immer } from "zustand/middleware/immer";
import { ThreadMessageLike } from "@assistant-ui/react";

interface ChatState {
  messages: ThreadMessageLike[];
  isRunning: boolean;
  addMessage: (message: ThreadMessageLike) => void;
  setMessages: (messages: ThreadMessageLike[]) => void;
  setIsRunning: (isRunning: boolean) => void;
  updateMessage: (id: string, updates: Partial<ThreadMessageLike>) => void;
}

// Zustand v5 requires the extra parentheses for TypeScript
const useChatStore = create<ChatState>()(
  immer((set) => ({
    messages: [],
    isRunning: false,

    addMessage: (message) =>
      set((state) => {
        state.messages.push(message);
      }),

    setMessages: (messages) =>
      set((state) => {
        state.messages = messages;
      }),

    setIsRunning: (isRunning) =>
      set((state) => {
        state.isRunning = isRunning;
      }),

    updateMessage: (id, updates) =>
      set((state) => {
        const index = state.messages.findIndex((m) => m.id === id);
        if (index !== -1) {
          Object.assign(state.messages[index], updates);
        }
      }),
  })),
);

// ZustandRuntimeProvider.tsx
import { useShallow } from "zustand/shallow";

export function ZustandRuntimeProvider({ children }) {
  // Use useShallow to prevent unnecessary re-renders
  const { messages, isRunning, addMessage, setMessages, setIsRunning } =
    useChatStore(
      useShallow((state) => ({
        messages: state.messages,
        isRunning: state.isRunning,
        addMessage: state.addMessage,
        setMessages: state.setMessages,
        setIsRunning: state.setIsRunning,
      })),
    );

  const runtime = useExternalStoreRuntime({
    messages,
    isRunning,
    setMessages,
    onNew: async (message) => {
      // Add user message
      addMessage({
        role: "user",
        content: message.content,
        id: `msg-${Date.now()}`,
        createdAt: new Date(),
      });

      // Generate response
      setIsRunning(true);
      const response = await api.chat(message);
      addMessage({
        role: "assistant",
        content: response.content,
        id: `msg-${Date.now()}-assistant`,
        createdAt: new Date(),
      });
      setIsRunning(false);
    },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

TanStack Query Integration \[#tanstack-query-integration]

```tsx title="app/chatQueries.ts"
// Using TanStack Query v5 with TypeScript
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { ThreadMessageLike, AppendMessage } from "@assistant-ui/react";

// Query key factory pattern
export const messageKeys = {
  all: ["messages"] as const,
  thread: (threadId: string) => [...messageKeys.all, threadId] as const,
};

// TanStackQueryRuntimeProvider.tsx
export function TanStackQueryRuntimeProvider({ children }) {
  const queryClient = useQueryClient();
  const threadId = "main"; // Or from context/props

  const { data: messages = [] } = useQuery({
    queryKey: messageKeys.thread(threadId),
    queryFn: () => fetchMessages(threadId),
    staleTime: 1000 * 60 * 5, // Consider data fresh for 5 minutes
  });

  const sendMessage = useMutation({
    mutationFn: api.chat,

    // Optimistic updates with proper TypeScript types
    onMutate: async (message: AppendMessage) => {
      // Cancel any outgoing refetches
      await queryClient.cancelQueries({
        queryKey: messageKeys.thread(threadId),
      });

      // Snapshot the previous value
      const previousMessages = queryClient.getQueryData<ThreadMessageLike[]>(
        messageKeys.thread(threadId),
      );

      // Optimistically update with typed data
      const optimisticMessage: ThreadMessageLike = {
        role: "user",
        content: message.content,
        id: `temp-${Date.now()}`,
        createdAt: new Date(),
      };

      queryClient.setQueryData<ThreadMessageLike[]>(
        messageKeys.thread(threadId),
        (old = []) => [...old, optimisticMessage],
      );

      return { previousMessages, tempId: optimisticMessage.id };
    },

    onSuccess: (response, variables, context) => {
      // Replace optimistic message with real data
      queryClient.setQueryData<ThreadMessageLike[]>(
        messageKeys.thread(threadId),
        (old = []) => {
          // Remove temp message and add real ones
          return old
            .filter((m) => m.id !== context?.tempId)
            .concat([
              {
                role: "user",
                content: variables.content,
                id: `user-${Date.now()}`,
                createdAt: new Date(),
              },
              response,
            ]);
        },
      );
    },

    onError: (error, variables, context) => {
      // Rollback to previous messages on error
      if (context?.previousMessages) {
        queryClient.setQueryData(
          messageKeys.thread(threadId),
          context.previousMessages,
        );
      }
    },

    onSettled: () => {
      // Always refetch after error or success
      queryClient.invalidateQueries({
        queryKey: messageKeys.thread(threadId),
      });
    },
  });

  const runtime = useExternalStoreRuntime({
    messages,
    isRunning: sendMessage.isPending,
    onNew: async (message) => {
      await sendMessage.mutateAsync(message);
    },
    // Enable message editing
    setMessages: (newMessages) => {
      queryClient.setQueryData(messageKeys.thread(threadId), newMessages);
    },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

Key Features \[#key-features-1]

Automatic Optimistic Updates \[#automatic-optimistic-updates]

When `isRunning` becomes true, the runtime automatically shows an optimistic assistant message:

```tsx
// Your code
setIsRunning(true);

// Runtime automatically:
// 1. Shows empty assistant message with "in_progress" status
// 2. Displays typing indicator
// 3. Updates status to "complete" when isRunning becomes false
```

Message Status Management \[#message-status-management]

Assistant messages get automatic status updates:

* `"in_progress"` - When `isRunning` is true
* `"complete"` - When `isRunning` becomes false
* `"cancelled"` - When cancelled via `onCancel`

Tool Result Matching \[#tool-result-matching]

The runtime automatically matches tool results with their calls:

```tsx
// Tool call and result can be in separate messages
const messages = [
  {
    role: "assistant",
    content: [
      {
        type: "tool-call",
        toolCallId: "call_123",
        toolName: "get_weather",
        args: { location: "SF" },
      },
    ],
  },
  {
    role: "tool",
    content: [
      {
        type: "tool-result",
        toolCallId: "call_123",
        result: { temp: 72 },
      },
    ],
  },
];
// Runtime automatically associates these
```

Working with External Messages \[#working-with-external-messages]

Converting Back to Your Format \[#converting-back-to-your-format]

Use `getExternalStoreMessages` to access your original messages:

```tsx
import { getExternalStoreMessages } from "@assistant-ui/react";

const MyComponent = () => {
  const originalMessages = useMessage((m) => getExternalStoreMessages(m));
  // originalMessages is MyMessage[] (your original type)
};
```

<Callout type="info">
  After the chat finishes, use `getExternalStoreMessages(runtime)` to convert
  back to your domain model. Refer to the API reference for return structures
  and edge-case behaviors.
</Callout>

<Callout type="warning">
  `getExternalStoreMessages` may return multiple messages for a single UI
  message. This happens because assistant-ui merges adjacent assistant and tool
  messages for display.
</Callout>

Message part Access \[#message-part-access]

```tsx
const ToolUI = makeAssistantToolUI({
  render: () => {
    const originalMessages = useMessagePart((p) => getExternalStoreMessages(p));
    // Access original message data for this message part
  },
});
```

Binding External Messages Manually \[#binding-external-messages-manually]

Use `bindExternalStoreMessage` to attach your original message to a `ThreadMessage` or message part object. This is useful when you construct `ThreadMessage` objects yourself (outside of the built-in message converter) and want `getExternalStoreMessages` to work with them.

```tsx
import {
  bindExternalStoreMessage,
  getExternalStoreMessages,
} from "@assistant-ui/react";

// Attach your original message to a ThreadMessage
bindExternalStoreMessage(threadMessage, originalMessage);

// Later, retrieve it
const original = getExternalStoreMessages(threadMessage);
```

<Callout type="warn">
  This API is experimental and may change without notice.
</Callout>

`bindExternalStoreMessage` is a no-op if the target already has a bound message. It mutates the target object in place.

Debugging \[#debugging]

Common Debugging Scenarios \[#common-debugging-scenarios]

```tsx
// Debug message conversion
const convertMessage = (message: MyMessage): ThreadMessageLike => {
  console.log("Converting message:", message);
  const converted = {
    role: message.role,
    content: [{ type: "text", text: message.content }],
  };
  console.log("Converted to:", converted);
  return converted;
};

// Debug adapter calls
const onNew = async (message: AppendMessage) => {
  console.log("onNew called with:", message);
  // ... implementation
};

// Enable verbose logging
const runtime = useExternalStoreRuntime({
  messages,
  onNew: (...args) => {
    console.log("Runtime onNew:", args);
    return onNew(...args);
  },
  // ... other props
});
```

Best Practices \[#best-practices]

1. Immutable Updates \[#1-immutable-updates]

Always create new arrays when updating messages:

```tsx
// ❌ Wrong - mutating array
messages.push(newMessage);
setMessages(messages);

// ✅ Correct - new array
setMessages([...messages, newMessage]);
```

2. Stable Handler References \[#2-stable-handler-references]

Memoize handlers to prevent runtime recreation:

```tsx
const onNew = useCallback(
  async (message: AppendMessage) => {
    // Handle new message
  },
  [
    /* dependencies */
  ],
);

const runtime = useExternalStoreRuntime({
  messages,
  onNew, // Stable reference
});
```

3. Performance Optimization \[#3-performance-optimization]

```tsx
// For large message lists
const recentMessages = useMemo(
  () => messages.slice(-50), // Show last 50 messages
  [messages],
);

// For expensive conversions
const convertMessage = useCallback((msg) => {
  // Conversion logic
}, []);
```

LocalRuntime vs ExternalStoreRuntime \[#localruntime-vs-externalstoreruntime]

When to Choose Which \[#when-to-choose-which]

| Scenario                         | Recommendation                                               |
| -------------------------------- | ------------------------------------------------------------ |
| Quick prototype                  | `LocalRuntime`                                               |
| Using Redux/Zustand              | `ExternalStoreRuntime`                                       |
| Need Assistant Cloud integration | `LocalRuntime`                                               |
| Custom thread storage            | Both (`LocalRuntime` with adapter or `ExternalStoreRuntime`) |
| Simple single thread             | `LocalRuntime`                                               |
| Complex state logic              | `ExternalStoreRuntime`                                       |

Feature Comparison \[#feature-comparison]

| Feature          | `LocalRuntime`              | `ExternalStoreRuntime` |
| ---------------- | --------------------------- | ---------------------- |
| State Management | Built-in                    | You provide            |
| Multi-thread     | Via Cloud or custom adapter | Via adapter            |
| Message Format   | ThreadMessage               | Any (with conversion)  |
| Setup Complexity | Low                         | Medium                 |
| Flexibility      | Medium                      | High                   |

Common Pitfalls \[#common-pitfalls]

<Callout type="error">
  **Features not appearing**: Each UI feature requires its corresponding handler:

  ```tsx
  // ❌ No edit button
  const runtime = useExternalStoreRuntime({ messages, onNew });

  // ✅ Edit button appears
  const runtime = useExternalStoreRuntime({ messages, onNew, onEdit });
  ```
</Callout>

<Callout type="warning">
  **State not updating**: Common causes:

  1. Mutating arrays instead of creating new ones
  2. Missing `setMessages` for branch switching
  3. Not handling async operations properly
  4. Incorrect message format conversion
</Callout>

Debugging Checklist \[#debugging-checklist]

* Are you creating new arrays when updating messages?
* Did you provide all required handlers for desired features?
* Is your `convertMessage` returning valid `ThreadMessageLike`?
* Are you properly handling `isRunning` state?
* For threads: Is your thread list adapter complete?

Thread-Specific Debugging \[#thread-specific-debugging]

Common thread context issues and solutions:

**Messages disappearing when switching threads:**

```tsx
// Check 1: Ensure currentThreadId is consistent
console.log("Runtime threadId:", threadListAdapter.threadId);
console.log("Current threadId:", currentThreadId);
console.log("Messages for thread:", threads.get(currentThreadId));

// Check 2: Verify setMessages uses correct thread
setMessages: (messages) => {
  console.log("Setting messages for thread:", currentThreadId);
  setThreads((prev) => new Map(prev).set(currentThreadId, messages));
};
```

**Thread list not updating:**

```tsx
// Ensure threadList state is properly managed
onSwitchToNewThread: () => {
  const newId = `thread-${Date.now()}`;
  console.log("Creating new thread:", newId);

  // All three updates must happen together
  setThreadList((prev) => [...prev, newThreadData]);
  setThreads((prev) => new Map(prev).set(newId, []));
  setCurrentThreadId(newId);
};
```

**Messages going to wrong thread:**

```tsx
// Add validation to prevent race conditions
const validateThreadContext = () => {
  const runtimeThread = threadListAdapter.threadId;
  const contextThread = currentThreadId;

  if (runtimeThread !== contextThread) {
    console.error("Thread mismatch!", { runtimeThread, contextThread });
    throw new Error("Thread context mismatch");
  }
};

// Call before any message operation
onNew: async (message) => {
  validateThreadContext();
  // ... handle message
};
```

API Reference \[#api-reference]

ExternalStoreAdapter \[#externalstoreadapter]

The main interface for connecting your state to assistant-ui.

<ParametersTable
  type="ExternalStoreAdapter<T>"
  parameters={[
{
  name: "messages",
  type: "readonly T[]",
  description: "Array of messages from your state",
  required: true,
},
{
  name: "onNew",
  type: "(message: AppendMessage) => Promise<void>",
  description: "Handler for new messages from the user",
  required: true,
},
{
  name: "isRunning",
  type: "boolean",
  description:
    "Whether the assistant is currently generating a response. When true, shows optimistic assistant message",
  default: "false",
},
{
  name: "isDisabled",
  type: "boolean",
  description: "Whether the chat input should be disabled",
  default: "false",
},
{
  name: "suggestions",
  type: "readonly ThreadSuggestion[]",
  description: "Suggested prompts to display",
},
{
  name: "extras",
  type: "unknown",
  description: "Additional data accessible via runtime.extras",
},
{
  name: "setMessages",
  type: "(messages: T[]) => void",
  description: "Update messages (required for branch switching)",
},
{
  name: "onEdit",
  type: "(message: AppendMessage) => Promise<void>",
  description: "Handler for message edits (required for edit feature)",
},
{
  name: "onReload",
  type: "(parentId: string | null, config: StartRunConfig) => Promise<void>",
  description:
    "Handler for regenerating messages (required for reload feature)",
},
{
  name: "onCancel",
  type: "() => Promise<void>",
  description: "Handler for cancelling the current generation",
},
{
  name: "onAddToolResult",
  type: "(options: AddToolResultOptions) => Promise<void> | void",
  description: "Handler for adding tool call results",
},
{
  name: "convertMessage",
  type: "(message: T, index: number) => ThreadMessageLike",
  description:
    "Convert your message format to assistant-ui format. Not needed if using ThreadMessage type",
},
{
  name: "joinStrategy",
  type: '"concat-content" | "none"',
  description: "How to join adjacent assistant messages when converting",
  default: '"concat-content"',
},
{
  name: "adapters",
  type: "object",
  description: "Feature adapters (same as LocalRuntime)",
  children: [
    {
      type: "adapters",
      parameters: [
        {
          name: "attachments",
          type: "AttachmentAdapter",
          description: "Enable file attachments",
        },
        {
          name: "speech",
          type: "SpeechSynthesisAdapter",
          description: "Enable text-to-speech",
        },
        {
          name: "feedback",
          type: "FeedbackAdapter",
          description: "Enable message feedback",
        },
        {
          name: "threadList",
          type: "ExternalStoreThreadListAdapter",
          description: "Enable multi-thread management",
        },
      ],
    },
  ],
},
{
  name: "unstable_capabilities",
  type: "object",
  description: "Configure runtime capabilities",
  children: [
    {
      type: "unstable_capabilities",
      parameters: [
        {
          name: "copy",
          type: "boolean",
          description: "Enable message copy feature",
          default: "true",
        },
      ],
    },
  ],
},
]}
/>

ThreadMessageLike \[#threadmessagelike]

A flexible message format that can be converted to assistant-ui's internal format.

<ParametersTable
  type="ThreadMessageLike"
  parameters={[
{
  name: "role",
  type: '"assistant" | "user" | "system"',
  description: "The role of the message sender",
  required: true,
},
{
  name: "content",
  type: "string | readonly MessagePart[]",
  description: "Message content as string or structured message parts. Supports `data-*` prefixed types (e.g. `{ type: \"data-workflow\", data: {...} }`) which are automatically converted to DataMessagePart.",
  required: true,
},
{
  name: "id",
  type: "string",
  description: "Unique identifier for the message",
},
{
  name: "createdAt",
  type: "Date",
  description: "Timestamp when the message was created",
},
{
  name: "status",
  type: "MessageStatus",
  description:
    "Status of assistant messages (in_progress, complete, cancelled)",
},
{
  name: "attachments",
  type: "readonly CompleteAttachment[]",
  description: "File attachments (user messages only). Attachment `type` accepts custom strings beyond \"image\" | \"document\" | \"file\", and `contentType` is optional.",
},
{
  name: "metadata",
  type: "object",
  description: "Additional message metadata",
  children: [
    {
      type: "metadata",
      parameters: [
        {
          name: "steps",
          type: "readonly ThreadStep[]",
          description: "Tool call steps for assistant messages",
        },
        {
          name: "custom",
          type: "Record<string, unknown>",
          description: "Custom metadata for your application",
        },
      ],
    },
  ],
},
]}
/>

ExternalStoreThreadListAdapter \[#externalstorethreadlistadapter]

Enable multi-thread support with custom thread management.

<ParametersTable
  type="ExternalStoreThreadListAdapter"
  parameters={[
{
  name: "threadId",
  type: "string",
  description: "ID of the current active thread",
},
{
  name: "threads",
  type: "readonly ExternalStoreThreadData[]",
  description: "Array of regular threads with { threadId, title }",
},
{
  name: "archivedThreads",
  type: "readonly ExternalStoreThreadData[]",
  description: "Array of archived threads",
},
{
  name: "onSwitchToNewThread",
  type: "() => Promise<void> | void",
  description: "Handler for creating a new thread",
},
{
  name: "onSwitchToThread",
  type: "(threadId: string) => Promise<void> | void",
  description: "Handler for switching to an existing thread",
},
{
  name: "onRename",
  type: "(threadId: string, newTitle: string) => Promise<void> | void",
  description: "Handler for renaming a thread",
},
{
  name: "onArchive",
  type: "(threadId: string) => Promise<void> | void",
  description: "Handler for archiving a thread",
},
{
  name: "onUnarchive",
  type: "(threadId: string) => Promise<void> | void",
  description: "Handler for unarchiving a thread",
},
{
  name: "onDelete",
  type: "(threadId: string) => Promise<void> | void",
  description: "Handler for deleting a thread",
},
]}
/>

<Callout type="info">
  The thread list adapter enables multi-thread support. Without it, the runtime
  only manages the current conversation.
</Callout>

Related Runtime APIs \[#related-runtime-apis]

* [AssistantRuntime API](/docs/api-reference/runtimes/assistant-runtime) - Core runtime interface and methods
* [ThreadRuntime API](/docs/api-reference/runtimes/thread-runtime) - Thread-specific operations and state management
* [Runtime Providers](/docs/api-reference/context-providers/assistant-runtime-provider) - Context providers for runtime integration

Related Resources \[#related-resources]

* [Runtime Layer Concepts](/docs/concepts/runtime-layer)
* [Pick a Runtime Guide](/docs/runtimes/pick-a-runtime)
* [`LocalRuntime` Documentation](/docs/runtimes/custom/local)
* [Examples Repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-external-store)


# LocalRuntime
URL: /docs/runtimes/custom/local

Quickest path to a working chat. Handles state while you handle the API.

Overview \[#overview]

`LocalRuntime` is the simplest way to connect your own custom backend to assistant-ui. It manages all chat state internally while providing a clean adapter interface to connect with any REST API, OpenAI, or custom language model.

`LocalRuntime` provides:

* **Built-in state management** for messages, threads, and conversation history
* **Automatic features** like message editing, reloading, and branch switching
* **Multi-thread support** through [Assistant Cloud](/docs/cloud/overview) or your own database using `useRemoteThreadListRuntime`
* **Simple adapter pattern** to connect any backend API

While LocalRuntime manages state in-memory by default, it offers multiple persistence options through adapters - use the history adapter for single-thread persistence, Assistant Cloud for managed multi-thread support, or implement your own storage with `useRemoteThreadListRuntime`.

When to Use \[#when-to-use]

Use `LocalRuntime` if you need:

* **Quick setup with minimal configuration** - Get a fully functional chat interface with just a few lines of code
* **Built-in state management** - No need to manage messages, threads, or conversation history yourself
* **Automatic features** - Branch switching, message editing, and regeneration work out of the box
* **API flexibility** - Connect to any REST endpoint, OpenAI, or custom model with a simple adapter
* **Multi-thread support** - Full thread management with Assistant Cloud or custom database
* **Thread persistence** - Via history adapter, Assistant Cloud, or custom thread list adapter

Key Features \[#key-features]

<Cards>
  <Card title="Built-in State Management" description="Automatic handling of messages, threads, and conversation history" />

  <Card title="Multi-Thread Support" description="Full thread management capabilities with Assistant Cloud or custom database adapter" />

  <Card title="Adapter System" description="Extend with attachments, speech, feedback, persistence, and suggestions" />

  <Card title="Tool Calling" description="Support for function calling with human-in-the-loop approval" />
</Cards>

Getting Started \[#getting-started]

<Steps>
  <Step>
    Create a Next.js project \[#create-a-nextjs-project]

    ```sh
    npx create-next-app@latest my-app
    cd my-app
    ```
  </Step>

  <Step>
    Install @assistant-ui/react \[#install-assistant-uireact]

    <InstallCommand npm={["@assistant-ui/react"]} />
  </Step>

  <Step>
    Add assistant-ui Thread component \[#add-assistant-ui-thread-component]

    ```sh npm2yarn
    npx assistant-ui@latest add thread
    ```
  </Step>

  <Step>
    Define a MyRuntimeProvider component \[#define-a-myruntimeprovider-component]

    Update the `MyModelAdapter` below to integrate with your own custom API.
    See `LocalRuntimeOptions` [API Reference](#localruntimeoptions) for available configuration options.

    ```tsx twoslash include MyRuntimeProvider title="app/MyRuntimeProvider.tsx"
    // @filename: /app/MyRuntimeProvider.tsx

    // ---cut---
    "use client";

    import type { ReactNode } from "react";
    import {
      AssistantRuntimeProvider,
      useLocalRuntime,
      type ChatModelAdapter,
    } from "@assistant-ui/react";

    const MyModelAdapter: ChatModelAdapter = {
      async run({ messages, abortSignal }) {
        // TODO replace with your own API
        const result = await fetch("<YOUR_API_ENDPOINT>", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          // forward the messages in the chat to the API
          body: JSON.stringify({
            messages,
          }),
          // if the user hits the "cancel" button or escape keyboard key, cancel the request
          signal: abortSignal,
        });

        const data = await result.json();
        return {
          content: [
            {
              type: "text",
              text: data.text,
            },
          ],
        };
      },
    };

    export function MyRuntimeProvider({
      children,
    }: Readonly<{
      children: ReactNode;
    }>) {
      const runtime = useLocalRuntime(MyModelAdapter);

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          {children}
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Wrap your app in MyRuntimeProvider \[#wrap-your-app-in-myruntimeprovider]

    ```tsx {1,11,17} twoslash title="app/layout.tsx"
    // @include: MyRuntimeProvider
    // @filename: /app/layout.tsx
    // ---cut---
    import type { ReactNode } from "react";
    import { MyRuntimeProvider } from "@/app/MyRuntimeProvider";

    export default function RootLayout({
      children,
    }: Readonly<{
      children: ReactNode;
    }>) {
      return (
        <MyRuntimeProvider>
          <html lang="en">
            <body>{children}</body>
          </html>
        </MyRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Use the Thread component \[#use-the-thread-component]

    ```tsx title="app/page.tsx"
    import { Thread } from 'components/assistant-ui/thread.tsx'

    export default function Page() {
      return <Thread />;
    }
    ```
  </Step>
</Steps>

Streaming Responses \[#streaming-responses]

Implement streaming by declaring the `run` function as an `AsyncGenerator`.

```tsx twoslash {2, 11-13} title="app/MyRuntimeProvider.tsx"
import {
  ChatModelAdapter,
  ThreadMessage,
  type ModelContext,
} from "@assistant-ui/react";
import { OpenAI } from "openai";

const openai = new OpenAI();
const backendApi = async ({
  messages,
  abortSignal,
  context,
}: {
  messages: readonly ThreadMessage[];
  abortSignal: AbortSignal;
  context: ModelContext;
}) => {
  return openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Say this is a test" }],
    stream: true,
  });
};

// ---cut---
const MyModelAdapter: ChatModelAdapter = {
  async *run({ messages, abortSignal, context }) {
    const stream = await backendApi({ messages, abortSignal, context });

    let text = "";
    for await (const part of stream) {
      text += part.choices[0]?.delta?.content || "";

      yield {
        content: [{ type: "text", text }],
      };
    }
  },
};
```

Streaming with Tool Calls \[#streaming-with-tool-calls]

Handle streaming responses that include function calls:

```tsx
const MyModelAdapter: ChatModelAdapter = {
  async *run({ messages, abortSignal, context }) {
    const stream = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: convertToOpenAIMessages(messages),
      tools: context.tools,
      stream: true,
      signal: abortSignal,
    });

    let content = "";
    const toolCalls: any[] = [];

    for await (const chunk of stream) {
      const delta = chunk.choices[0]?.delta;

      // Handle text content
      if (delta?.content) {
        content += delta.content;
      }

      // Handle tool calls
      if (delta?.tool_calls) {
        for (const toolCall of delta.tool_calls) {
          if (!toolCalls[toolCall.index]) {
            toolCalls[toolCall.index] = {
              id: toolCall.id,
              type: "function",
              function: { name: "", arguments: "" },
            };
          }

          if (toolCall.function?.name) {
            toolCalls[toolCall.index].function.name = toolCall.function.name;
          }

          if (toolCall.function?.arguments) {
            toolCalls[toolCall.index].function.arguments +=
              toolCall.function.arguments;
          }
        }
      }

      // Yield current state
      yield {
        content: [
          ...(content ? [{ type: "text" as const, text: content }] : []),
          ...toolCalls.map((tc) => ({
            type: "tool-call" as const,
            toolCallId: tc.id,
            toolName: tc.function.name,
            args: JSON.parse(tc.function.arguments || "{}"),
          })),
        ],
      };
    }
  },
};
```

Tool Calling \[#tool-calling]

`LocalRuntime` supports OpenAI-compatible function calling with automatic or human-in-the-loop execution.

Basic Tool Definition \[#basic-tool-definition]

Tools should be registered using the `Tools()` API with `useAui()`:

```tsx
import { useAui, Tools, type Toolkit } from "@assistant-ui/react";
import { z } from "zod";

// Define your toolkit
const myToolkit: Toolkit = {
  getWeather: {
    description: "Get the current weather in a location",
    parameters: z.object({
      location: z.string().describe("The city and state, e.g. San Francisco, CA"),
      unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
    }),
    execute: async ({ location, unit }) => {
      const weather = await fetchWeatherAPI(location, unit);
      return weather;
    },
  },
};

// Register tools in your runtime provider
function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useLocalRuntime(MyModelAdapter);

  // Register all tools
  const aui = useAui({
    tools: Tools({ toolkit: myToolkit }),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

The tools will be available to your adapter via the `context` parameter in the `run` function. See the [Tools guide](/docs/guides/tools) for more details on tool registration and advanced features.

Human-in-the-Loop Approval \[#human-in-the-loop-approval]

Require user confirmation before executing certain tools:

```tsx
const runtime = useLocalRuntime(MyModelAdapter, {
  unstable_humanToolNames: ["delete_file", "send_email"],
});
```

Tool Execution \[#tool-execution]

Tools are executed automatically by the runtime. The model adapter receives tool results in subsequent messages:

```tsx
// Messages will include tool calls and results:
[
  { role: "user", content: "What's the weather in SF?" },
  {
    role: "assistant",
    content: [
      {
        type: "tool-call",
        toolCallId: "call_123",
        toolName: "get_weather",
        args: { location: "San Francisco, CA" },
      },
    ],
  },
  {
    role: "tool",
    content: [
      {
        type: "tool-result",
        toolCallId: "call_123",
        result: { temperature: 72, condition: "sunny" },
      },
    ],
  },
  {
    role: "assistant",
    content: "The weather in San Francisco is sunny and 72°F.",
  },
];
```

Multi-Thread Support \[#multi-thread-support]

`LocalRuntime` supports multiple conversation threads through two approaches:

1. Assistant Cloud Integration \[#1-assistant-cloud-integration]

```tsx
import { useLocalRuntime } from "@assistant-ui/react";
import { AssistantCloud } from "assistant-cloud";

const cloud = new AssistantCloud({
  apiKey: process.env.ASSISTANT_CLOUD_API_KEY,
});

const runtime = useLocalRuntime(MyModelAdapter, {
  cloud, // Enables multi-thread support
});
```

With Assistant Cloud, you get:

* Multiple conversation threads
* Thread persistence across sessions
* Thread management (create, switch, rename, archive, delete)
* Automatic synchronization across devices
* Built-in user authentication

2. Custom Database with useRemoteThreadListRuntime \[#2-custom-database-with-useremotethreadlistruntime]

For custom thread storage, use `useRemoteThreadListRuntime` with your own adapter:

```tsx
import {
  unstable_useRemoteThreadListRuntime as useRemoteThreadListRuntime,
  useAui,
  RuntimeAdapterProvider,
  AssistantRuntimeProvider,
  type unstable_RemoteThreadListAdapter as RemoteThreadListAdapter,
  type ThreadHistoryAdapter,
} from "@assistant-ui/react";
import { createAssistantStream } from "assistant-stream";
import { useMemo } from "react";

// Implement your custom adapter with proper message persistence
const myDatabaseAdapter: RemoteThreadListAdapter = {
  async list() {
    const threads = await db.threads.findAll();
    return {
      threads: threads.map((t) => ({
        status: t.archived ? "archived" : "regular",
        remoteId: t.id,
        title: t.title,
      })),
    };
  },

  async initialize(threadId) {
    const thread = await db.threads.create({ id: threadId });
    return { remoteId: thread.id };
  },

  async rename(remoteId, newTitle) {
    await db.threads.update(remoteId, { title: newTitle });
  },

  async archive(remoteId) {
    await db.threads.update(remoteId, { archived: true });
  },

  async unarchive(remoteId) {
    await db.threads.update(remoteId, { archived: false });
  },

  async delete(remoteId) {
    // Delete thread and its messages
    await db.messages.deleteByThreadId(remoteId);
    await db.threads.delete(remoteId);
  },

  async generateTitle(remoteId, messages) {
    // Generate title from messages using your AI
    const newTitle = await generateTitle(messages);

    // Persist the title in your DB
    await db.threads.update(remoteId, { title: newTitle });

    // IMPORTANT: Return an AssistantStream so the UI updates
    return createAssistantStream((controller) => {
      controller.appendText(newTitle);
      controller.close();
    });
  },
};

// Complete implementation with message persistence using Provider pattern
export function MyRuntimeProvider({ children }) {
  const runtime = useRemoteThreadListRuntime({
    runtimeHook: () => {
      return useLocalRuntime(MyModelAdapter);
    },
    adapter: {
      ...myDatabaseAdapter,

      // The Provider component adds thread-specific adapters
      unstable_Provider: ({ children }) => {
        // This runs in the context of each thread
        const aui = useAui();

        // Create thread-specific history adapter
        const history = useMemo<ThreadHistoryAdapter>(
          () => ({
            async load() {
              const { remoteId } = aui.threadListItem().getState();
              if (!remoteId) return { messages: [] };

              const messages = await db.messages.findByThreadId(remoteId);
              return {
                messages: messages.map((m) => ({
                  role: m.role,
                  content: m.content,
                  id: m.id,
                  createdAt: new Date(m.createdAt),
                })),
              };
            },

            async append(message) {
              // Wait for initialization to get remoteId (safe to call multiple times)
              const { remoteId } = await aui.threadListItem().initialize();

              await db.messages.create({
                threadId: remoteId,
                role: message.role,
                content: message.content,
                id: message.id,
                createdAt: message.createdAt,
              });
            },
          }),
          [aui],
        );

        const adapters = useMemo(() => ({ history }), [history]);

        return (
          <RuntimeAdapterProvider adapters={adapters}>
            {children}
          </RuntimeAdapterProvider>
        );
      },
    },
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

<Callout type="info" title="Returning a title from generateTitle">
  The `generateTitle` method must return an <code>AssistantStream</code>{" "}
  containing the title text. The easiest, type-safe way is to use{" "}
  <code>createAssistantStream</code> and call{" "}
  <code>controller.appendText(newTitle)</code> followed by{" "}
  <code>controller.close()</code>. Returning a raw <code>ReadableStream</code>{" "}
  won't update the thread list UI.
</Callout>

Understanding the Architecture \[#understanding-the-architecture]

<Callout type="info">
  **Key Insight**: The `unstable_Provider` component in your adapter runs in the
  context of each thread, giving you access to thread-specific information like
  `remoteId`. This is where you add the history adapter for message persistence.
</Callout>

The complete multi-thread implementation requires:

1. **RemoteThreadListAdapter** - Manages thread metadata (list, create, rename, archive, delete)
2. **unstable\_Provider** - Component that provides thread-specific adapters (like history)
3. **ThreadHistoryAdapter** - Persists messages for each thread (load, append)
4. **runtimeHook** - Creates a basic `LocalRuntime` (adapters are added by Provider)

Without the history adapter, threads would have no message persistence, making them effectively useless. The Provider pattern allows you to add thread-specific functionality while keeping the runtime creation simple.

<Callout type="warn" title="Avoiding Race Conditions">
  When implementing a history adapter, `append()` may be called before the thread is fully initialized, causing the first message to be lost. Instead of checking `if (!remoteId)`, await initialization to ensure the `remoteId` is available:

  ```tsx
  import { useAui } from "@assistant-ui/react";

  // Inside your unstable_Provider component
  const aui = useAui();

  const history = useMemo<ThreadHistoryAdapter>(
    () => ({
      async append(message) {
        // Wait for initialization - safe to call multiple times
        const { remoteId } = await aui.threadListItem().initialize();
        await db.messages.create({ threadId: remoteId, ...message });
      },
      // ...
    }),
    [aui],
  );
  ```

  See `AssistantCloudThreadHistoryAdapter` in the source for a production reference.
</Callout>

Database Schema Example \[#database-schema-example]

```typescript
// Example database schema for thread persistence
interface ThreadRecord {
  id: string;
  title: string;
  archived: boolean;
  createdAt: Date;
  updatedAt: Date;
}

interface MessageRecord {
  id: string;
  threadId: string;
  role: "user" | "assistant" | "system";
  content: any; // Store as JSON
  createdAt: Date;
}
```

Both approaches provide full multi-thread support. Choose Assistant Cloud for a managed solution or implement your own adapter for custom storage requirements.

Adapters \[#adapters]

Extend `LocalRuntime` capabilities with adapters. The runtime automatically enables/disables UI features based on which adapters are provided.

Attachment Adapter \[#attachment-adapter]

Enable file and image uploads:

```tsx
const attachmentAdapter: AttachmentAdapter = {
  accept: "image/*,application/pdf",
  async add(file) {
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch("/api/upload", {
      method: "POST",
      body: formData,
    });

    const { id, url } = await response.json();
    return {
      id,
      type: file.type.startsWith("image/") ? "image" : "document",
      name: file.name,
      url,
    };
  },
  async remove(attachment) {
    await fetch(`/api/upload/${attachment.id}`, {
      method: "DELETE",
    });
  },
};

const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: { attachments: attachmentAdapter },
});

// For multiple file types, use CompositeAttachmentAdapter:
const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: {
    attachments: new CompositeAttachmentAdapter([
      new SimpleImageAttachmentAdapter(),
      new SimpleTextAttachmentAdapter(),
      customPDFAdapter,
    ]),
  },
});
```

Thread History Adapter \[#thread-history-adapter]

Persist and resume conversations:

```tsx
const historyAdapter: ThreadHistoryAdapter = {
  async load() {
    // Load messages from your storage
    const response = await fetch(`/api/thread/current`);
    const { messages } = await response.json();
    return { messages };
  },

  async append(message) {
    // Save new message to storage
    await fetch(`/api/thread/messages`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ message }),
    });
  },

  // Optional: Resume interrupted conversations
  async resume({ messages }) {
    const lastMessage = messages[messages.length - 1];
    if (lastMessage?.role === "user") {
      // Resume generating assistant response
      const response = await fetch("/api/chat/resume", {
        method: "POST",
        body: JSON.stringify({ messages }),
      });
      return response.body; // Return stream
    }
  },
};

const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: { history: historyAdapter },
});
```

<Callout type="info">
  The history adapter handles persistence for the current thread's messages. For
  multi-thread support with custom storage, use either
  `useRemoteThreadListRuntime` with `LocalRuntime` or `ExternalStoreRuntime`
  with a thread list adapter.
</Callout>

Speech Synthesis Adapter \[#speech-synthesis-adapter]

Add text-to-speech capabilities:

```tsx
const speechAdapter: SpeechSynthesisAdapter = {
  speak(text) {
    const utterance = new SpeechSynthesisUtterance(text);
    utterance.rate = 1.0;
    utterance.pitch = 1.0;
    speechSynthesis.speak(utterance);
  },

  stop() {
    speechSynthesis.cancel();
  },
};

const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: { speech: speechAdapter },
});
```

Feedback Adapter \[#feedback-adapter]

Collect user feedback on messages:

```tsx
const feedbackAdapter: FeedbackAdapter = {
  async submit(feedback) {
    await fetch("/api/feedback", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        messageId: feedback.messageId,
        rating: feedback.type, // "positive" or "negative"
      }),
    });
  },
};

const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: { feedback: feedbackAdapter },
});
```

Suggestion Adapter \[#suggestion-adapter]

Provide follow-up suggestions:

```tsx
const suggestionAdapter: SuggestionAdapter = {
  async *generate({ messages }) {
    // Analyze conversation context
    const lastMessage = messages[messages.length - 1];

    // Generate suggestions
    const suggestions = await generateSuggestions(lastMessage);

    yield suggestions.map((text) => ({
      id: crypto.randomUUID(),
      text,
    }));
  },
};

const runtime = useLocalRuntime(MyModelAdapter, {
  adapters: { suggestion: suggestionAdapter },
});
```

Advanced Features \[#advanced-features]

Resuming a Run \[#resuming-a-run]

<Callout type="warning">
  The `unstable_resumeRun` method is experimental and may change in future
  releases.
</Callout>

Resume a conversation with a custom stream:

```tsx
import { useThreadRuntime, type ChatModelRunResult } from "@assistant-ui/react";

// Get the thread runtime
const thread = useThreadRuntime();

// Create a custom stream
async function* createCustomStream(): AsyncGenerator<ChatModelRunResult> {
  let text = "Initial response";
  yield {
    content: [{ type: "text", text }],
  };

  // Simulate delay
  await new Promise((resolve) => setTimeout(resolve, 500));

  text = "Initial response. And here's more content...";
  yield {
    content: [{ type: "text", text }],
  };
}

// Resume a run with the custom stream
thread.unstable_resumeRun({
  parentId: "message-id", // ID of the message to respond to
  stream: createCustomStream(), // The stream to use for resuming
});
```

Custom Thread Management \[#custom-thread-management]

Access thread runtime for advanced control with `useThreadRuntime`:

```tsx
import { useThreadRuntime } from "@assistant-ui/react";

function MyComponent() {
  const thread = useThreadRuntime();

  // Cancel current generation
  const handleCancel = () => {
    thread.cancelRun();
  };

  // Switch to a different branch
  const handleSwitchBranch = (messageId: string, branchIndex: number) => {
    thread.switchToBranch(messageId, branchIndex);
  };

  // Reload a message
  const handleReload = (messageId: string) => {
    thread.reload(messageId);
  };

  return (
    // Your UI
  );
}
```

Integration Examples \[#integration-examples]

OpenAI Integration \[#openai-integration]

```tsx
import { OpenAI } from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  dangerouslyAllowBrowser: true, // Use server-side in production
});

const OpenAIAdapter: ChatModelAdapter = {
  async *run({ messages, abortSignal, context }) {
    const stream = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: messages.map((m) => ({
        role: m.role,
        content: m.content
          .filter((c) => c.type === "text")
          .map((c) => c.text)
          .join("\n"),
      })),
      stream: true,
      signal: abortSignal,
    });

    for await (const chunk of stream) {
      const content = chunk.choices[0]?.delta?.content;
      if (content) {
        yield {
          content: [{ type: "text", text: content }],
        };
      }
    }
  },
};
```

Custom REST API Integration \[#custom-rest-api-integration]

```tsx
const CustomAPIAdapter: ChatModelAdapter = {
  async run({ messages, abortSignal, unstable_threadId }) {
    const response = await fetch("/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        messages: messages.map((m) => ({
          role: m.role,
          content: m.content,
        })),
        threadId: unstable_threadId, // Pass thread ID to your backend
      }),
      signal: abortSignal,
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.statusText}`);
    }

    const data = await response.json();
    return {
      content: [{ type: "text", text: data.message }],
    };
  },
};
```

Best Practices \[#best-practices]

1. **Error Handling** - Always handle API errors gracefully:

   ```tsx
   async *run({ messages, abortSignal }) {
     try {
       const response = await fetchAPI(messages, abortSignal);
       yield response;
     } catch (error) {
       if (error.name === 'AbortError') {
         // User cancelled - this is normal
         return;
       }
       // Re-throw other errors to display in UI
       throw error;
     }
   }
   ```

2. **Abort Signal** - Always pass the abort signal to fetch requests:

   ```tsx
   fetch(url, { signal: abortSignal });
   ```

3. **Memory Management** - For long conversations, consider implementing message limits:

   ```tsx
   const recentMessages = messages.slice(-20); // Keep last 20 messages
   ```

4. **Type Safety** - Use TypeScript for better development experience:
   ```tsx
   import type { ChatModelAdapter, ThreadMessage } from "@assistant-ui/react";
   ```

Comparison with ExternalStoreRuntime \[#comparison-with-externalstoreruntime]

| Feature               | `LocalRuntime`                               | `ExternalStoreRuntime`                           |
| --------------------- | -------------------------------------------- | ------------------------------------------------ |
| State Management      | Built-in                                     | You manage                                       |
| Setup Complexity      | Simple                                       | More complex                                     |
| Flexibility           | Extensible via adapters                      | Full control                                     |
| Message Editing       | Automatic                                    | Requires `onEdit` handler                        |
| Branch Switching      | Automatic                                    | Requires `setMessages` handler                   |
| Multi-Thread Support  | Yes (with Assistant Cloud or custom adapter) | Yes (with thread list adapter)                   |
| Custom Thread Storage | Yes (with useRemoteThreadListRuntime)        | Yes                                              |
| Persistence           | Via history adapter or Assistant Cloud       | Your implementation                              |
| Best For              | Quick prototypes, standard apps, cloud-based | Complex state requirements, custom storage needs |

Troubleshooting \[#troubleshooting]

Common Issues \[#common-issues]

<Callout type="error">
  **Messages not appearing**: Ensure your adapter returns the correct format:

  ```tsx
  return {
    content: [{ type: "text", text: "response" }]
  };
  ```
</Callout>

<Callout type="warning">
  **Streaming not working**: Make sure to use `async *run` (note the asterisk):

  ```tsx
  async *run({ messages }) { // ✅ Correct
  async run({ messages }) {  // ❌ Wrong for streaming
  ```
</Callout>

Tool UI Flickers or Disappears During Streaming \[#tool-ui-flickers-or-disappears-during-streaming]

A common issue when implementing a streaming `ChatModelAdapter` is seeing a tool's UI appear for a moment and then disappear. This is caused by failing to accumulate the `tool_calls` correctly across multiple stream chunks. State must be stored **outside** the streaming loop to persist.

**❌ Incorrect: Forgetting Previous Tool Calls**

This implementation incorrectly re-creates the `content` array for every chunk. If a later chunk contains only text, tool calls from previous chunks are lost, causing the UI to disappear.

```tsx
// This implementation incorrectly re-creates the `content` array for every chunk.
// If a later chunk contains only text, tool calls from previous chunks are lost.
async *run({ messages, abortSignal, context }) {
  const stream = await backendApi({ messages, abortSignal, context });
  let text = "";

  for await (const chunk of stream) {
    // ❌ DON'T: This overwrites toolCalls with only the current chunk's data
    const toolCalls = chunk.tool_calls || [];
    const content = [{ type: "text", text }];
    for (const toolCall of toolCalls) {
      content.push({
        type: "tool-call",
        toolName: toolCall.name,
        toolCallId: toolCall.id,
        args: toolCall.args,
      });
    }
    yield { content }; // This yield might not contain the tool call anymore
  }
}
```

**✅ Correct: Accumulating State**

This implementation uses a `Map` outside the loop to remember all tool calls.

```tsx
// This implementation uses a Map outside the loop to remember all tool calls.
async *run({ messages, abortSignal, context }) {
  const stream = await backendApi({ messages, abortSignal, context });
  let text = "";
  // ✅ DO: Declare state outside the loop
  const toolCallsMap = new Map();

  for await (const chunk of stream) {
    text += chunk.content || "";

    // ✅ DO: Add/update tool calls in the persistent map
    for (const toolCall of chunk.tool_calls || []) {
      toolCallsMap.set(toolCall.toolCallId, {
        type: "tool-call",
        toolName: toolCall.name,
        toolCallId: toolCall.toolCallId,
        args: toolCall.args,
      });
    }

    // ✅ DO: Build content from accumulated state
    const content = [
      ...(text ? [{ type: "text", text }] : []),
      ...Array.from(toolCallsMap.values()),
    ];

    yield { content }; // Yield the complete, correct state every time
  }
}
```

Debug Tips \[#debug-tips]

1. **Log adapter calls** to trace execution:

   ```tsx
   async *run(options) {
     console.log("Adapter called with:", options);
     // ... rest of implementation
   }
   ```

2. **Check network requests** in browser DevTools

3. **Verify message format** matches ThreadMessage structure

API Reference \[#api-reference]

ChatModelAdapter \[#chatmodeladapter]

The main interface for connecting your API to `LocalRuntime`.

<ParametersTable
  type="ChatModelAdapter"
  parameters={[
{
  name: "run",
  type: "ChatModelRunOptions => ChatModelRunResult | AsyncGenerator<ChatModelRunResult>",
  description:
    "Function that sends messages to your API and returns the response",
  required: true,
},
]}
/>

ChatModelRunOptions \[#chatmodelrunoptions]

Parameters passed to the `run` function.

<ParametersTable
  type="ChatModelRunOptions"
  parameters={[
{
  name: "messages",
  type: "readonly ThreadMessage[]",
  description: "The conversation history to send to your API",
  required: true,
},
{
  name: "abortSignal",
  type: "AbortSignal",
  description: "Signal to cancel the request if user interrupts",
  required: true,
},
{
  name: "context",
  type: "ModelContext",
  description: "Additional context including configuration and tools",
  required: true,
},
{
  name: "unstable_threadId",
  type: "string | undefined",
  description: "The current thread/conversation identifier. Useful for passing to your backend API.",
},
]}
/>

LocalRuntimeOptions \[#localruntimeoptions]

Configuration options for the `LocalRuntime`.

<ParametersTable
  type="LocalRuntimeOptions"
  parameters={[
{
  name: "initialMessages",
  type: "readonly ThreadMessage[]",
  description: "Pre-populate the thread with messages",
},
{
  name: "maxSteps",
  type: "number",
  description:
    "Maximum number of sequential tool calls before requiring user input",
  default: "5",
},
{
  name: "cloud",
  type: "AssistantCloud",
  description:
    "Enable Assistant Cloud integration for multi-thread support and persistence",
},
{
  name: "adapters",
  type: "LocalRuntimeAdapters",
  description:
    "Additional capabilities through adapters. Features are automatically enabled based on provided adapters",
  children: [
    {
      type: "adapters",
      parameters: [
        {
          name: "attachments",
          type: "AttachmentAdapter",
          description: "Enable file/image attachments",
        },
        {
          name: "speech",
          type: "SpeechSynthesisAdapter",
          description: "Enable text-to-speech for messages",
        },
        {
          name: "feedback",
          type: "FeedbackAdapter",
          description: "Enable message feedback (thumbs up/down)",
        },
        {
          name: "history",
          type: "ThreadHistoryAdapter",
          description: "Enable thread persistence and resumption",
        },
        {
          name: "suggestions",
          type: "SuggestionAdapter",
          description: "Enable follow-up suggestions",
        },
      ],
    },
  ],
},
{
  name: "unstable_humanToolNames",
  type: "string[]",
  description:
    "Tool names that require human approval before execution (experimental API)",
},
]}
/>

RemoteThreadListAdapter \[#remotethreadlistadapter]

Interface for implementing custom thread list storage.

<ParametersTable
  type="RemoteThreadListAdapter"
  parameters={[
{
  name: "list",
  type: "() => Promise<RemoteThreadListResponse>",
  description: "Returns list of all threads (regular and archived)",
  required: true,
},
{
  name: "initialize",
  type: "(threadId: string) => Promise<RemoteThreadInitializeResponse>",
  description: "Creates a new thread with the given ID",
  required: true,
},
{
  name: "rename",
  type: "(remoteId: string, newTitle: string) => Promise<void>",
  description: "Updates the title of a thread",
  required: true,
},
{
  name: "archive",
  type: "(remoteId: string) => Promise<void>",
  description: "Archives a thread",
  required: true,
},
{
  name: "unarchive",
  type: "(remoteId: string) => Promise<void>",
  description: "Unarchives a thread",
  required: true,
},
{
  name: "delete",
  type: "(remoteId: string) => Promise<void>",
  description: "Deletes a thread permanently",
  required: true,
},
{
  name: "generateTitle",
  type: "(remoteId: string, messages: readonly ThreadMessage[]) => Promise<AssistantStream>",
  description: "Generates a title for the thread based on the conversation",
  required: true,
},
]}
/>

Related Runtime APIs \[#related-runtime-apis]

* [AssistantRuntime API](/docs/api-reference/runtimes/assistant-runtime) - Core runtime interface and methods
* [ThreadRuntime API](/docs/api-reference/runtimes/thread-runtime) - Thread-specific operations and state management

Related Resources \[#related-resources]

* [Runtime Layer Concepts](/docs/concepts/runtime-layer)
* [Pick a Runtime Guide](/docs/runtimes/pick-a-runtime)
* [`ExternalStoreRuntime`](/docs/runtimes/custom/external-store)
* [Examples Repository](https://github.com/assistant-ui/assistant-ui/tree/main/examples)


# Getting Started
URL: /docs/runtimes/langgraph

Connect to LangGraph Cloud API for agent workflows with streaming.

Requirements \[#requirements]

You need a LangGraph Cloud API server. You can start a server locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or use [LangSmith](https://www.langchain.com/langsmith) for a hosted version.

The state of the graph you are using must have a `messages` key with a list of LangChain-alike messages.

New project from template \[#new-project-from-template]

<Steps>
  <Step>
    Create a new project based on the LangGraph assistant-ui template \[#create-a-new-project-based-on-the-langgraph-assistant-ui-template]

    ```sh
    npx create-assistant-ui@latest -t langgraph my-app
    ```
  </Step>

  <Step>
    Set environment variables \[#set-environment-variables]

    Create a `.env.local` file in your project with the following variables:

    ```sh
    # LANGCHAIN_API_KEY=your_api_key # for production
    # LANGGRAPH_API_URL=your_api_url # for production
    NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url # for development (no api key required)
    NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
    ```
  </Step>
</Steps>

Installation in existing React project \[#installation-in-existing-react-project]

<Steps>
  <Step>
    Install dependencies \[#install-dependencies]

    <InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk"]} />
  </Step>

  <Step>
    Setup a proxy backend endpoint (optional, for production) \[#setup-a-proxy-backend-endpoint-optional-for-production]

    <Callout type="warn">
      This example forwards every request to the LangGraph server directly from the
      browser. For production use-cases, you should limit the API calls to the
      subset of endpoints that you need and perform authorization checks.
    </Callout>

    ```tsx twoslash title="@/api/api/[...path]/route.ts"
    import { NextRequest, NextResponse } from "next/server";

    function getCorsHeaders() {
      return {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
        "Access-Control-Allow-Headers": "*",
      };
    }

    async function handleRequest(req: NextRequest, method: string) {
      try {
        const path = req.nextUrl.pathname.replace(/^\/?api\//, "");
        const url = new URL(req.url);
        const searchParams = new URLSearchParams(url.search);
        searchParams.delete("_path");
        searchParams.delete("nxtP_path");
        const queryString = searchParams.toString()
          ? `?${searchParams.toString()}`
          : "";

        const options: RequestInit = {
          method,
          headers: {
            "x-api-key": process.env["LANGCHAIN_API_KEY"] || "",
          },
        };

        if (["POST", "PUT", "PATCH"].includes(method)) {
          options.body = await req.text();
        }

        const res = await fetch(
          `${process.env["LANGGRAPH_API_URL"]}/${path}${queryString}`,
          options,
        );

        return new NextResponse(res.body, {
          status: res.status,
          statusText: res.statusText,
          headers: {
            ...res.headers,
            ...getCorsHeaders(),
          },
        });
      } catch (e: any) {
        return NextResponse.json({ error: e.message }, { status: e.status ?? 500 });
      }
    }

    export const GET = (req: NextRequest) => handleRequest(req, "GET");
    export const POST = (req: NextRequest) => handleRequest(req, "POST");
    export const PUT = (req: NextRequest) => handleRequest(req, "PUT");
    export const PATCH = (req: NextRequest) => handleRequest(req, "PATCH");
    export const DELETE = (req: NextRequest) => handleRequest(req, "DELETE");

    // Add a new OPTIONS handler
    export const OPTIONS = () => {
      return new NextResponse(null, {
        status: 204,
        headers: {
          ...getCorsHeaders(),
        },
      });
    };
    ```
  </Step>

  <Step>
    Setup helper functions \[#setup-helper-functions]

    ```tsx twoslash include chatApi title="@/lib/chatApi.ts"
    // @filename: /lib/chatApi.ts

    // ---cut---
    import { Client } from "@langchain/langgraph-sdk";
    import { LangChainMessage, LangGraphSendMessageConfig } from "@assistant-ui/react-langgraph";

    const createClient = () => {
      const apiUrl = process.env["NEXT_PUBLIC_LANGGRAPH_API_URL"] || "/api";
      return new Client({
        apiUrl,
      });
    };

    export const createThread = async () => {
      const client = createClient();
      return client.threads.create();
    };

    export const getThreadState = async (
      threadId: string,
    ): Promise<ThreadState<{ messages: LangChainMessage[] }>> => {
      const client = createClient();
      return client.threads.getState(threadId);
    };

    export const sendMessage = async (params: {
      threadId: string;
      messages: LangChainMessage[];
      config?: LangGraphSendMessageConfig;
    }) => {
      const client = createClient();
      const { checkpointId, ...restConfig } = params.config ?? {};
      return client.runs.stream(
        params.threadId,
        process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
        {
          input: params.messages.length > 0
            ? { messages: params.messages }
            : null,
          streamMode: "messages-tuple",
          ...(checkpointId && { checkpoint_id: checkpointId }),
          ...restConfig,
        },
      );
    };
    ```
  </Step>

  <Step>
    Define a MyAssistant component \[#define-a-myassistant-component]

    ```tsx twoslash include MyAssistant title="@/components/MyAssistant.tsx"
    // @filename: /components/MyAssistant.tsx
    // @include: chatApi

    // ---cut---
    "use client";

    import { Thread } from "@/components/assistant-ui/thread";
    import { AssistantRuntimeProvider } from "@assistant-ui/react";
    import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";

    import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";

    export function MyAssistant() {
      const runtime = useLangGraphRuntime({
        stream: async (messages, { initialize, ...config }) => {
          const { externalId } = await initialize();
          if (!externalId) throw new Error("Thread not found");
          return sendMessage({
            threadId: externalId,
            messages,
            config
          });
        },
        create: async () => {
          const { thread_id } = await createThread();
          return { externalId: thread_id };
        },
        load: async (externalId) => {
          const state = await getThreadState(externalId);
          return {
            messages: state.values.messages,
            interrupts: state.tasks[0]?.interrupts,
          };
        },
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <Thread />
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>

  <Step>
    Use the MyAssistant component \[#use-the-myassistant-component]

    ```tsx twoslash title="@/app/page.tsx" {1,6}
    // @include: MyAssistant
    // @filename: /app/page.tsx
    // ---cut---
    import { MyAssistant } from "@/components/MyAssistant";

    export default function Home() {
      return (
        <main className="h-dvh">
          <MyAssistant />
        </main>
      );
    }
    ```
  </Step>

  <Step>
    Setup environment variables \[#setup-environment-variables]

    Create a `.env.local` file in your project with the following variables:

    ```sh
    # LANGCHAIN_API_KEY=your_api_key # for production
    # LANGGRAPH_API_URL=your_api_url # for production
    NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url # for development (no api key required)
    NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
    ```
  </Step>

  <Step>
    Setup UI components \[#setup-ui-components]

    Follow the [UI Components](/docs/ui/thread) guide to setup the UI components.
  </Step>
</Steps>

Advanced APIs \[#advanced-apis]

Message Accumulator \[#message-accumulator]

The `LangGraphMessageAccumulator` lets you append messages incoming from the server to replicate the messages state client side.

```typescript
import {
  LangGraphMessageAccumulator,
  appendLangChainChunk,
} from "@assistant-ui/react-langgraph";

const accumulator = new LangGraphMessageAccumulator({
  appendMessage: appendLangChainChunk,
});

// Add new chunks from the server
if (event.event === "messages/partial") accumulator.addMessages(event.data);
```

Message Conversion \[#message-conversion]

Use `convertLangChainMessages` to transform LangChain messages to assistant-ui format:

```typescript
import { convertLangChainMessages } from "@assistant-ui/react-langgraph";

const threadMessage = convertLangChainMessages(langChainMessage);
```

Event Handlers \[#event-handlers]

You can listen to streaming events by passing `eventHandlers` to `useLangGraphRuntime`:

```typescript
const runtime = useLangGraphRuntime({
  stream: async (messages, { initialize, ...config }) => { /* ... */ },
  eventHandlers: {
    onMessageChunk: (chunk, metadata) => {
      // Fired for each chunk in messages-tuple mode
      // metadata contains langgraph_step, langgraph_node, ls_model_name, etc.
    },
    onValues: (values) => {
      // Fired when a "values" event is received
    },
    onUpdates: (updates) => {
      // Fired when an "updates" event is received
    },
    onMetadata: (metadata) => { /* thread metadata */ },
    onError: (error) => { /* stream errors */ },
    onCustomEvent: (type, data) => { /* custom events */ },
  },
});
```

Message Metadata \[#message-metadata]

When using `streamMode: "messages-tuple"`, each chunk includes metadata from the LangGraph server. Access accumulated metadata per message with the `useLangGraphMessageMetadata` hook:

```typescript
import { useLangGraphMessageMetadata } from "@assistant-ui/react-langgraph";

function MyComponent() {
  const metadata = useLangGraphMessageMetadata();
  // Map<string, LangGraphTupleMetadata> keyed by message ID
}
```

Thread Management \[#thread-management]

Basic Thread Support \[#basic-thread-support]

The `useLangGraphRuntime` hook now includes built-in thread management capabilities:

```typescript
const runtime = useLangGraphRuntime({
  stream: async (messages, { initialize, ...config }) => {
    // initialize() creates or loads a thread and returns its IDs
    const { remoteId, externalId } = await initialize();
    // Use externalId (your backend's thread ID) for API calls
    return sendMessage({ threadId: externalId, messages, config });
  },
  create: async () => {
    // Called when creating a new thread
    const { thread_id } = await createThread();
    return { externalId: thread_id };
  },
  load: async (externalId) => {
    // Called when loading an existing thread
    const state = await getThreadState(externalId);
    return {
      messages: state.values.messages,
      interrupts: state.tasks[0]?.interrupts,
    };
  },
});
```

Cloud Persistence \[#cloud-persistence]

For persistent thread history across sessions, integrate with assistant-cloud:

```typescript
const runtime = useLangGraphRuntime({
  cloud: new AssistantCloud({
    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
  }),
  // ... stream, create, load functions
});
```

See the [Cloud Persistence guide](/docs/cloud/langgraph) for detailed setup instructions.

Message Editing & Regeneration \[#message-editing--regeneration]

LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, you need to provide a `getCheckpointId` callback that resolves the appropriate checkpoint for server-side forking.

```typescript
const runtime = useLangGraphRuntime({
  stream: async (messages, { initialize, ...config }) => {
    const { externalId } = await initialize();
    if (!externalId) throw new Error("Thread not found");
    return sendMessage({ threadId: externalId, messages, config });
  },
  create: async () => {
    const { thread_id } = await createThread();
    return { externalId: thread_id };
  },
  load: async (externalId) => {
    const state = await getThreadState(externalId);
    return {
      messages: state.values.messages,
      interrupts: state.tasks[0]?.interrupts,
    };
  },
  getCheckpointId: async (threadId, parentMessages) => {
    const client = createClient();
    // Get the thread state history and find the checkpoint
    // that matches the parent messages by exact message ID sequence.
    // If IDs are missing, return null and skip edit/reload for safety.
    const history = await client.threads.getHistory(threadId);
    for (const state of history) {
      const stateMessages = state.values.messages;
      if (!stateMessages || stateMessages.length !== parentMessages.length) {
        continue;
      }

      const hasStableIds =
        parentMessages.every((message) => typeof message.id === "string") &&
        stateMessages.every((message) => typeof message.id === "string");
      if (!hasStableIds) {
        continue;
      }

      const isMatch = parentMessages.every(
        (message, index) => message.id === stateMessages[index]?.id,
      );

      if (isMatch) {
        return state.checkpoint.checkpoint_id ?? null;
      }
    }
    return null;
  },
});
```

When `getCheckpointId` is provided:

* **Edit buttons** appear on user messages, allowing users to edit and resend from that point
* **Regenerate buttons** appear on assistant messages, allowing users to regenerate the response

The resolved `checkpointId` is passed to your `stream` callback via `config.checkpointId`. Your `sendMessage` helper should map it to the LangGraph SDK's `checkpoint_id` parameter (see the helper function in the setup section above).

<Callout type="info">
  Without `getCheckpointId`, the edit and regenerate buttons will not appear. This is intentional — simply truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.
</Callout>

Interrupt Persistence \[#interrupt-persistence]

LangGraph supports interrupting the execution flow to request user input or handle specific interactions. These interrupts can be persisted and restored when switching between threads:

1. Make sure your thread state type includes the `interrupts` field
2. Return the interrupts from the `load` function along with the messages
3. The runtime will automatically restore the interrupt state when switching threads

This feature is particularly useful for applications that require user approval flows, multi-step forms, or any other interactive elements that might span multiple thread switches.


# Full-Stack Integration
URL: /docs/runtimes/mastra/full-stack-integration

Integrate Mastra directly into Next.js API routes.

Integrate Mastra directly into your Next.js application's API routes. This approach keeps your backend and frontend code within the same project.

<Steps>
  <Step>
    Initialize assistant-ui \[#initialize-assistant-ui]

    Start by setting up assistant-ui in your project. Run one of the following commands:

    ```sh title="New Project"
    npx assistant-ui@latest create
    ```

    ```sh title="Existing Project"
    npx assistant-ui@latest init
    ```

    This command installs necessary dependencies and creates basic configuration files, including a default chat API route.

    <Callout title="Need Help?">
      For detailed setup instructions, including adding API keys, basic
      configuration, and manual setup steps, please refer to the main [Getting
      Started guide](/docs).
    </Callout>
  </Step>

  <Step>
    Review Initial API Route \[#review-initial-api-route]

    The initialization command creates a basic API route at `app/api/chat/route.ts` (or `src/app/api/chat/route.ts`). It typically looks like this:

    ```typescript title="app/api/chat/route.ts"
    import { openai } from "@ai-sdk/openai";
    import { streamText } from "ai";

    // Allow streaming responses up to 30 seconds
    export const maxDuration = 30;

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = streamText({
        model: openai("gpt-4o-mini"),
        messages,
      });

      return result.toUIMessageStreamResponse();
    }
    ```

    This default route uses the Vercel AI SDK directly with OpenAI. In the following steps, we will modify this route to integrate Mastra.
  </Step>

  <Step>
    Install Mastra Packages \[#install-mastra-packages]

    Add the `@mastra/core` package and its peer dependency `zod` (which you can use later inside tools for example). Also add `@mastra/ai-sdk` to convert Mastra's stream to an AI SDK-compatible format:

    <InstallCommand npm={["@mastra/core@latest", "@mastra/ai-sdk@latest", "zod@latest"]} />
  </Step>

  <Step>
    Configure Next.js \[#configure-nextjs]

    To ensure Next.js correctly bundles your application when using Mastra directly in API routes, you need to configure `serverExternalPackages`.

    Update your `next.config.mjs` (or `next.config.js`) file to include `@mastra/*`:

    ```js title="next.config.mjs"
    /** @type {import('next').NextConfig} */
    const nextConfig = {
      serverExternalPackages: ["@mastra/*"],
      // ... other configurations
    };

    export default nextConfig;
    ```

    This tells Next.js to treat Mastra packages as external dependencies on the server-side.
  </Step>

  <Step>
    Create Mastra Files \[#create-mastra-files]

    Set up the basic folder structure for your Mastra configuration. Create a `mastra` folder (e.g., in your `src` or root directory) with the following structure:

    ```txt title="Project Structure"
    /
    ├── mastra/
    │   ├── agents/
    │   │   └── chefAgent.ts
    │   └── index.ts
    └── ... (rest of your project)
    ```

    You can create these files and folders manually or use the following commands in your terminal:

    ```bash
    mkdir -p mastra/agents
    touch mastra/index.ts mastra/agents/chefAgent.ts
    ```

    These files will be used in the next steps to define your Mastra agent and configuration.
  </Step>

  <Step>
    Define the Agent \[#define-the-agent]

    Now, let's define the behavior of our AI agent. Open the `mastra/agents/chefAgent.ts` file and add the following code:

    ```typescript title="mastra/agents/chefAgent.ts"
    import { Agent } from "@mastra/core/agent";

    export const chefAgent = new Agent({
      name: "chef-agent",
      instructions:
        "You are Michel, a practical and experienced home chef. " +
        "You help people cook with whatever ingredients they have available.",
      model: "openai/gpt-4o-mini",
    });
    ```

    This code creates a new Mastra `Agent` named `chef-agent`.

    * `instructions`: Defines the agent's persona and primary goal.
    * `model`: Specifies the language model the agent will use (in this case, OpenAI's GPT-4o Mini via Mastra's model router).

    Make sure you have set up your OpenAI API key as described in the [Getting Started guide](/docs).
  </Step>

  <Step>
    Register the Agent \[#register-the-agent]

    Next, register the agent with your Mastra instance. Open the `mastra/index.ts` file and add the following code:

    ```typescript title="mastra/index.ts"
    import { Mastra } from "@mastra/core";
    import { chefAgent } from "./agents/chefAgent";

    export const mastra = new Mastra({
      agents: { chefAgent },
    });
    ```

    This code initializes Mastra and makes the `chefAgent` available for use in your application's API routes.
  </Step>

  <Step>
    Modify the API Route \[#modify-the-api-route]

    Now, update your API route (`app/api/chat/route.ts`) to use the Mastra agent you just configured. Replace the existing content with the following:

    ```typescript title="app/api/chat/route.ts"
    import { createUIMessageStreamResponse } from "ai";
    import { toAISdkFormat } from "@mastra/ai-sdk";
    import { mastra } from "@/mastra"; // Adjust the import path if necessary

    // Allow streaming responses up to 30 seconds
    export const maxDuration = 30;

    export async function POST(req: Request) {
      // Extract the messages from the request body
      const { messages } = await req.json();

      // Get the chefAgent instance from Mastra
      const agent = mastra.getAgent("chefAgent");

      // Stream the response using the agent
      const stream = await agent.stream(messages);

      // Create a Response that streams the UI message stream to the client
      return createUIMessageStreamResponse({
        stream: toAISdkFormat(stream, { from: "agent" }),
      });
    }
    ```

    Key changes:

    * We import the `mastra` instance created in `mastra/index.ts`. Make sure the import path (`@/mastra`) is correct for your project setup (you might need `~/mastra`, `../../../mastra`, etc., depending on your path aliases and project structure).
    * We retrieve the `chefAgent` using `mastra.getAgent("chefAgent")`.
    * Instead of calling the AI SDK's `streamText` directly, we call `agent.stream(messages)` to process the chat messages using the agent's configuration and model.
    * The result is still returned in a format compatible with assistant-ui using `createUIMessageStreamResponse()` and `toAISdkFormat()`.

    Your API route is now powered by Mastra!
  </Step>

  <Step>
    Run the Application \[#run-the-application]

    You're all set! Start your Next.js development server:

    ```bash npm2yarn
    npm run dev
    ```

    Open your browser to `http://localhost:3000` (or the port specified in your terminal). You should now be able to interact with your `chefAgent` through the assistant-ui chat interface. Ask it for cooking advice based on ingredients you have!
  </Step>
</Steps>

Congratulations! You have successfully integrated Mastra into your Next.js application using the full-stack approach. Your assistant-ui frontend now communicates with a Mastra agent running in your Next.js backend API route.

To explore more advanced Mastra features like memory, tools, workflows, and more, please refer to the [official Mastra documentation](https://mastra.ai/docs).


# Overview
URL: /docs/runtimes/mastra/overview

TypeScript agent framework for AI applications with tools and workflows.

Mastra is an open-source TypeScript agent framework designed to provide the essential primitives for building AI applications. It enables developers to create AI agents with memory and tool-calling capabilities, implement deterministic LLM workflows, and leverage RAG for knowledge integration. With features like model routing, workflow graphs, and automated evals, Mastra provides a complete toolkit for developing, testing, and deploying AI applications.

Integrating with Next.js and assistant-ui \[#integrating-with-nextjs-and-assistant-ui]

There are two primary ways to integrate Mastra into your Next.js project when using assistant-ui:

1. **Full-Stack Integration**: Integrate Mastra directly into your Next.js application's API routes. This approach keeps your backend and frontend code within the same project.
   [Learn how to set up Full-Stack Integration](./full-stack-integration)

2. **Separate Server Integration**: Run Mastra as a standalone server and connect your Next.js frontend to its API endpoints. This approach separates concerns and allows for independent scaling.
   [Learn how to set up Separate Server Integration](./separate-server-integration)

Choose the guide that best fits your project architecture. Both methods allow seamless integration with the assistant-ui components.


# Separate Server Integration
URL: /docs/runtimes/mastra/separate-server-integration

Run Mastra as a standalone server connected to your frontend.

Run Mastra as a standalone server and connect your Next.js frontend (using assistant-ui) to its API endpoints. This approach separates your AI backend from your frontend application, allowing for independent development and scaling.

<Steps>
  <Step>
    Create Mastra Server Project \[#create-mastra-server-project]

    First, create a dedicated project for your Mastra server. Choose a directory separate from your Next.js/assistant-ui frontend project.

    Navigate to your chosen parent directory in the terminal and run the Mastra create command:

    ```bash
    npx create-mastra@latest
    ```

    This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project. For more detailed setup instructions, refer to the [official Mastra installation guide](https://mastra.ai/docs/getting-started/installation).

    Once the setup is complete, navigate into your new Mastra project directory (the name you provided during the setup):

    ```bash
    cd your-mastra-server-directory # Replace with the actual directory name
    ```

    In the next steps you'll need to use the `@mastra/ai-sdk` package. Add it to your Mastra project:

    <InstallCommand npm={["@mastra/ai-sdk@latest"]} />

    You now have a basic Mastra server project ready.

    <Callout title="API Keys">
      Ensure you have configured your environment variables (e.g., `OPENAI_API_KEY`)
      within this Mastra server project, typically in a `.env.development` file, as
      required by the models you use. The `create-mastra` wizard might prompt you
      for some keys, but ensure all necessary keys for your chosen models are
      present.
    </Callout>
  </Step>

  <Step>
    Define the Agent \[#define-the-agent]

    Next, let's define an agent within your Mastra server project. We'll create a `chefAgent` similar to the one used in the full-stack guide.

    Open or create the agent file (e.g., `src/mastra/agents/chefAgent.ts` within your Mastra project) and add the following code:

    ```typescript title="src/mastra/agents/chefAgent.ts"
    import { Agent } from "@mastra/core/agent";

    export const chefAgent = new Agent({
      name: "chef-agent",
      instructions:
        "You are Michel, a practical and experienced home chef. " +
        "You help people cook with whatever ingredients they have available.",
      model: "openai/gpt-4o-mini",
    });
    ```

    This defines the agent's behavior, but it's not yet active in the Mastra server.
  </Step>

  <Step>
    Register the Agent \[#register-the-agent]

    Now, you need to register the `chefAgent` with your Mastra instance so the server knows about it. Open your main Mastra configuration file (this is often `src/mastra/index.ts` in projects created with `create-mastra`).

    Import the `chefAgent` and add it to the `agents` object when initializing Mastra:

    ```typescript title="src/mastra/index.ts"
    import { Mastra } from "@mastra/core";
    import { chefAgent } from "./agents/chefAgent"; // Adjust path if necessary

    export const mastra = new Mastra({
      agents: { chefAgent },
    });
    ```

    Make sure you adapt this code to fit the existing structure of your `src/mastra/index.ts` file generated by `create-mastra`. The key is to import your agent and include it in the `agents` configuration object.
  </Step>

  <Step>
    Register the Chat Route \[#register-the-chat-route]

    Still inside `src/mastra/index.ts`, register a chat route for the `chefAgent` now. You can do this by using `chatRoute()` from `@mastra/ai-sdk`. You need to place this inside `server.apiRoutes` of your Mastra configuration:

    ```typescript title="src/mastra/index.ts" {3,7-13}
    import { Mastra } from "@mastra/core";
    import { chefAgent } from "./agents/chefAgent";
    import { chatRoute } from "@mastra/ai-sdk";

    export const mastra = new Mastra({
      agents: { chefAgent },
      server: {
        apiRoutes: [
          chatRoute({
            path: "/chat/:agentId",
          }),
        ],
      },
    });
    ```

    Make sure you adapt this code to fit the existing structure of your `src/mastra/index.ts` file generated by `create-mastra`. This will make all agents available in AI SDK-compatible formats, including the `chefAgent` at the endpoint `/chat/chefAgent`.
  </Step>

  <Step>
    Run the Mastra Server \[#run-the-mastra-server]

    With the agent defined and registered, start the Mastra development server:

    ```bash npm2yarn
    npm run dev
    ```

    By default, the Mastra server will run on `http://localhost:4111`. Keep this server running for the next steps where we'll set up the assistant-ui frontend to connect to it.
  </Step>

  <Step>
    Initialize assistant-ui Frontend \[#initialize-assistant-ui-frontend]

    Now, set up your frontend application using assistant-ui. Navigate to a **different directory** from your Mastra server project. You can either create a new Next.js project or use an existing one.

    Inside your frontend project directory, run one of the following commands:

    ```sh title="New Project"
    npx assistant-ui@latest create
    ```

    ```sh title="Existing Project"
    npx assistant-ui@latest init
    ```

    This command installs the necessary assistant-ui dependencies and sets up basic configuration files, including a default chat page and an API route (`app/api/chat/route.ts`).

    <Callout title="Need Help?">
      For detailed setup instructions for assistant-ui, including manual setup
      steps, please refer to the main [Getting Started
      guide](/docs).
    </Callout>

    In the next step, we will configure this frontend to communicate with the separate Mastra server instead of using the default API route.
  </Step>

  <Step>
    Configure Frontend API Endpoint \[#configure-frontend-api-endpoint]

    The default assistant-ui setup configures the chat runtime to use a local API route (`/api/chat`) within the Next.js project. Since our Mastra agent is running on a separate server, we need to update the frontend to point to that server's endpoint.

    Open the file in your assistant-ui frontend project that contains the `useChatRuntime` hook (usually `app/assistant.tsx` or `src/app/assistant.tsx`). Find the `useChatRuntime` hook and change the `api` property to the full URL of your Mastra agent's stream endpoint:

    ```tsx {8} title="app/assistant.tsx"
    "use client";

    // Rest of the imports...

    export const Assistant = () => {
      const runtime = useChatRuntime({
        transport: new AssistantChatTransport({
          api: "http://localhost:4111/chat/chefAgent",
        }),
      });

      // Rest of the component...
    };
    ```

    Replace `"http://localhost:4111/chat/chefAgent"` with the actual URL if your Mastra server runs on a different port or host, or if your agent has a different name.

    Now, the assistant-ui frontend will send chat requests directly to your running Mastra server.

    <Callout title="Delete Default API Route">
      Since the frontend no longer uses the local `/api/chat` route created by the
      `init` command, you can safely delete the `app/api/chat/route.ts` (or
      `src/app/api/chat/route.ts`) file from your frontend project.
    </Callout>
  </Step>

  <Step>
    Run the Frontend Application \[#run-the-frontend-application]

    You're ready to connect the pieces! Make sure your separate Mastra server is still running (from Step 4).

    In your assistant-ui frontend project directory, start the Next.js development server:

    ```bash npm2yarn
    npm run dev
    ```

    Open your browser to `http://localhost:3000` (or the port specified in your terminal for the frontend app). You should now be able to interact with your `chefAgent` through the assistant-ui chat interface. The frontend will make requests to your Mastra server running on `http://localhost:4111`.
  </Step>
</Steps>

Congratulations! You have successfully integrated Mastra with assistant-ui using a separate server approach. Your assistant-ui frontend now communicates with a standalone Mastra agent server.

This setup provides a clear separation between your frontend and AI backend. To explore more advanced Mastra features like memory, tools, workflows, and deployment options, please refer to the [official Mastra documentation](https://mastra.ai/docs).


# <AssistantRuntimeProvider />
URL: /docs/api-reference/context-providers/assistant-runtime-provider

Root provider that connects your runtime to assistant-ui components.

import { AssistantRuntimeProvider } from "@/generated/typeDocs";

The `AssistantRuntimeProvider` provides data and APIs used by assistant-ui components.

Almost all components in assistant-ui require an `AssistantRuntimeProvider` around them to function properly.

You must either wrap your app in an `AssistantRuntimeProvider` or pass a `runtime` to the `<Thread />` component instead.

```tsx {1, 8, 10}
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";

const MyApp = () => {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({
      api: "/api/chat",
    }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your app */}
    </AssistantRuntimeProvider>
  );
};
```

Properties \[#properties]

<ParametersTable {...AssistantRuntimeProvider} />


# <TextMessagePartProvider />
URL: /docs/api-reference/context-providers/text-message-part-provider

Context provider for reusing text components outside of message content.

import { AssistantRuntimeProvider } from "@/generated/typeDocs";

The `TextMessagePartProvider` provides data and APIs for `TextMessagePart` components.

This is useful if you want to reuse the same `Text` component outside of a message text, e.g. with the `@assistant-ui/react-markdown` package.

```tsx {1, 8, 10}
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyApp = () => {
  return (
    <TextMessagePartProvider text={"Hello!"}>
      <MyMarkdownText />
    </AssistantRuntimeProvider>
  );
};
```

Properties \[#properties]

<ParametersTable {...AssistantRuntimeProvider} />


# @assistant-ui/react-data-stream
URL: /docs/api-reference/integrations/react-data-stream

Hooks for connecting to data stream protocol endpoints and Assistant Cloud.

Data Stream protocol integration for assistant-ui.

API Reference \[#api-reference]

useDataStreamRuntime \[#usedatastreamruntime]

Create a runtime that connects to a data stream protocol endpoint.

```tsx
import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useDataStreamRuntime({
    api: "/api/chat",
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

<ParametersTable
  parameters={[
{
  name: "api",
  type: "string",
  description: "The API endpoint URL for the data stream protocol.",
},
{
  name: "onResponse",
  type: "(response: Response) => void | Promise<void>",
  description: "Optional callback called when a response is received.",
},
{
  name: "onFinish",
  type: "(message: ThreadMessage) => void",
  description: "Optional callback called when a message is finished.",
},
{
  name: "onError",
  type: "(error: Error) => void",
  description: "Optional callback called when an error occurs.",
},
{
  name: "onCancel",
  type: "() => void",
  description: "Optional callback called when a request is cancelled.",
},
{
  name: "credentials",
  type: "RequestCredentials",
  description: "Optional credentials mode for the fetch request.",
},
{
  name: "headers",
  type: "Record<string, string> | Headers | (() => Promise<Record<string, string> | Headers>)",
  description: "Optional headers to include in the request.",
},
{
  name: "body",
  type: "object",
  description: "Optional additional body parameters to include in the request.",
},
{
  name: "sendExtraMessageFields",
  type: "boolean",
  description: "Whether to include extra message fields like IDs in the request.",
},
]}
/>

useCloudRuntime \[#usecloudruntime]

Create a runtime that connects to Assistant Cloud using the data stream protocol.

```tsx
import { useCloudRuntime } from "@assistant-ui/react-data-stream";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useCloudRuntime({
    cloud: assistantCloud,
    assistantId: "my-assistant-id",
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

<ParametersTable
  parameters={[
{
  name: "cloud",
  type: "AssistantCloud",
  description: "The Assistant Cloud instance.",
},
{
  name: "assistantId",
  type: "string",
  description: "The ID of the assistant to connect to.",
},
{
  name: "onResponse",
  type: "(response: Response) => void | Promise<void>",
  description: "Optional callback called when a response is received.",
},
{
  name: "onFinish",
  type: "(message: ThreadMessage) => void",
  description: "Optional callback called when a message is finished.",
},
{
  name: "onError",
  type: "(error: Error) => void",
  description: "Optional callback called when an error occurs.",
},
{
  name: "onCancel",
  type: "() => void",
  description: "Optional callback called when a request is cancelled.",
},
{
  name: "credentials",
  type: "RequestCredentials",
  description: "Optional credentials mode for the fetch request.",
},
{
  name: "headers",
  type: "Record<string, string> | Headers | (() => Promise<Record<string, string> | Headers>)",
  description: "Optional headers to include in the request.",
},
{
  name: "body",
  type: "object",
  description: "Optional additional body parameters to include in the request.",
},
{
  name: "sendExtraMessageFields",
  type: "boolean",
  description: "Whether to include extra message fields like IDs in the request.",
},
]}
/>

toLanguageModelMessages \[#tolanguagemodelmessages]

Convert assistant-ui messages to AI SDK's `LanguageModelV2Message` format.

<Callout type="info">
  For custom integrations, consider using `toGenericMessages` from `assistant-stream` instead.
  This function is specific to the AI SDK format.
</Callout>

```tsx
import { toLanguageModelMessages } from "@assistant-ui/react-data-stream";

const languageModelMessages = toLanguageModelMessages(messages, {
  unstable_includeId: true,
});
```

<ParametersTable
  parameters={[
{
  name: "messages",
  type: "readonly ThreadMessage[]",
  description: "The messages to convert.",
},
{
  name: "options",
  type: "{ unstable_includeId?: boolean }",
  description: "Optional conversion options.",
  children: [
    {
      type: "{ unstable_includeId?: boolean }",
      parameters: [
        {
          name: "unstable_includeId",
          type: "boolean",
          description: "Whether to include message IDs in the converted messages.",
        },
      ],
    },
  ],
},
]}
/>

***

Framework-Agnostic Utilities \[#framework-agnostic-utilities]

For custom integrations that don't use the AI SDK, use these utilities from `assistant-stream`:

toGenericMessages \[#togenericmessages]

Convert thread messages to a framework-agnostic format.

```tsx
import { toGenericMessages } from "assistant-stream";

const genericMessages = toGenericMessages(messages);
```

Returns an array of `GenericMessage` which can be one of:

* `{ role: "system"; content: string }`
* `{ role: "user"; content: (GenericTextPart | GenericFilePart)[] }`
* `{ role: "assistant"; content: (GenericTextPart | GenericToolCallPart)[] }`
* `{ role: "tool"; content: GenericToolResultPart[] }`

toToolsJSONSchema \[#totoolsjsonschema]

Convert tool definitions to JSON Schema format.

```tsx
import { toToolsJSONSchema } from "assistant-stream";

const toolSchemas = toToolsJSONSchema(tools);
// Returns: Record<string, { description?: string; parameters: JSONSchema7 }>
```

By default, filters out disabled tools and backend-only tools. Use the `filter` option to customize:

```tsx
const allTools = toToolsJSONSchema(tools, {
  filter: () => true, // Include all tools
});
```


# @assistant-ui/react-hook-form
URL: /docs/api-reference/integrations/react-hook-form

React Hook Form integration for AI-assisted form filling.

A React Hook Form integration for @assistant-ui.

API Reference \[#api-reference]

useAssistantForm \[#useassistantform]

Drop-in replacement hook for `useForm` that adds support for `@assistant-ui/react`.

```diff
- import { useForm } from "react-hook-form";
+ import { useAssistantForm } from "@assistant-ui/react-hook-form";

- useForm({
+ useAssistantForm({
    ...
  });
```

Properties \[#properties]

<ParametersTable
  type="UseAssistantFormProps"
  parameters={[
{
  name: "assistant",
  type: "object",
  optional: true,
  description: "Configuration for useAssistantForm",
  children: [
    {
      parameters: [
        {
          name: "tools",
          type: "object",
          description: "Tools configuration for useAssistantForm",
          children: [
            {
              parameters: [
                {
                  name: "set_form_field",
                  type: "object",
                  description: "Configuration for the set_form_field tool",
                  children: [
                    {
                      parameters: [
                        {
                          name: "render",
                          type: "ToolCallMessagePartComponent<{ name: string; value: string; }, {}>",
                          description:
                            "The component to render when set_form_field is called.",
                        },
                      ],
                    },
                  ],
                },
                {
                  name: "submit_form",
                  type: "object",
                  description: "Configuration for the submit_form tool",
                  children: [
                    {
                      parameters: [
                        {
                          name: "render",
                          type: "ToolCallMessagePartComponent<{}, {}>",
                          description:
                            "The component to render when submit_form is called.",
                        },
                      ],
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    },
  ],
},
]}
/>

formTools \[#formtools]

The set of tools to use with `useAssistantForm`, useful for runtimes that do not support client-side tool definitions (i.e. Vercel AI SDK).

```tsx {1, 5-7}
import { formTools } from "@assistant-ui/react-hook-form";

const result = streamText({
  ...
  tools: {
    ...formTools,
  }
});
```


# @assistant-ui/react-ai-sdk
URL: /docs/api-reference/integrations/vercel-ai-sdk

Vercel AI SDK v5 integration with chat runtime hooks and transport utilities.

Vercel AI SDK integration for assistant-ui.

<Callout type="info">
  This package provides integration with AI SDK v5. For AI SDK v4, see the [AI
  SDK v4 (Legacy)](/docs/runtimes/ai-sdk/v4-legacy) documentation.
</Callout>

API Reference \[#api-reference]

useChatRuntime \[#usechatruntime]

Creates a runtime directly with AI SDK v5's `useChat` hook integration. This is the recommended approach for most use cases.

```tsx
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({
      api: "/api/chat",
    }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

To customize the API endpoint, simply change the `api` parameter:

```tsx
const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

<ParametersTable
  parameters={[
{
  name: "options",
  type: "UseChatRuntimeOptions",
  description: "Configuration options for the chat runtime.",
  children: [
    {
      type: "UseChatRuntimeOptions",
      parameters: [
        {
          name: "api",
          type: "string",
          description: "The API endpoint URL. Defaults to '/api/chat'.",
        },
        {
          name: "transport",
          type: "ChatTransport",
          description:
            "Custom transport implementation. Defaults to AssistantChatTransport which forwards system messages and tools.",
        },
        {
          name: "cloud",
          type: "AssistantCloud",
          description:
            "Optional AssistantCloud instance for chat persistence.",
        },
        {
          name: "initialMessages",
          type: "UIMessage[]",
          description: "Initial messages to populate the chat.",
        },
        {
          name: "onFinish",
          type: "(message: UIMessage) => void",
          description: "Callback when a message completes streaming.",
        },
        {
          name: "onError",
          type: "(error: Error) => void",
          description: "Callback for handling errors.",
        },
      ],
    },
  ],
},
]}
/>

<Callout type="info">
  By default, `useChatRuntime` uses `AssistantChatTransport` which automatically
  forwards system messages and frontend tools to your backend API. This enables
  your backend to receive the full context from the assistant-ui.
</Callout>

useAISDKRuntime \[#useaisdkruntime]

For advanced use cases where you need direct access to the `useChat` hook from AI SDK.

```tsx
import { useChat } from "@ai-sdk/react";
import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const chat = useChat({
    api: "/api/chat",
  });

  const runtime = useAISDKRuntime(chat);

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

<ParametersTable
  parameters={[
{
  name: "chat",
  type: "ReturnType<typeof useChat>",
  description: "The chat helpers from @ai-sdk/react's useChat hook.",
},
{
  name: "options",
  type: "AISDKRuntimeOptions",
  description: "Optional configuration options.",
  children: [
    {
      type: "AISDKRuntimeOptions",
      parameters: [
        {
          name: "cloud",
          type: "AssistantCloud",
          description:
            "Optional AssistantCloud instance for chat persistence.",
        },
        {
          name: "adapters",
          type: "RuntimeAdapters",
          description:
            "Optional runtime adapters for attachments, feedback, speech, etc.",
        },
      ],
    },
  ],
},
]}
/>

AssistantChatTransport \[#assistantchattransport]

A transport that extends the default AI SDK transport to automatically forward system messages and frontend tools to your backend.

```tsx
import { AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

<ParametersTable
  parameters={[
{
  name: "options",
  type: "HttpChatTransportInitOptions",
  description: "Transport configuration options.",
  children: [
    {
      type: "HttpChatTransportInitOptions",
      parameters: [
        {
          name: "api",
          type: "string",
          description: "The API endpoint URL.",
        },
        {
          name: "headers",
          type: "Record<string, string> | Headers",
          description: "Optional headers to include in requests.",
        },
        {
          name: "credentials",
          type: "RequestCredentials",
          description: "Optional credentials mode for fetch requests.",
        },
      ],
    },
  ],
},
]}
/>

frontendTools \[#frontendtools]

Helper function to convert frontend tool definitions to AI SDK format for use in your backend.

```tsx
import { frontendTools } from "@assistant-ui/react-ai-sdk";
import { streamText, convertToModelMessages } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages, system, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system,
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with the helper
      ...frontendTools(tools),
      // Your backend tools
      myBackendTool: tool({
        // ...
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}
```

<ParametersTable
  parameters={[
{
  name: "tools",
  type: "Record<string, unknown>",
  description:
    "Frontend tools object forwarded from AssistantChatTransport.",
},
]}
/>

<Callout type="info">
  The `frontendTools` helper converts frontend tool definitions to the AI SDK
  format and ensures they are properly handled by the streaming response.
</Callout>


# ActionBarMorePrimitive
URL: /docs/api-reference/primitives/action-bar-more

A dropdown menu for additional actions that don't fit in the main action bar.

Anatomy \[#anatomy]

```tsx
import { ActionBarPrimitive, ActionBarMorePrimitive } from "@assistant-ui/react";

const MessageActions = () => (
  <ActionBarPrimitive.Root>
    <ActionBarPrimitive.Copy />
    <ActionBarPrimitive.Reload />

    <ActionBarMorePrimitive.Root>
      <ActionBarMorePrimitive.Trigger>
        <MoreHorizontalIcon />
      </ActionBarMorePrimitive.Trigger>
      <ActionBarMorePrimitive.Content>
        <ActionBarMorePrimitive.Item onSelect={() => console.log("Edit")}>
          Edit
        </ActionBarMorePrimitive.Item>
        <ActionBarMorePrimitive.Item onSelect={() => console.log("Speak")}>
          Read aloud
        </ActionBarMorePrimitive.Item>
        <ActionBarMorePrimitive.Separator />
        <ActionBarMorePrimitive.Item onSelect={() => console.log("Feedback")}>
          Submit feedback
        </ActionBarMorePrimitive.Item>
      </ActionBarMorePrimitive.Content>
    </ActionBarMorePrimitive.Root>
  </ActionBarPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the dropdown menu.

<ParametersTable
  type="ActionBarMorePrimitiveRootProps"
  parameters={[
{
  name: "defaultOpen",
  type: "boolean",
  default: "false",
  description:
    "The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.",
},
{
  name: "open",
  type: "boolean",
  description:
    "The controlled open state of the dropdown menu. Must be used in conjunction with onOpenChange.",
},
{
  name: "onOpenChange",
  type: "(open: boolean) => void",
  description:
    "Event handler called when the open state of the dropdown menu changes.",
},
{
  name: "modal",
  type: "boolean",
  default: "true",
  description:
    "The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.",
},
{
  name: "dir",
  type: "'ltr' | 'rtl'",
  description: "The reading direction of the dropdown menu.",
},
]}
/>

Trigger \[#trigger]

A button that toggles the dropdown menu.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarMorePrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

| Data attribute    | Values                |
| ----------------- | --------------------- |
| `[data-state]`    | `"open" \| "closed"`  |
| `[data-disabled]` | Present when disabled |

Content \[#content]

The component that pops out when the dropdown menu is open.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarMorePrimitiveContentProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "side",
  type: "'top' | 'right' | 'bottom' | 'left'",
  default: "'bottom'",
  description: "The preferred side of the trigger to render against.",
},
{
  name: "sideOffset",
  type: "number",
  default: "4",
  description: "The distance in pixels from the trigger.",
},
{
  name: "align",
  type: "'start' | 'center' | 'end'",
  default: "'center'",
  description: "The preferred alignment against the trigger.",
},
{
  name: "alignOffset",
  type: "number",
  default: "0",
  description: "An offset in pixels from the align option.",
},
{
  name: "portalProps",
  type: "PortalProps",
  description: "Props to pass to the Portal component.",
},
]}
/>

| Data attribute | Values                                   |
| -------------- | ---------------------------------------- |
| `[data-state]` | `"open" \| "closed"`                     |
| `[data-side]`  | `"top" \| "right" \| "bottom" \| "left"` |
| `[data-align]` | `"start" \| "center" \| "end"`           |

Refer to Radix UI's Documentation for [DropdownMenu.Content](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#content) for more details.

Item \[#item]

A menu item within the dropdown menu.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarMorePrimitiveItemProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "disabled",
  type: "boolean",
  description: "When true, prevents the user from interacting with the item.",
},
{
  name: "onSelect",
  type: "(event: Event) => void",
  description:
    "Event handler called when the user selects an item (via mouse or keyboard). Calling event.preventDefault in this handler will prevent the dropdown menu from closing when selecting that item.",
},
{
  name: "textValue",
  type: "string",
  description:
    "Optional text used for typeahead purposes. By default the typeahead behavior will use the .textContent of the item.",
},
]}
/>

| Data attribute       | Values                   |
| -------------------- | ------------------------ |
| `[data-disabled]`    | Present when disabled    |
| `[data-highlighted]` | Present when highlighted |

Refer to Radix UI's Documentation for [DropdownMenu.Item](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#item) for more details.

Separator \[#separator]

A visual separator between groups of items.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarMorePrimitiveSeparatorProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Example Usage \[#example-usage]

Basic dropdown menu \[#basic-dropdown-menu]

```tsx
import { ActionBarMorePrimitive } from "@assistant-ui/react";
import { MoreHorizontal, Pencil, Volume2, ThumbsUp } from "lucide-react";

const MoreActionsMenu = () => (
  <ActionBarMorePrimitive.Root>
    <ActionBarMorePrimitive.Trigger className="action-button">
      <MoreHorizontal className="size-4" />
    </ActionBarMorePrimitive.Trigger>
    <ActionBarMorePrimitive.Content className="dropdown-content">
      <ActionBarMorePrimitive.Item
        className="dropdown-item"
        onSelect={() => console.log("Edit")}
      >
        <Pencil className="size-4" />
        Edit message
      </ActionBarMorePrimitive.Item>
      <ActionBarMorePrimitive.Item
        className="dropdown-item"
        onSelect={() => console.log("Speak")}
      >
        <Volume2 className="size-4" />
        Read aloud
      </ActionBarMorePrimitive.Item>
      <ActionBarMorePrimitive.Separator className="dropdown-separator" />
      <ActionBarMorePrimitive.Item
        className="dropdown-item"
        onSelect={() => console.log("Like")}
      >
        <ThumbsUp className="size-4" />
        Good response
      </ActionBarMorePrimitive.Item>
    </ActionBarMorePrimitive.Content>
  </ActionBarMorePrimitive.Root>
);
```

Using with action hooks \[#using-with-action-hooks]

You can combine the dropdown menu items with action hooks from ActionBarPrimitive:

```tsx
import {
  ActionBarPrimitive,
  ActionBarMorePrimitive,
  useAui,
  useAuiState,
} from "@assistant-ui/react";
import { useCallback } from "react";

const useEditAction = () => {
  const aui = useAui();
  const disabled = useAuiState((s) => s.composer.isEditing);
  const callback = useCallback(() => aui.composer().beginEdit(), [aui]);
  if (disabled) return null;
  return callback;
};

const useSpeakAction = () => {
  const aui = useAui();
  return useCallback(() => aui.message().speak(), [aui]);
};

const MoreActionsWithHooks = () => {
  const edit = useEditAction();
  const speak = useSpeakAction();

  return (
    <ActionBarMorePrimitive.Root>
      <ActionBarMorePrimitive.Trigger>
        <MoreHorizontalIcon />
      </ActionBarMorePrimitive.Trigger>
      <ActionBarMorePrimitive.Content>
        <ActionBarMorePrimitive.Item onSelect={edit ?? undefined} disabled={!edit}>
          Edit
        </ActionBarMorePrimitive.Item>
        <ActionBarMorePrimitive.Item onSelect={speak}>
          Read aloud
        </ActionBarMorePrimitive.Item>
      </ActionBarMorePrimitive.Content>
    </ActionBarMorePrimitive.Root>
  );
};
```


# ActionBarPrimitive
URL: /docs/api-reference/primitives/action-bar

Buttons for message actions like copy, edit, reload, speak, and feedback.

Buttons to interact with the message.

Anatomy \[#anatomy]

```tsx
import { ActionBarPrimitive } from "@assistant-ui/react";

const UserMessageBar = () => (
  <ActionBarPrimitive.Root>
    <ActionBarPrimitive.Edit />
    <ActionBarPrimitive.Copy />
  </ActionBarPrimitive.Root>
);

const AssistantMessageBar = () => (
  <ActionBarPrimitive.Root>
    <ActionBarPrimitive.Reload />
    <ActionBarPrimitive.Copy />
  </ActionBarPrimitive.Root>
);
```

API Reference \[#api-reference]

Container \[#container]

Containts all parts of the action bar.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "hideWhenRunning",
  type: "boolean",
  default: "false",
  description: (
    <span>
      Do not render the ActionBar when the thread is in running state.
    </span>
  ),
},
{
  name: "autohide",
  type: '"always" | "not-last" | "never"',
  default: '"never"',
  description: (
    <span>
      Do not render the ActionBar unless the mouse is hovering over the
      message.
      <br />
      <br />
      <Code>"always"</Code>: always autohide.
      <br />
      <Code>"not-last"</Code>; only autohide if the message is not the last
      one in the thread.
    </span>
  ),
},
{
  name: "autohideFloat",
  type: '"always" | "single-branch" | "never"',
  default: '"never"',
  description: (
    <span>
      Float the ActionBar during autohide.
      <br />
      <br />
      <Code>"always"</Code>: always float during autohide.
      <br />
      <Code>"single-branch"</Code>: only float if the message is the only
      one in the thread.
      <br />
      <br />
      Note: this only sets `data-floating` on the ActionBar. You need to set
      the appropriate styles on the ActionBar to make it float.
    </span>
  ),
},
]}
/>

| Data attribute    | Values                |
| ----------------- | --------------------- |
| `[data-floating]` | Present when floating |

Edit \[#edit]

Enables edit mode on user message.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveEditProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Reload \[#reload]

Regenerates the assistant message.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveReloadProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

{" "}

Copy \[#copy]

Copies the message to the clipboard.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveCopyProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "copiedDuration",
  type: "number",
  description:
    "The duration in milliseconds to change the message status to 'copied'.",
  default: "3000",
},
]}
/>

| Data attribute  | Values                                        |
| --------------- | --------------------------------------------- |
| `[data-copied]` | Present when the message was recently copied. |

Copied state \[#copied-state]

Show a different icon for a few seconds after the message is copied.

```tsx
<ActionBarPrimitive.Copy>
  <AuiIf condition={(s) => !s.message.isCopied}>
    <CopyIcon />
  </AuiIf>
  <AuiIf condition={(s) => s.message.isCopied}>
    <CopySuccessIcon />
  </AuiIf>
</ActionBarPrimitive.Copy>
```

or using the `data-copied` attribute:

```tsx
<ActionBarPrimitive.Copy className="group">
  <CopyIcon className="group-data-[copied]:hidden" />
  <CheckIcon className="hidden group-data-[copied]:block" />
</ActionBarPrimitive.Copy>
```

Speak \[#speak]

Plays the message text as speech.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveSpeakProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

StopSpeaking \[#stopspeaking]

Stops the message text from being played as speech.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveStopSpeakingProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Feedback Positive \[#feedback-positive]

Shows a positive feedback submission button.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveFeedbackPositiveProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

| Data attribute     | Values                                        |
| ------------------ | --------------------------------------------- |
| `[data-submitted]` | Present when positive feedback was submitted. |

Feedback Negative \[#feedback-negative]

Shows a negative feedback submission button.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveFeedbackNegativeProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

| Data attribute     | Values                                        |
| ------------------ | --------------------------------------------- |
| `[data-submitted]` | Present when negative feedback was submitted. |

ExportMarkdown \[#exportmarkdown]

Exports the message content as a Markdown file download by default, or calls a custom export handler when `onExport` is provided.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveExportMarkdownProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "filename",
  type: "string",
  description:
    "The filename for the downloaded Markdown file. Defaults to 'message-{timestamp}.md'. Ignored when onExport is provided.",
},
{
  name: "onExport",
  type: "(content: string) => void | Promise<void>",
  description:
    "Optional callback function that receives the message content. When provided, overrides the default Markdown download behavior. Use this to implement custom export logic (PDF, JSON, TXT, etc.).",
},
]}
/>

Examples \[#examples]

Default Markdown export:

```tsx
<ActionBarPrimitive.ExportMarkdown>
  <DownloadIcon />
  Export as Markdown
</ActionBarPrimitive.ExportMarkdown>
```

With custom filename:

```tsx
<ActionBarPrimitive.ExportMarkdown filename="chat-response.md">
  <DownloadIcon />
  Download
</ActionBarPrimitive.ExportMarkdown>
```

Export as PDF (with custom logic):

```tsx
<ActionBarPrimitive.ExportMarkdown
  onExport={async (content) => {
    const pdf = await generatePdf(content);
    downloadFile(pdf, "message.pdf");
  }}
>
  <FileIcon />
  Export PDF
</ActionBarPrimitive.ExportMarkdown>
```

Export as JSON:

```tsx
<ActionBarPrimitive.ExportMarkdown
  onExport={(content) => {
    const json = JSON.stringify({ content, timestamp: Date.now() });
    const blob = new Blob([json], { type: "application/json" });
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "message.json";
    a.click();
    URL.revokeObjectURL(url);
  }}
>
  <CodeIcon />
  Export JSON
</ActionBarPrimitive.ExportMarkdown>
```


# AuiIf
URL: /docs/api-reference/primitives/assistant-if

Conditional rendering component based on thread, message, or composer state.

Conditionally render children based on assistant state.

Anatomy \[#anatomy]

```tsx
import { AuiIf } from "@assistant-ui/react";

<AuiIf condition={(s) => s.thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>
```

Overview \[#overview]

`AuiIf` is a generic conditional rendering component that provides access to the full assistant state. It replaces the deprecated `ThreadPrimitive.If`, `MessagePrimitive.If`, and `ComposerPrimitive.If` components with a single, flexible API.

API Reference \[#api-reference]

<ParametersTable
  type="AuiIfProps"
  parameters={[
{
  name: "condition",
  type: "(state: AssistantState) => boolean",
  required: true,
  description: "A function that receives the assistant state and returns whether to render children.",
},
{
  name: "children",
  type: "ReactNode",
  description: "Content to render when the condition returns true.",
},
]}
/>

AssistantState \[#assistantstate]

The condition function receives an `AssistantState` object with the following properties:

<ParametersTable
  type="AssistantState"
  parameters={[
{
  name: "thread",
  type: "ThreadState",
  description: "The current thread state (always available).",
},
{
  name: "message",
  type: "MessageState",
  description: "The current message state (available within a message context).",
},
{
  name: "composer",
  type: "ComposerState",
  description: "The current composer state (always available).",
},
{
  name: "part",
  type: "PartState",
  description: "The current message part state (available within a part context).",
},
{
  name: "attachment",
  type: "AttachmentState",
  description: "The current attachment state (available within an attachment context).",
},
]}
/>

Examples \[#examples]

Thread State Conditions \[#thread-state-conditions]

```tsx
// Show welcome screen when thread is empty
<AuiIf condition={(s) => s.thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>

// Show loading indicator while running
<AuiIf condition={(s) => s.thread.isRunning}>
  <LoadingSpinner />
</AuiIf>

// Conditional send/cancel button
<AuiIf condition={(s) => !s.thread.isRunning}>
  <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
</AuiIf>
<AuiIf condition={(s) => s.thread.isRunning}>
  <ComposerPrimitive.Cancel>Cancel</ComposerPrimitive.Cancel>
</AuiIf>
```

Message State Conditions \[#message-state-conditions]

```tsx
// Show avatar only for assistant messages
<AuiIf condition={(s) => s.message.role === "assistant"}>
  <AssistantAvatar />
</AuiIf>

// Show disclaimer on last message
<AuiIf condition={(s) => s.message.isLast}>
  <Disclaimer />
</AuiIf>

// Toggle copy icon based on copied state
<ActionBarPrimitive.Copy>
  <AuiIf condition={(s) => !s.message.isCopied}>
    <CopyIcon />
  </AuiIf>
  <AuiIf condition={(s) => s.message.isCopied}>
    <CheckIcon />
  </AuiIf>
</ActionBarPrimitive.Copy>

// Show speak/stop button based on speech state
<AuiIf condition={(s) => s.message.speech == null}>
  <ActionBarPrimitive.Speak>
    <SpeakIcon />
  </ActionBarPrimitive.Speak>
</AuiIf>
<AuiIf condition={(s) => s.message.speech != null}>
  <ActionBarPrimitive.StopSpeaking>
    <StopIcon />
  </ActionBarPrimitive.StopSpeaking>
</AuiIf>
```

Composer State Conditions \[#composer-state-conditions]

```tsx
// Show placeholder when composer is empty
<AuiIf condition={(s) => s.composer.isEmpty}>
  <PlaceholderText />
</AuiIf>

// Show attachment preview when editing
<AuiIf condition={(s) => s.composer.isEditing}>
  <EditingIndicator />
</AuiIf>
```

Complex Conditions \[#complex-conditions]

```tsx
// Combine multiple conditions
<AuiIf condition={(s) =>
  !s.thread.isRunning && s.message.role === "assistant"
}>
  <ActionBar />
</AuiIf>

// Custom logic
<AuiIf condition={(s) =>
  s.thread.messages.length > 0 && !s.thread.isRunning
}>
  <FollowUpSuggestions />
</AuiIf>
```

Type Export \[#type-export]

You can import the `AuiIf.Condition` type for typing your condition functions:

```tsx
import { AuiIf } from "@assistant-ui/react";

const isThreadEmpty: AuiIf.Condition = (s) => s.thread.isEmpty;

<AuiIf condition={isThreadEmpty}>
  <WelcomeScreen />
</AuiIf>
```

Migration from Deprecated Components \[#migration-from-deprecated-components]

<Callout type="warn">
  `ThreadPrimitive.If`, `MessagePrimitive.If`, and `ComposerPrimitive.If` are deprecated. Use `AuiIf` instead.
</Callout>

| Before                                 | After                                                       |
| -------------------------------------- | ----------------------------------------------------------- |
| `<ThreadPrimitive.If empty>`           | `<AuiIf condition={(s) => s.thread.isEmpty}>`               |
| `<ThreadPrimitive.If running>`         | `<AuiIf condition={(s) => s.thread.isRunning}>`             |
| `<ThreadPrimitive.If running={false}>` | `<AuiIf condition={(s) => !s.thread.isRunning}>`            |
| `<MessagePrimitive.If user>`           | `<AuiIf condition={(s) => s.message.role === "user"}>`      |
| `<MessagePrimitive.If assistant>`      | `<AuiIf condition={(s) => s.message.role === "assistant"}>` |
| `<MessagePrimitive.If copied>`         | `<AuiIf condition={(s) => s.message.isCopied}>`             |
| `<MessagePrimitive.If speaking>`       | `<AuiIf condition={(s) => s.message.speech != null}>`       |
| `<MessagePrimitive.If last>`           | `<AuiIf condition={(s) => s.message.isLast}>`               |
| `<ComposerPrimitive.If editing>`       | `<AuiIf condition={(s) => s.composer.isEditing}>`           |


# AssistantModalPrimitive
URL: /docs/api-reference/primitives/assistant-modal

A popover chat interface for floating assistant UI in the corner of the screen.

A modal chat UI usually displayed in the bottom right corner of the screen.

Anatomy \[#anatomy]

```tsx
import { AssistantModalPrimitive } from "@assistant-ui/react";

const Thread = () => (
  <AssistantModalPrimitive.Root>
    <AssistantModalPrimitive.Trigger>
      <FloatingAssistantButton />
    </AssistantModalPrimitive.Trigger>
    <AssistantModalPrimitive.Content>
      <Thread />
    </AssistantModalPrimitive.Content>
  </AssistantModalPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the assistant modal.

<ParametersTable
  type="AssistantModalPrimitiveRootProps"
  parameters={[
{
  name: "defaultOpen",
  type: "boolean",
  default: "false",
  description:
    "The open state of the assistant modal when it is initially rendered. Use when you do not need to control its open state.",
},
{
  name: "open",
  type: "boolean",
  description:
    "Not recommended. The controlled open state of the assistant modal. Must be used in conjunction with onOpenChange.",
},
{
  name: "onOpenChange",
  type: "(open: boolean) => void",
  description:
    "Event handler called when the open state of the assistant modal changes.",
},
{
  name: "modal",
  type: "boolean",
  default: "false",
  description:
    "The modality of the assistant modal. When set to true, interaction with outside elements will be disabled and only modal content will be visible to screen readers.",
},
]}
/>

Trigger \[#trigger]

A button that toggles the open state of the assistant modal. `AssistantModalPrimitive.Content` will position itself against this button.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="AssistantModalPrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

| Data attribute | Values               |
| -------------- | -------------------- |
| `[data-state]` | `"open" \| "closed"` |

Anchor \[#anchor]

The anchor element that the assistant modal is attached to. Defaults to the `Trigger` element.

This primitive renders a `<div>` element unless `asChild` is set.

Content \[#content]

The component that pops out when the assistant modal is open.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AssistantModalPrimitiveContentProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "side",
  type: "'top' | 'right' | 'bottom' | 'left'",
  default: "'top'",
  description: "The side of the assistant modal to position against.",
},
{
  name: "align",
  type: "'start' | 'center' | 'end'",
  default: "'end'",
  description: "The alignment of the assistant modal to position against.",
},
{
  name: "dissmissOnInteractOutside",
  type: "boolean",
  default: "false",
  description:
    "Dismiss the assistant modal when the user interacts outside of it.",
},
]}
/>

Refer to Radix UI's Documentation for [Popover.Content](https://www.radix-ui.com/primitives/docs/components/popover#content) for more details.


# AttachmentPrimitive
URL: /docs/api-reference/primitives/attachment

Components for displaying and managing file attachments in messages and composer.

Buttons to interact with attachments.

<Callout>
  **Dual Use!** Attachments can appear in both messages and composers.
</Callout>

Anatomy \[#anatomy]

```tsx
import { AttachmentPrimitive } from "@assistant-ui/react";

const MyMessageAttachment = () => (
  <AttachmentPrimitive.Root>
    <AttachmentPrimitive.Thumbnail />
    <AttachmentPrimitive.Name />
  </AttachmentPrimitive.Root>
);

const MyComposerAttachment = () => (
  <AttachmentPrimitive.Root>
    <AttachmentPrimitive.Thumbnail />
    <AttachmentPrimitive.Name />
    <AttachmentPrimitive.Remove />
  </AttachmentPrimitive.Root>
);
```

API Reference \[#api-reference]

Container \[#container]

Containts all parts of the attachment.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Thumbnail \[#thumbnail]

The thumbnail of the attachment.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveThumbnailProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Name \[#name]

The name of the attachment.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveNameProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Remove \[#remove]

Removes the attachment.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveRemoveProps"
  parameters={[
{
  name: "asChild",
},
]}
/>


# BranchPickerPrimitive
URL: /docs/api-reference/primitives/branch-picker

Navigate between conversation branches with previous/next controls.

View and switch between branches.

Anatomy \[#anatomy]

```tsx
import { BranchPickerPrimitive } from "@assistant-ui/react";

const BranchPicker = () => (
  <BranchPickerPrimitive.Root>
    <BranchPickerPrimitive.Previous />
    <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
    <BranchPickerPrimitive.Next />
  </BranchPickerPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Containts all parts of the branch picker.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="BranchPickerPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "hideWhenSingleBranch",
  type: "boolean",
  default: "false",
  description:
    "Do not render the BranchPicker when there is only one branch at the current message.",
},
]}
/>

Number \[#number]

The current branch number.

This primitive renders the raw number as a string.

Count \[#count]

The total number of branches.

This primitive renders the raw number as a string.

Previous \[#previous]

Navigates to the previous branch.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="BranchPickerPrimitivePreviousProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Next \[#next]

Navigates to the next branch.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="BranchPickerPrimitiveNextProps"
  parameters={[
{
  name: "asChild",
},
]}
/>


# ComposerPrimitive
URL: /docs/api-reference/primitives/composer

Primitives for the text input, send button, and attachments.

The user interface to add new messages or edit existing ones.

<Callout>
  **Dual Use!** A Composer placed directly inside a `Thread` will compose new
  messages. A Composer placed inside a `Message` will edit that message.
</Callout>

Anatomy \[#anatomy]

```tsx
import { ComposerPrimitive } from "@assistant-ui/react";

// creating a new message
const Composer = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.Quote>
      <ComposerPrimitive.QuoteText />
      <ComposerPrimitive.QuoteDismiss />
    </ComposerPrimitive.Quote>
    <ComposerPrimitive.Attachments />
    <ComposerPrimitive.AddAttachment />
    <ComposerPrimitive.Input />
    <ComposerPrimitive.Send />
  </ComposerPrimitive.Root>
);

// editing an existing message
const EditComposer = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.Input />
    <ComposerPrimitive.Send />
    <ComposerPrimitive.Cancel />
  </ComposerPrimitive.Root>
);

// with voice input (dictation)
const ComposerWithDictation = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.Input />
    <ComposerPrimitive.If dictation={false}>
      <ComposerPrimitive.Dictate />
    </ComposerPrimitive.If>
    <ComposerPrimitive.If dictation>
      <ComposerPrimitive.StopDictation />
    </ComposerPrimitive.If>
    <ComposerPrimitive.Send />
  </ComposerPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Containts all parts of the composer.

This primitive renders a `<form>` element unless `asChild` is set.

<ParametersTable
  type="ComposerRootProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Input \[#input]

The text input field for the user to type a new message.

This primitive renders a `<textarea>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveInputProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "submitMode",
  type: '"enter" | "ctrlEnter" | "none"',
  default: '"enter"',
  description:
    'Controls how the Enter key submits messages. "enter": plain Enter submits (Shift+Enter for newline). "ctrlEnter": Ctrl/Cmd+Enter submits (plain Enter for newline). "none": keyboard submission disabled.',
},
]}
/>

Keyboard Shortcuts \[#keyboard-shortcuts]

Default (`submitMode="enter"`):

| Key                      | Description            |
| ------------------------ | ---------------------- |
| <Kbd>Enter</Kbd>         | Sends the message.     |
| <Kbd>Shift + Enter</Kbd> | Inserts a newline.     |
| <Kbd>Escape</Kbd>        | Sends a cancel action. |

With `submitMode="ctrlEnter"`:

| Key                         | Description            |
| --------------------------- | ---------------------- |
| <Kbd>Ctrl/Cmd + Enter</Kbd> | Sends the message.     |
| <Kbd>Enter</Kbd>            | Inserts a newline.     |
| <Kbd>Escape</Kbd>           | Sends a cancel action. |

Send \[#send]

The button to send the message.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveSendProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "multiple",
  type: "boolean | undefined",
  description: "Allow selecting multiple attachments at the same time.",
  default: "true",
},
]}
/>

Cancel \[#cancel]

Sends a cancel action.

In edit composers, this action exits the edit mode.
In thread composers, this action stops the current run.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveCancelProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Attachments \[#attachments]

Renders attachments. This primitive renders a separate component for each attachment.

<ParametersTable
  type="ComposerPrimitiveAttachmentsProps"
  parameters={[
{
  name: "components",
  type: "ComposerAttachmentsComponents",
  description: "The component to render for each attachment.",
  children: [
    {
      type: "ComposerPrimitiveAttachmentsProps['components']",
      parameters: [
        {
          name: "Image",
          type: "ComponentType",
          description: "The component to render for each image attachment.",
        },
        {
          name: "Document",
          type: "ComponentType",
          description:
            "The component to render for each document attachment.",
        },
        {
          name: "File",
          type: "ComponentType",
          description: "The component to render for each file attachment.",
        },
        {
          name: "Fallback",
          type: "ComponentType",
          description: "The component to render for each attachment type.",
        },
      ],
    },
  ],
},
]}
/>

AttachmentByIndex \[#attachmentbyindex]

Renders a single attachment at the specified index within the composer.

```tsx
<ComposerPrimitive.AttachmentByIndex
  index={0}
  components={{
    Image: MyImageAttachment,
    Document: MyDocumentAttachment
  }}
/>
```

<ParametersTable
  type="ComposerPrimitive.AttachmentByIndex.Props"
  parameters={[
{
  name: "index",
  type: "number",
  required: true,
  description: "The index of the attachment to render.",
},
{
  name: "components",
  type: "ComposerAttachmentsComponents",
  description: "The components to render for the attachment.",
},
]}
/>

AddAttachment \[#addattachment]

Renders a button to add an attachment.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveAddAttachmentProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Dictate \[#dictate]

Renders a button to start dictation to convert voice to text.

Requires a `DictationAdapter` to be configured in the runtime.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveDictateProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

StopDictation \[#stopdictation]

Renders a button to stop the current dictation session.

Only rendered when dictation is active.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveStopDictationProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

DictationTranscript \[#dictationtranscript]

Renders the current interim (partial) transcript while dictation is active.

<Callout type="info">
  **Note:** By default, interim transcripts are displayed directly in the composer input (like native dictation).
  This component is for **advanced customization** when you want to display the interim transcript separately (e.g., in a different style or location).
</Callout>

Only renders when there is an active interim transcript (returns `null` otherwise).

This primitive renders a `<span>` element.

```tsx
{/* Optional: Display interim transcript separately with custom styling */}
<ComposerPrimitive.If dictation>
  <div className="dictation-preview">
    <ComposerPrimitive.DictationTranscript className="italic text-muted" />
  </div>
</ComposerPrimitive.If>
```

Quote \[#quote]

A container for displaying a quote preview in the composer. Only renders when a quote is set via `composer.setQuote()`.

This primitive renders a `<div>` element.

```tsx
<ComposerPrimitive.Quote className="flex items-start gap-2 bg-muted/60 px-3 py-2">
  <ComposerPrimitive.QuoteText className="line-clamp-2 flex-1 text-sm" />
  <ComposerPrimitive.QuoteDismiss>×</ComposerPrimitive.QuoteDismiss>
</ComposerPrimitive.Quote>
```

QuoteText \[#quotetext]

Renders the quoted text content. Only renders when a quote is set.

This primitive renders a `<span>` element.

QuoteDismiss \[#quotedismiss]

A button that clears the current quote from the composer by calling `setQuote(undefined)`.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveQuoteDismissProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

<Callout type="info">
  See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough including the floating selection toolbar and backend handling.
</Callout>

If \[#if]

Renders children if a condition is met.

<ParametersTable
  type="UseComposerIfProps"
  parameters={[
{
  name: "editing",
  required: false,
  type: "boolean | undefined",
  description: "Render children if the message is being edited.",
},
{
  name: "dictation",
  required: false,
  type: "boolean | undefined",
  description: "Render children if dictation is active.",
},
]}
/>

```tsx
<Composer.If editing>{/* rendered if message is being edited */}</Composer.If>

<Composer.If dictation>{/* rendered if dictation is active */}</Composer.If>
```


# Composition
URL: /docs/api-reference/primitives/composition

How to compose primitives with custom components using asChild.

`assistant-ui` primitives are composable. This means that all props are forwarded, classes are merged, and event handlers are chained.

Most primitives come with a default HTML element (usually `div` or `button`). If you already have a custom component, you can use the `asChild` prop to replace it:

```tsx
// use the primitive's <button> element
<Composer.Send>Send</Composer.Send>;

// use your own <Button> component
<Composer.Send asChild>
  <Button>Send</Button>
</Composer.Send>;
```

Learn more on [Radix's composition guide](https://www.radix-ui.com/primitives/docs/guides/composition).


# ErrorPrimitive
URL: /docs/api-reference/primitives/error

Components for displaying error messages in the chat interface.

A component for displaying error messages in the UI.

Anatomy \[#anatomy]

```tsx
import { ErrorPrimitive } from "@assistant-ui/react";

const ErrorDisplay = () => (
  <ErrorPrimitive.Root>
    <ErrorPrimitive.Message />
  </ErrorPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the error display. Renders a `<div>` element with `role="alert"`.

<ParametersTable
  type="ErrorPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
  type: "boolean",
  description:
    "Change the component to the HTML tag or custom component of the only child.",
},
]}
/>

Message \[#message]

Displays the error message. By default, it shows the error from the message context if available, or you can provide custom content.

<ParametersTable
  type="ErrorPrimitiveMessageProps"
  parameters={[
{
  name: "children",
  type: "ReactNode",
  description:
    "Optional custom content to display instead of the default error message.",
},
]}
/>

Usage \[#usage]

The ErrorPrimitive is typically used within a MessagePrimitive.Error component to display error states in messages:

```tsx
import { MessagePrimitive, ErrorPrimitive } from "@assistant-ui/react";

const MessageWithError = () => (
  <MessagePrimitive.Root>
    <MessagePrimitive.Parts />
    <MessagePrimitive.Error>
      <ErrorPrimitive.Root>
        <ErrorPrimitive.Message />
      </ErrorPrimitive.Root>
    </MessagePrimitive.Error>
  </MessagePrimitive.Root>
);
```


# MessagePartPrimitive
URL: /docs/api-reference/primitives/message-part

Primitives for text, images, tool calls, and other message content.

import {
  MessagePartRuntime,
  TextMessagePartState,
  AudioMessagePartState,
  ToolCallMessagePartState,
} from "@/generated/typeDocs";

Each message can have any number of message parts.
Message parts are usually one of text, reasoning, audio, tool-call, or data.

Message part Types \[#message-part-types]

Text \[#text]

Standard text content, used for both user and assistant messages.

Reasoning \[#reasoning]

Exposes the assistant's reasoning process, showing how it arrived at its responses. This is typically used only in assistant messages.

Audio \[#audio]

Audio content that can be played back.

Tool Call \[#tool-call]

Interactive elements that represent tool operations.

Data \[#data]

Custom data events that can be rendered as UI at their position in the message stream. Each data part has a `name` and a `data` payload.

You can use either the explicit format `{ type: "data", name: "workflow", data: {...} }` or the shorthand `data-*` prefixed format `{ type: "data-workflow", data: {...} }`. The prefixed format is automatically converted to a `DataMessagePart` (stripping the `data-` prefix as the `name`). Unknown message part types that don't match any built-in type are silently skipped with a console warning.

Anatomy \[#anatomy]

```tsx
import { MessagePartPrimitive } from "@assistant-ui/react";

const TextMessagePart = () => {
  return <MessagePartPrimitive.Text />;
};
```

Primitives \[#primitives]

Plain Text \[#plain-text]

```tsx
import { MessagePartPrimitive } from "@assistant-ui/react";

<MessagePartPrimitive.Text />;
```

Markdown Text \[#markdown-text]

Renders the message's text as Markdown.

```tsx
import { MarkdownTextPrimitive } from "@assistant-ui/react-markdown";

<MarkdownTextPrimitive />;
```

Audio \[#audio-1]

Coming soon.

InProgress \[#inprogress]

Renders children only if the message part is in progress.

```tsx
import { MessagePartPrimitive } from "@assistant-ui/react";

<MessagePartPrimitive.InProgress>
  <LoadingIndicator />
</MessagePartPrimitive.InProgress>;
```

Tool UI \[#tool-ui]

You can map tool calls to UI components. We provide a few utility functions to make this easier, such as `makeAssistantToolUI`.

```tsx
const MyWeatherToolUI = makeAssistantToolUI({
  toolName: "get_weather",
  render: function MyWeatherToolUI({ args, result }) {
    return (
      <div className="mb-4 flex flex-col items-center">
        <pre className="whitespace-pre-wrap break-all text-center">
          get_weather({JSON.stringify(args)})
        </pre>
        {"result" in result && (
          <pre className="whitespace-pre-wrap break-all text-center">
            {JSON.stringify(result.result)}
          </pre>
        )}
      </div>
    );
  },
});
```

Data UI \[#data-ui]

You can map data events to UI components, similar to tool UIs. There are two approaches:

Inline configuration \[#inline-configuration]

Pass a `data` config to `MessagePrimitive.Parts`:

```tsx
<MessagePrimitive.Parts
  components={{
    data: {
      by_name: {
        my_chart: ({ name, data }) => <ChartComponent data={data} />,
      },
      Fallback: ({ name, data }) => (
        <pre>{JSON.stringify(data, null, 2)}</pre>
      ),
    },
  }}
/>
```

Global registration \[#global-registration]

Use `makeAssistantDataUI` or `useAssistantDataUI` to register data UIs globally. Global registrations take priority over inline configuration.

```tsx
import { makeAssistantDataUI } from "@assistant-ui/react";

const MyChartUI = makeAssistantDataUI({
  name: "my_chart",
  render: ({ name, data }) => <ChartComponent data={data} />,
});

// Place inside AssistantRuntimeProvider
function App() {
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
      <MyChartUI />
    </AssistantRuntimeProvider>
  );
}
```

The hook variant allows access to component state:

```tsx
import { useAssistantDataUI } from "@assistant-ui/react";

function MyComponent() {
  useAssistantDataUI({
    name: "my_chart",
    render: ({ name, data }) => <ChartComponent data={data} />,
  });
  return null;
}
```

Each data component receives the full data part as props: `{ type: "data", name: string, data: T, status: MessagePartStatus }`.

Context Provider \[#context-provider]

Message part context is provided by `MessagePrimitive.Parts` or `TextMessagePartProvider`

MessagePrimitive.Parts \[#messageprimitiveparts]

```tsx
import { MessagePrimitive } from "@assistant-ui/react";

<MessagePrimitive.Parts
  components={{
    Text: MyText,
    Reasoning: MyReasoning,
    Audio: MyAudio,
    tools: {
      by_name: {
        get_weather: MyWeatherToolUI,
      },
      Fallback: MyFallbackToolUI,
    },
    data: {
      by_name: {
        my_chart: MyChartComponent,
      },
      Fallback: GenericDataComponent,
    },
  }}
/>;
```

TextMessagePartProvider \[#textmessagepartprovider]

This is a helper context provider to allow you to reuse the message part components outside a message message part.

```tsx
import { TextMessagePartProvider } from "@assistant-ui/react";

<TextMessagePartProvider text="Hello world" isRunning={false}>
  <MessagePart.Text />
</TextMessagePartProvider>;
```

Runtime API \[#runtime-api]

useMessagePartRuntime \[#usemessagepartruntime]

```tsx
import { useMessagePartRuntime } from "@assistant-ui/react";

const MessagePartRuntime = useMessagePartRuntime();
```

<ParametersTable {...MessagePartRuntime} />

useMessagePart \[#usemessagepart]

```tsx
import { useMessagePart } from "@assistant-ui/react";

const MessagePart = useMessagePart();
```

<ParametersTable {...TextMessagePartState} />

<ParametersTable {...AudioMessagePartState} />

<ParametersTable {...ToolCallMessagePartState} />

useMessagePartText \[#usemessageparttext]

```tsx
import { useMessagePartText } from "@assistant-ui/react";

const MessagePartText = useMessagePartText();
```

<ParametersTable {...TextMessagePartState} />


# MessagePrimitive
URL: /docs/api-reference/primitives/message

Components for rendering message content, parts, and attachments.

A single message in a conversation. Messages may consist of multiple parts.

Anatomy \[#anatomy]

```tsx
import { MessagePrimitive } from "@assistant-ui/react";

const UserMessage = () => (
  <MessagePrimitive.Root>
    User: <MessagePrimitive.Parts />
    <BranchPicker />
    <ActionBar />
  </MessagePrimitive.Root>
);

const AssistantMessage = () => (
  <MessagePrimitive.Root>
    Assistant: <MessagePrimitive.Parts />
    <BranchPicker />
    <ActionBar />
  </MessagePrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Containts all parts of the message.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="MessagePrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Parts \[#parts]

The content of the message. This renders a separate component for each content part of the message.

<ParametersTable
  type="MessagePrimitiveContentProps"
  parameters={[
{
  name: "components",
  required: false,
  type: "ContentPartComponents",
  description: "The components to render for each content part.",
  children: [
    {
      type: "ContentPartComponents",
      parameters: [
        {
          name: "Text",
          type: "TextContentPartComponent",
          description:
            "The component to render for each text content part.",
        },
        {
          name: "Image",
          type: "ImageContentPartComponent",
          description:
            "The component to render for each image content part.",
        },
        {
          name: "Source",
          type: "SourceContentPartComponent",
          description:
            "The component to render for each source content part.",
        },
        {
          name: "File",
          type: "FileContentPartComponent",
          description:
            "The component to render for each file content part.",
        },
        {
          name: "Unstable_Audio",
          type: "Unstable_AudioContentPartComponent",
          description:
            "The component to render for each audio content part.",
        },
        {
          name: "tools",
          type: "object",
          description:
            "The component to render for each tool call content part.",
          children: [
            {
              parameters: [
                {
                  name: "by_name",
                  type: "Record<string, ToolCallContentPartComponent>",
                  description:
                    "The components to render for each tool call content part.",
                },
                {
                  name: "Fallback",
                  type: "ToolCallContentPartComponent",
                  description:
                    "The fallback component to render for tool call content parts.",
                },
              ],
            },
          ],
        },
        {
          name: "ToolGroup",
          type: "ComponentType<PropsWithChildren<{ startIndex: number; endIndex: number }>>",
          description:
            "Component for rendering grouped consecutive tool calls. When provided, consecutive tool-call content parts will be automatically grouped and wrapped with this component.",
          children: [
            {
              type: "ToolGroupProps",
              parameters: [
                {
                  name: "startIndex",
                  type: "number",
                  description: "Index of the first tool call in the group.",
                  required: true,
                },
                {
                  name: "endIndex",
                  type: "number",
                  description: "Index of the last tool call in the group.",
                  required: true,
                },
                {
                  name: "children",
                  type: "ReactNode",
                  description:
                    "The rendered tool call components within the group.",
                  required: true,
                },
              ],
            },
          ],
        },
      ],
    },
  ],
},
]}
/>

PartByIndex \[#partbyindex]

Renders a single message part at the specified index.

```tsx
<MessagePrimitive.PartByIndex
  index={0}
  components={{
    Text: MyTextComponent,
    Image: MyImageComponent
  }}
/>
```

<ParametersTable
  type="MessagePrimitive.PartByIndex.Props"
  parameters={[
{
  name: "index",
  type: "number",
  required: true,
  description: "The index of the message part to render.",
},
{
  name: "components",
  required: false,
  type: "ContentPartComponents",
  description: "The components to render for the message part.",
},
]}
/>

Attachments \[#attachments]

Renders all attachments of the message.

<ParametersTable
  type="MessagePrimitive.Attachments.Props"
  parameters={[
{
  name: "components",
  type: "AttachmentComponents",
  description: "The components to render for each attachment.",
  children: [
    {
      type: "AttachmentComponents",
      parameters: [
        {
          name: "Image",
          type: "ComponentType",
          description: "The component to render for image attachments.",
        },
        {
          name: "Document",
          type: "ComponentType",
          description: "The component to render for document attachments.",
        },
        {
          name: "File",
          type: "ComponentType",
          description: "The component to render for file attachments.",
        },
        {
          name: "Attachment",
          type: "ComponentType",
          description: "The fallback component to render for any attachment type.",
        },
      ],
    },
  ],
},
]}
/>

AttachmentByIndex \[#attachmentbyindex]

Renders a single attachment at the specified index within the message.

```tsx
<MessagePrimitive.AttachmentByIndex
  index={0}
  components={{
    Image: MyImageAttachment,
    Document: MyDocumentAttachment
  }}
/>
```

<ParametersTable
  type="MessagePrimitive.AttachmentByIndex.Props"
  parameters={[
{
  name: "index",
  type: "number",
  required: true,
  description: "The index of the attachment to render.",
},
{
  name: "components",
  type: "AttachmentComponents",
  description: "The components to render for the attachment.",
},
]}
/>

useMessageQuote() \[#usemessagequote]

A hook that returns the quote info attached to the current message, if any. Reads from `message.metadata.custom.quote`.

```tsx
import { useMessageQuote } from "@assistant-ui/react";

const QuoteBlock = () => {
  const quote = useMessageQuote();
  if (!quote) return null;

  return (
    <div className="mb-2 flex items-start gap-1.5 text-sm italic text-muted-foreground">
      {quote.text}
    </div>
  );
};
```

**Returns:** `QuoteInfo | undefined`

```typescript
type QuoteInfo = {
  readonly text: string;       // the quoted plain text
  readonly messageId: string;  // the source message ID
};
```

<Callout type="info">
  See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough.
</Callout>

Error \[#error]

Renders children only if the message has an error status.

```tsx
<MessagePrimitive.Error>
  {/* rendered if the message has an error status */}
  <ErrorPrimitive.Root>
    <ErrorPrimitive.Message />
  </ErrorPrimitive.Root>
</MessagePrimitive.Error>
```


# SelectionToolbarPrimitive
URL: /docs/api-reference/primitives/selection-toolbar

A floating toolbar that appears when text is selected within a message.

A floating toolbar that appears near the user's text selection within a message. Used to provide contextual actions like quoting selected text.

Anatomy \[#anatomy]

```tsx
import { SelectionToolbarPrimitive } from "@assistant-ui/react";

const FloatingSelectionToolbar = () => (
  <SelectionToolbarPrimitive.Root>
    <SelectionToolbarPrimitive.Quote>Quote</SelectionToolbarPrimitive.Quote>
  </SelectionToolbarPrimitive.Root>
);
```

Place this component inside `ThreadPrimitive.Root`:

```tsx
<ThreadPrimitive.Root>
  <ThreadPrimitive.Viewport>...</ThreadPrimitive.Viewport>
  <FloatingSelectionToolbar />
</ThreadPrimitive.Root>
```

API Reference \[#api-reference]

Root \[#root]

A floating container that renders as a portal positioned above the text selection. Only renders when there is a valid text selection within a single message.

This primitive renders a `<div>` element.

**Behavior:**

* Listens for `mouseup` and `keyup` events to detect completed selections
* Validates the selection is within a single message using `data-message-id` attributes
* Renders a portal with `position: fixed`, centered above the selection
* Prevents `mousedown` from clearing the text selection when clicking the toolbar
* Hides automatically on scroll or when the selection is cleared
* Cross-message selections are ignored

Quote \[#quote]

A button that captures the currently selected text and sets it as a quote in the thread composer.

This primitive renders a `<button>` element.

**Behavior:**

* Reads selection info from the Root context (not `window.getSelection()`)
* Calls `composer.setQuote({ text, messageId })` on the thread composer
* Clears the text selection after quoting
* Disabled when no selection info is available

<Callout type="info">
  See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough including composer preview, sent message display, and backend handling.
</Callout>


# SuggestionPrimitive
URL: /docs/api-reference/primitives/suggestion

Primitives for rendering individual suggestions. These primitives must be used within a suggestion context provided by `ThreadPrimitive.Suggestions`.

Quick Reference \[#quick-reference]

```tsx
import { SuggestionPrimitive } from "@assistant-ui/react";

<SuggestionPrimitive.Title />
<SuggestionPrimitive.Description />
<SuggestionPrimitive.Trigger />
```

API Reference \[#api-reference]

SuggestionPrimitive.Title \[#suggestionprimitivetitle]

Displays the suggestion's title.

```tsx
import { SuggestionPrimitive } from "@assistant-ui/react";

const SuggestionCard = () => {
  return (
    <div>
      <h3>
        <SuggestionPrimitive.Title />
      </h3>
    </div>
  );
};
```

This primitive renders a `<span>` element.

SuggestionPrimitive.Description \[#suggestionprimitivedescription]

Displays the suggestion's description/label. This is only shown when suggestions are configured using the object format with separate title and label.

```tsx
import { SuggestionPrimitive } from "@assistant-ui/react";

const SuggestionCard = () => {
  return (
    <div>
      <p className="text-muted-foreground">
        <SuggestionPrimitive.Description />
      </p>
    </div>
  );
};
```

This primitive renders a `<span>` element.

SuggestionPrimitive.Trigger \[#suggestionprimitivetrigger]

A button that triggers the suggestion action when clicked. When clicked, it either sends the message immediately or populates the composer with the suggestion's prompt.

```tsx
import { SuggestionPrimitive } from "@assistant-ui/react";

const SuggestionButton = () => {
  return (
    <SuggestionPrimitive.Trigger send asChild>
      <button>
        <SuggestionPrimitive.Title />
      </button>
    </SuggestionPrimitive.Trigger>
  );
};
```

<ParametersTable
  type="SuggestionPrimitiveTriggerProps"
  parameters={[
{
  name: "send",
  type: "boolean",
  description:
    "When true, automatically sends the message. When false, only populates the composer with the suggestion's prompt.",
},
{
  name: "clearComposer",
  type: "boolean",
  default: "true",
  description:
    "When send is false, determines whether to clear the composer before adding the suggestion (true) or append to existing text (false).",
},
{
  name: "asChild",
  type: "boolean",
  default: "false",
  description: "Merge props with child element instead of rendering a wrapper button.",
},
{
  name: "className",
  type: "string",
  description: "CSS class name.",
},
]}
/>

This primitive renders a `<button>` element unless `asChild` is set.

Usage Example \[#usage-example]

```tsx
import {
  ThreadPrimitive,
  SuggestionPrimitive,
} from "@assistant-ui/react";

const ThreadWelcome = () => {
  return (
    <div>
      <h1>How can I help you?</h1>
      <div className="grid grid-cols-2 gap-2">
        <ThreadPrimitive.Suggestions
          components={{
            Suggestion: SuggestionCard,
          }}
        />
      </div>
    </div>
  );
};

const SuggestionCard = () => {
  return (
    <SuggestionPrimitive.Trigger send asChild>
      <button className="flex flex-col gap-1 rounded-lg border p-3 hover:bg-muted">
        <span className="font-medium">
          <SuggestionPrimitive.Title />
        </span>
        <span className="text-muted-foreground text-sm">
          <SuggestionPrimitive.Description />
        </span>
      </button>
    </SuggestionPrimitive.Trigger>
  );
};
```

See Also \[#see-also]

* [Suggestions Guide](/docs/guides/suggestions) - Configure and customize suggestions
* [ThreadPrimitive.Suggestions](/docs/reference/api-reference/primitives/thread#threadprimitive-suggestions) - Render all suggestions


# ThreadListItemMorePrimitive
URL: /docs/api-reference/primitives/thread-list-item-more

Dropdown menu for additional thread actions like archive and delete.

A dropdown menu for displaying additional actions on a thread list item. Built on top of [Radix UI Dropdown Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu).

Anatomy \[#anatomy]

```tsx
import {
  ThreadListItemPrimitive,
  ThreadListItemMorePrimitive
} from "@assistant-ui/react";

const ThreadListItemMore = () => (
  <ThreadListItemMorePrimitive.Root>
    <ThreadListItemMorePrimitive.Trigger>
      More options
    </ThreadListItemMorePrimitive.Trigger>
    <ThreadListItemMorePrimitive.Content>
      <ThreadListItemPrimitive.Archive asChild>
        <ThreadListItemMorePrimitive.Item>
          Archive
        </ThreadListItemMorePrimitive.Item>
      </ThreadListItemPrimitive.Archive>
      <ThreadListItemMorePrimitive.Separator />
      <ThreadListItemPrimitive.Delete asChild>
        <ThreadListItemMorePrimitive.Item>
          Delete
        </ThreadListItemMorePrimitive.Item>
      </ThreadListItemPrimitive.Delete>
    </ThreadListItemMorePrimitive.Content>
  </ThreadListItemMorePrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the dropdown menu. Wraps Radix UI's `DropdownMenu.Root`.

<ParametersTable
  type="ThreadListItemMorePrimitiveRootProps"
  parameters={[
{
  name: "open",
  type: "boolean",
  description: "The controlled open state of the dropdown menu.",
},
{
  name: "defaultOpen",
  type: "boolean",
  description: "The open state of the dropdown menu when it is initially rendered.",
},
{
  name: "onOpenChange",
  type: "(open: boolean) => void",
  description: "Event handler called when the open state changes.",
},
{
  name: "modal",
  type: "boolean",
  default: "true",
  description: "Whether the dropdown menu should be modal.",
},
]}
/>

Trigger \[#trigger]

The button that toggles the dropdown menu. Wraps Radix UI's `DropdownMenu.Trigger`.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemMorePrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Content \[#content]

The container for the dropdown menu items. Wraps Radix UI's `DropdownMenu.Portal` and `DropdownMenu.Content`.

<ParametersTable
  type="ThreadListItemMorePrimitiveContentProps"
  parameters={[
{
  name: "side",
  type: '"top" | "right" | "bottom" | "left"',
  default: '"bottom"',
  description: "The preferred side of the trigger to render against.",
},
{
  name: "sideOffset",
  type: "number",
  default: "4",
  description: "The distance in pixels from the trigger.",
},
{
  name: "align",
  type: '"start" | "center" | "end"',
  default: '"center"',
  description: "The preferred alignment against the trigger.",
},
{
  name: "alignOffset",
  type: "number",
  default: "0",
  description: "An offset in pixels from the align option.",
},
{
  name: "portalProps",
  type: "PortalProps",
  description: "Props to pass to the Portal component.",
},
]}
/>

Item \[#item]

A menu item within the dropdown. Wraps Radix UI's `DropdownMenu.Item`.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemMorePrimitiveItemProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "disabled",
  type: "boolean",
  description: "Whether the item is disabled.",
},
{
  name: "onSelect",
  type: "(event: Event) => void",
  description: "Event handler called when the user selects an item.",
},
]}
/>

Separator \[#separator]

A visual separator between menu items. Wraps Radix UI's `DropdownMenu.Separator`.

<ParametersTable
  type="ThreadListItemMorePrimitiveSeparatorProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Examples \[#examples]

With Icons \[#with-icons]

```tsx
import { ArchiveIcon, TrashIcon, MoreHorizontalIcon } from "lucide-react";

const ThreadListItemMore = () => (
  <ThreadListItemMorePrimitive.Root>
    <ThreadListItemMorePrimitive.Trigger asChild>
      <button className="icon-button">
        <MoreHorizontalIcon />
      </button>
    </ThreadListItemMorePrimitive.Trigger>
    <ThreadListItemMorePrimitive.Content
      side="bottom"
      align="start"
      className="dropdown-content"
    >
      <ThreadListItemPrimitive.Archive asChild>
        <ThreadListItemMorePrimitive.Item className="dropdown-item">
          <ArchiveIcon className="icon" />
          Archive
        </ThreadListItemMorePrimitive.Item>
      </ThreadListItemPrimitive.Archive>
    </ThreadListItemMorePrimitive.Content>
  </ThreadListItemMorePrimitive.Root>
);
```

Complete Thread List Item with More Menu \[#complete-thread-list-item-with-more-menu]

```tsx
const ThreadListItem = () => (
  <ThreadListItemPrimitive.Root className="thread-item">
    <ThreadListItemPrimitive.Trigger className="thread-trigger">
      <ThreadListItemPrimitive.Title fallback="New Chat" />
    </ThreadListItemPrimitive.Trigger>

    <ThreadListItemMorePrimitive.Root>
      <ThreadListItemMorePrimitive.Trigger asChild>
        <button className="more-button">
          <MoreHorizontalIcon />
        </button>
      </ThreadListItemMorePrimitive.Trigger>
      <ThreadListItemMorePrimitive.Content>
        <ThreadListItemPrimitive.Archive asChild>
          <ThreadListItemMorePrimitive.Item>
            <ArchiveIcon />
            Archive
          </ThreadListItemMorePrimitive.Item>
        </ThreadListItemPrimitive.Archive>
      </ThreadListItemMorePrimitive.Content>
    </ThreadListItemMorePrimitive.Root>
  </ThreadListItemPrimitive.Root>
);
```


# ThreadListItemPrimitive
URL: /docs/api-reference/primitives/thread-list-item

Individual thread item with title, archive, and delete controls.

A single thread item within a thread list.

Anatomy \[#anatomy]

```tsx
import { ThreadListItemPrimitive } from "@assistant-ui/react";

const ThreadListItem = () => (
  <ThreadListItemPrimitive.Root>
    <ThreadListItemPrimitive.Trigger>
      <ThreadListItemPrimitive.Title />
    </ThreadListItemPrimitive.Trigger>
    <ThreadListItemPrimitive.Archive />
    <ThreadListItemPrimitive.Unarchive />
    <ThreadListItemPrimitive.Delete />
  </ThreadListItemPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the thread list item.

This primitive renders a `<div>` element unless `asChild` is set. It automatically adds `data-active="true"` and `aria-current="true"` attributes when the thread is the currently active thread.

<ParametersTable
  type="ThreadListItemPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Trigger \[#trigger]

A button that switches to the thread when clicked.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemPrimitiveTriggerProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Title \[#title]

Displays the title of the thread.

This primitive renders a `<span>` element unless `asChild` is set. The title is automatically derived from the first user message in the thread.

<ParametersTable
  type="ThreadListItemPrimitiveTitleProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Archive \[#archive]

A button to archive the thread. Only shown for non-archived threads.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemPrimitiveArchiveProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Unarchive \[#unarchive]

A button to unarchive the thread. Only shown for archived threads.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemPrimitiveUnarchiveProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Delete \[#delete]

A button to permanently delete the thread.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemPrimitiveDeleteProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Examples \[#examples]

Basic Thread List Item \[#basic-thread-list-item]

```tsx
const MyThreadListItem = () => {
  return (
    <ThreadListItemPrimitive.Root className="thread-item">
      <ThreadListItemPrimitive.Trigger className="thread-trigger">
        <ThreadListItemPrimitive.Title />
      </ThreadListItemPrimitive.Trigger>
      <div className="thread-actions">
        <ThreadListItemPrimitive.Archive>
          Archive
        </ThreadListItemPrimitive.Archive>
        <ThreadListItemPrimitive.Delete>
          Delete
        </ThreadListItemPrimitive.Delete>
      </div>
    </ThreadListItemPrimitive.Root>
  );
};
```

Archived Thread List Item \[#archived-thread-list-item]

```tsx
const ArchivedThreadListItem = () => {
  return (
    <ThreadListItemPrimitive.Root className="archived-thread-item">
      <ThreadListItemPrimitive.Trigger>
        <ThreadListItemPrimitive.Title />
      </ThreadListItemPrimitive.Trigger>
      <ThreadListItemPrimitive.Unarchive>
        Restore
      </ThreadListItemPrimitive.Unarchive>
      <ThreadListItemPrimitive.Delete>
        Delete Permanently
      </ThreadListItemPrimitive.Delete>
    </ThreadListItemPrimitive.Root>
  );
};
```


# ThreadListPrimitive
URL: /docs/api-reference/primitives/thread-list

Display and manage multiple conversation threads with create and archive actions.

Displays a list of conversation threads.

Anatomy \[#anatomy]

```tsx
import { ThreadListPrimitive } from "@assistant-ui/react";

const ThreadList = () => (
  <ThreadListPrimitive.Root>
    <ThreadListPrimitive.New />
    <ThreadListPrimitive.Items
      components={{
        ThreadListItem: MyThreadListItem
      }}
    />
  </ThreadListPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the thread list.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

New \[#new]

A button to create a new thread.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListPrimitiveNewProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Items \[#items]

Renders all items in the thread list.

<ParametersTable
  type="ThreadListPrimitive.Items.Props"
  parameters={[
{
  name: "archived",
  type: "boolean",
  default: "false",
  description: "Whether to show archived threads instead of active threads.",
},
{
  name: "components",
  type: "ThreadListItemComponents",
  required: true,
  description: "The components to render for each thread list item.",
  children: [
    {
      type: "ThreadListItemComponents",
      parameters: [
        {
          name: "ThreadListItem",
          type: "ComponentType",
          required: true,
          description: "The component to render for each thread in the list.",
        },
      ],
    },
  ],
},
]}
/>

ItemByIndex \[#itembyindex]

Renders a single thread list item at the specified index.

```tsx
<ThreadListPrimitive.ItemByIndex
  index={0}
  components={{
    ThreadListItem: MyThreadListItem
  }}
/>
```

<ParametersTable
  type="ThreadListPrimitive.ItemByIndex.Props"
  parameters={[
{
  name: "index",
  type: "number",
  required: true,
  description: "The index of the thread list item to render.",
},
{
  name: "archived",
  type: "boolean",
  default: "false",
  description: "Whether to render from archived threads instead of active threads.",
},
{
  name: "components",
  type: "ThreadListItemComponents",
  required: true,
  description: "The components to render for the thread list item.",
},
]}
/>


# ThreadPrimitive
URL: /docs/api-reference/primitives/thread

Primitives for the message list, viewport, and welcome screen.

A conversation between a user and an assistant.

Anatomy \[#anatomy]

```tsx
import { ThreadPrimitive } from "@assistant-ui/react";

const Thread = () => (
  <ThreadPrimitive.Root>
    <ThreadPrimitive.Viewport>
      <AuiIf condition={(s) => s.thread.isEmpty}>...</AuiIf>
      <ThreadPrimitive.Messages components={...} />
    </ThreadPrimitive.Viewport>
    <Composer />
  </ThreadPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Containts all parts of the thread.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ThreadPrimitiveRootProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

Viewport \[#viewport]

The scrollable area containing all messages. Anchors scroll to the bottom as new messages are added.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ThreadPrimitiveViewportProps"
  parameters={[
{
  name: "asChild",
},
{
  name: "autoScroll",
  type: "boolean",
  default: "true",
  description:
    "Whether to automatically scroll to the bottom of the viewport when new messages are added while the viewport is was previously scrolled to the bottom.",
},
]}
/>

Messages \[#messages]

Renders all messages. This primitive renders a separate component for each message.

<ParametersTable
  type="ThreadPrimitiveMessagesProps"
  parameters={[
{
  name: "components",
  type: "MessageComponents",
  description: "The component to render for each message.",
  children: [
    {
      type: "MessageComponents",
      parameters: [
        {
          name: "Message",
          type: "ComponentType",
          description: "The component to render for each message.",
        },
        {
          name: "UserMessage",
          type: "ComponentType",
          description: "The component to render for user messages.",
        },
        {
          name: "EditComposer",
          type: "ComponentType",
          description:
            "The component to render for user messages that are being edited.",
        },
        {
          name: "AssistantMessage",
          type: "ComponentType",
          description: "The component to render for assistant messages.",
        },
      ],
    },
  ],
},
]}
/>

MessageByIndex \[#messagebyindex]

Renders a single message at the specified index in the current thread.

```tsx
<ThreadPrimitive.MessageByIndex
  index={0}
  components={{
    UserMessage: MyUserMessage,
    AssistantMessage: MyAssistantMessage
  }}
/>
```

<ParametersTable
  type="ThreadPrimitive.MessageByIndex.Props"
  parameters={[
{
  name: "index",
  type: "number",
  required: true,
  description: "The index of the message to render.",
},
{
  name: "components",
  type: "MessageComponents",
  description: "The component configuration for rendering the message.",
  children: [
    {
      type: "MessageComponents",
      parameters: [
        {
          name: "Message",
          type: "ComponentType",
          description: "The component to render for each message.",
        },
        {
          name: "UserMessage",
          type: "ComponentType",
          description: "The component to render for user messages.",
        },
        {
          name: "EditComposer",
          type: "ComponentType",
          description:
            "The component to render for user messages that are being edited.",
        },
        {
          name: "AssistantMessage",
          type: "ComponentType",
          description: "The component to render for assistant messages.",
        },
      ],
    },
  ],
},
]}
/>

Empty \[#empty]

Renders children only when there are no messages.

ScrollToBottom \[#scrolltobottom]

A button to scroll the viewport to the bottom. Disabled when the viewport is already at bottom.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadPrimitiveScrollToBottomProps"
  parameters={[
{
  name: "asChild",
},
]}
/>

ThreadPrimitive.Suggestions \[#threadprimitivesuggestions]

Renders all configured suggestions from the Suggestions API. Each suggestion is rendered using the provided Suggestion component.

```tsx
import { ThreadPrimitive, SuggestionPrimitive } from "@assistant-ui/react";

const SuggestionsList = () => {
  return (
    <div className="grid grid-cols-2 gap-2">
      <ThreadPrimitive.Suggestions
        components={{
          Suggestion: SuggestionItem,
        }}
      />
    </div>
  );
};

const SuggestionItem = () => (
  <SuggestionPrimitive.Trigger send asChild>
    <button className="p-3 border rounded">
      <SuggestionPrimitive.Title />
      <SuggestionPrimitive.Description />
    </button>
  </SuggestionPrimitive.Trigger>
);
```

<ParametersTable
  type="ThreadPrimitiveSuggestionsProps"
  parameters={[
{
  name: "components",
  type: "{ Suggestion: ComponentType }",
  description: "Custom component to render each suggestion.",
},
]}
/>

<Callout type="info">
  Configure suggestions using the `Suggestions()` API in your runtime provider. See the [Suggestions guide](/docs/guides/suggestions) for details.
</Callout>


# AssistantRuntime
URL: /docs/api-reference/runtimes/assistant-runtime

Root runtime for managing threads, tool UIs, and assistant state.

import { AssistantRuntime, AssistantToolUIsState } from "@/generated/typeDocs";

The `AssistantRuntime` is the root runtime of the application.

useAssistantRuntime \[#useassistantruntime]

```tsx
import { useAssistantRuntime } from "@assistant-ui/react";

const runtime = useAssistantRuntime();
```

<ParametersTable {...AssistantRuntime} />

Tool UI Registry \[#tool-ui-registry]

The tool UI registry is part of the assistant runtime. It allows you to display custom UI for tool calls, enabling generative UI.


# AttachmentRuntime
URL: /docs/api-reference/runtimes/attachment-runtime

Hooks for accessing attachment state in composer and messages.

import {
  ComposerAttachmentState,
  MessageAttachmentState,
} from "@/components/docs/parameters-table.context";

useAttachment \[#useattachment]

Access the current attachment state:

```tsx
import { useAttachment } from "@assistant-ui/react";

const { attachment } = useAttachment();
const att = useAttachment((m) => m.attachment);
```

useComposerAttachment (Composer) \[#usecomposerattachment-composer]

When working with a composer’s attachment:

```tsx
import { useComposerAttachment } from "@assistant-ui/react";

const { attachment } = useComposerAttachment();
const composerAttachment = useComposerAttachment((m) => m.attachment);
```

<ParametersTable {...ComposerAttachmentState} />

useMessageAttachment (Message) \[#usemessageattachment-message]

For managing a message’s attachment:

```tsx
import { useMessageAttachment } from "@assistant-ui/react";

const { attachment } = useMessageAttachment();
const messageAttachment = useMessageAttachment((m) => m.attachment);
```

<ParametersTable {...MessageAttachmentState} />


# ComposerRuntime
URL: /docs/api-reference/runtimes/composer-runtime

Runtime for programmatically controlling the message composer.

The composer runtime allows you to view or edit anything related to how new information is added and sent. For instance you can use the composer runtime to read the state, add attachments, update text, send a message, etc.

import { ComposerRuntime, ThreadComposerRuntime, ThreadComposerState, EditComposerState } from "@/generated/typeDocs";

useComposerRuntime \[#usecomposerruntime]

Grabs the nearest composer (whether it’s the edit composer or the thread’s composer):

```tsx
// Example
import { useComposerRuntime } from "@assistant-ui/react";

const composerRuntime = useComposerRuntime();

// set the text
composerRuntime.setText("Hello from the composer runtime");

// send whatever is in the composer
composerRuntime.send();

// get the current text in the composer state
const composerState = composerRuntime.getState();
const currentText = composerState.text;

```

<ParametersTable {...ComposerRuntime} />

useThreadComposer \[#usethreadcomposer]

Access the thread’s new message composer state:

```tsx
import { useThreadComposer } from "@assistant-ui/react";

const threadComposerRuntime = useThreadComposer();

// set the text
threadComposerRuntime.setText("Hello from the thread composer runtime");

// send whatever is in the thread composer
threadComposerRuntime.send();

// get the current text in the composer state
const threadComposerState = threadComposerRuntime.getState();
const currentText = threadComposerRuntime.text;

```

<ParametersTable {...ThreadComposerRuntime} />

ThreadComposerState \[#threadcomposerstate]

The state of the thread composer which is the composer the user can interact with at the bottom.

<ParametersTable {...ThreadComposerState} />

EditComposerState \[#editcomposerstate]

The state of the edit composer which is the composer the user can edit messages with.

<ParametersTable {...EditComposerState} />


# MessagePartRuntime
URL: /docs/api-reference/runtimes/message-part-runtime

Hook for accessing message part state within parts.

import { MessagePartState } from "@/components/docs/parameters-table.context";

useMessagePart \[#usemessagepart]

Access the message part state:

```tsx
import { useMessagePart } from "@assistant-ui/react";

const part = useMessagePart();
const partState = useMessagePart.getState();

const status = useMessagePart((m) => m.status);
const statusAgain = useMessagePart.getState().status;
```

<ParametersTable {...MessagePartState} />


# MessageRuntime
URL: /docs/api-reference/runtimes/message-runtime

Hooks for accessing message state, utilities, and edit composer.

import {
  MessageState,
  MessageUtilsState,
  EditComposerState,
} from "@/components/docs/parameters-table.context";

useMessage \[#usemessage]

Retrieve the message object:

```tsx
import { useMessage } from "@assistant-ui/react";

const { message } = useMessage();
const msg = useMessage((m) => m.message);
```

<ParametersTable {...MessageState} />

useMessageUtils \[#usemessageutils]

Provides utility functions for a message (e.g., copy status):

```tsx
import { useMessageUtils } from "@assistant-ui/react";

const messageUtils = useMessageUtils();
const isCopied = useMessageUtils((m) => m.isCopied);
```

<ParametersTable {...MessageUtilsState} />

useEditComposer \[#useeditcomposer]

Access the edit composer state (used when editing a message):

```tsx
import { useEditComposer } from "@assistant-ui/react";

const editComposer = useEditComposer();
const text = useEditComposer((m) => m.text);
```

<ParametersTable {...EditComposerState} />


# ThreadListItemRuntime
URL: /docs/api-reference/runtimes/thread-list-item-runtime

Runtime for managing individual thread list items.

import {
  ThreadListItemRuntime,
  ThreadListItemState,
} from "@/generated/typeDocs";

useThreadListItemRuntime \[#usethreadlistitemruntime]

```tsx
import { useThreadListItemRuntime } from "@assistant-ui/react";

const threadListItemRuntime = useThreadListItemRuntime();
```

<ParametersTable {...ThreadListItemRuntime} />

useThreadListItem \[#usethreadlistitem]

Access the state for a specific thread list item:

```tsx
import { useThreadListItem } from "@assistant-ui/react";

const threadListItem = useThreadListItem();
const title = useThreadListItem((m) => m.title);
```

<ParametersTable {...ThreadListItemState} />


# ThreadListRuntime
URL: /docs/api-reference/runtimes/thread-list-runtime

Runtime for accessing and managing the list of threads.

import { ThreadListRuntime, ThreadListState } from "@/generated/typeDocs";

Access via useAssistantRuntime \[#access-via-useassistantruntime]

You can access the thread list runtime via the assistant runtime:

```tsx
import { useAssistantRuntime } from "@assistant-ui/react";

const threadListRuntime = useAssistantRuntime().threadList;
```

<ParametersTable {...ThreadListRuntime} />

useThreadList \[#usethreadlist]

This hook provides access to the thread list state:

```tsx
import { useThreadList } from "@assistant-ui/react";

const threadList = useThreadList();
const threads = useThreadList((m) => m.threads);
const isLoading = useThreadList((m) => m.isLoading);
```

<ParametersTable {...ThreadListState} />


# ThreadRuntime
URL: /docs/api-reference/runtimes/thread-runtime

Runtime for thread state, messages, and viewport management.

import { ThreadRuntime, ThreadState } from "@/generated/typeDocs";
import { ThreadViewportState } from "@/components/docs/parameters-table.context";

useThreadRuntime \[#usethreadruntime]

Get the thread runtime object:

```tsx
import { useThreadRuntime } from "@assistant-ui/react";

const thread = useThreadRuntime();
```

<ParametersTable {...ThreadRuntime} />

useThread \[#usethread]

Access the thread state directly:

```tsx
import { useThread } from "@assistant-ui/react";

const thread = useThread();
const isRunning = useThread((m) => m.isRunning);
const isLoading = useThread((m) => m.isLoading);
```

<ParametersTable {...ThreadState} />

useThreadViewport \[#usethreadviewport]

Manage thread viewport state (e.g., scrolling):

```tsx
import { useThreadViewport } from "@assistant-ui/react";

const threadViewport = useThreadViewport();
const isAtBottom = useThreadViewport((m) => m.isAtBottom);
```

<ParametersTable {...ThreadViewportState} />


# AssistantModal
URL: /docs/legacy/styled/assistant-modal

Chat bubble component for support or Q&A use cases.

Overview \[#overview]

A chat bubble shown in the bottom right corner of the screen. Useful for support or Q\&A use cases.

Getting Started \[#getting-started]

<Steps>
  <Step>
    Install @assistant-ui/react-ui \[#install-assistant-uireact-ui]

    <InstallCommand npm={["@assistant-ui/react-ui"]} />
  </Step>

  <Step>
    Import CSS styles \[#import-css-styles]

    Add the following to your `tailwind.config.ts`:

    <Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
      <>
        <Tab value="Tailwind">
          ```ts title="/tailwind.config.ts" 
          {
            plugins: [
              require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
              require("@assistant-ui/react-ui/tailwindcss")({
                components: ["assistant-modal"],
              })
            ],
          }
          ```
        </Tab>

        <Tab value="Tailwind + shadcn-ui">
          ```ts title="/tailwind.config.ts" 
          {
            plugins: [
              require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
              require("@assistant-ui/react-ui/tailwindcss")({
                components: ["assistant-modal"],
                shadcn: true
              })
            ],
          }
          ```
        </Tab>
      </>
    </Tabs>
  </Step>

  <Step>
    Use it in your app \[#use-it-in-your-app]

    ```tsx title="/app/page.tsx"
    import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
    import { AssistantModal } from "@assistant-ui/react-ui";

    const MyApp = () => {
      const runtime = useChatRuntime({
        api: "/api/chat",
      });

      return (
        <div>
          <AssistantModal runtime={runtime} />
        </div>
      );
    };
    ```
  </Step>
</Steps>


# Decomposition
URL: /docs/legacy/styled/decomposition

Break down styled components into smaller customizable parts.

Overview \[#overview]

The Styled Components can be decomposed into smaller components. At each level, you can swap out a specific component with your own custom component.

Thread \[#thread]

Renders an entire conversation thread.

```tsx
import {
  Thread,
  ThreadWelcome,
  Composer,
  type ThreadConfig,
} from "@assistant-ui/react-ui";

const MyThread: FC<ThreadConfig> = (config) => {
  return (
    <Thread.Root config={config}>
      <Thread.Viewport>
        <ThreadWelcome />
        <Thread.Messages />
        <Thread.FollowupSuggestions />
        <Thread.ViewportFooter>
          <Thread.ScrollToBottom />
          <Composer />
        </Thread.ViewportFooter>
      </Thread.Viewport>
    </Thread.Root>
  );
};
```

**Usage:**

```ts
<MyThread />
```

Thread.Root \[#threadroot]

Contains all parts of the thread. Accepts a `config` prop which is used by many other styled components.

Thread.Viewport \[#threadviewport]

The scrollable area containing all messages. Anchors scroll to the bottom as new messages are added.

Thread.Messages \[#threadmessages]

Renders all messages. This renders a separate component for each message (passed to the `components` prop).

Thread.ViewportFooter \[#threadviewportfooter]

Renders the footer of the thread viewport. This is the sticky footer that does not scroll with the messages.

Thread.ScrollToBottom \[#threadscrolltobottom]

A button to scroll the viewport to the bottom. Hidden when the viewport is already at bottom.

ThreadWelcome \[#threadwelcome]

Renders the welcome message when no messages are present.

```tsx
import { ThreadWelcome } from "@assistant-ui/react-ui";

const MyThreadWelcome: FC = () => {
  return (
    <ThreadWelcome.Root>
      <ThreadWelcome.Center>
        <ThreadWelcome.Avatar />
        <ThreadWelcome.Message />
      </ThreadWelcome.Center>
      <ThreadWelcome.Suggestions />
    </ThreadWelcome.Root>
  );
};
```

**Usage:**

Decompose `Thread` into `MyThread` and use `MyThreadWelcome` instead of `ThreadWelcome`.

```ts
const MyThread: FC<ThreadConfig> = (config) => {
  ...
  <MyThreadWelcome />
  ...
};
```

ThreadWelcome.Root \[#threadwelcomeroot]

Contains all parts of the welcome message.

ThreadWelcome.Center \[#threadwelcomecenter]

The centered content of the welcome message.

ThreadWelcome.Avatar \[#threadwelcomeavatar]

The avatar of the assistant.

ThreadWelcome.Message \[#threadwelcomemessage]

The welcome message.

ThreadWelcome.Suggestions \[#threadwelcomesuggestions]

Conversation starter suggestions.

```tsx
import { ThreadWelcome } from "@assistant-ui/react-ui";

const MyThreadWelcomeSuggestions: FC = () => {
  return (
    <div className="aui-thread-welcome-suggestions">
      <ThreadWelcome.Suggestion prompt="Write me a poem about the weather" />
      <ThreadWelcome.Suggestion prompt="What is assistant-ui?" />
    </div>
  );
};
```

ThreadWelcome.Suggestion \[#threadwelcomesuggestion]

A conversation starter suggestion.

Composer \[#composer]

Renders the composer.

```tsx
import { Composer } from "@assistant-ui/react-ui";

const MyComposer: FC = () => {
  return (
    <Composer.Root>
      <Composer.Attachments />
      <Composer.AddAttachment />
      <Composer.Input autoFocus />
      <Composer.Action />
    </Composer.Root>
  );
};
```

**Usage:**

Decompose `Thread` into `MyThread` and use `MyComposer` instead of `Composer`.

```ts
const MyThread: FC<ThreadConfig> = (config) => {
  ...
  <MyComposer />
  ...
};
```

Composer.Root \[#composerroot]

Contains all parts of the composer.

Composer.Input \[#composerinput]

The text input field for the user to type a new message.

Composer.Action \[#composeraction]

The button to send or cancel the message.

```tsx
import { Composer } from "@assistant-ui/react-ui";
import { AuiIf } from "@assistant-ui/react";

const MyComposerAction: FC = () => {
  return (
    <>
      <AuiIf condition={(s) => !s.thread.isRunning}>
        <Composer.Send />
      </AuiIf>
      <AuiIf condition={(s) => s.thread.isRunning}>
        <Composer.Cancel />
      </AuiIf>
    </>
  );
};
```

Composer.Send \[#composersend]

The button to send the message.

Composer.Cancel \[#composercancel]

Sends a cancel action.

Composer.Attachments \[#composerattachments]

Renders attachments.

Composer.AddAttachment \[#composeraddattachment]

Renders an add attachment button.

AttachmentUI \[#attachmentui]

<Callout type="info" emoji="💡">
  `AttachmentUI` is still experimental.
</Callout>

Renders an attachment.

```tsx
import { AttachmentUI } from "@assistant-ui/react-ui";

const MyAttachmentUI: FC = () => {
  return (
    <AttachmentUI.Root>
      attachment
      <AttachmentUI.Remove />
    </AttachmentUI.Root>
  );
};
```

AttachmentUI.Root \[#attachmentuiroot]

Contains all parts of the composer attachment.

AttachmentUI.Remove \[#attachmentuiremove]

Renders a remove attachment button.

AssistantMessage \[#assistantmessage]

Renders an assistant message.

```tsx
import { AssistantMessage } from "@assistant-ui/react-ui";

const MyAssistantMessage: FC = () => {
  return (
    <AssistantMessage.Root>
      <AssistantMessage.Avatar />
      <AssistantMessage.Content />
      <BranchPicker />
      <AssistantActionBar />
    </AssistantMessage.Root>
  );
};
```

**Usage:**

Decompose `Thread` into `MyThread` and pass `MyAssistantMessage` to Thread.MEssages

```ts
const MyThread: FC<ThreadConfig> = (config) => {
  ...
  <Thread.Messages components={{ AssistantMessage: MyAssistantMessage }} />
  ...
};
```

AssistantMessage.Root \[#assistantmessageroot]

Contains all parts of the assistant message.

AssistantMessage.Avatar \[#assistantmessageavatar]

The avatar of the assistant.

AssistantMessage.Content \[#assistantmessagecontent]

The content of the assistant message.

AssistantActionBar \[#assistantactionbar]

Renders the action bar for the assistant message.

```tsx
import { AssistantActionBar } from "@assistant-ui/react-ui";

const MyAssistantActionBar: FC = () => {
  return (
    <AssistantActionBar.Root
      hideWhenRunning
      autohide="not-last"
      autohideFloat="single-branch"
    >
      <AssistantActionBar.SpeechControl />
      <AssistantActionBar.Copy />
      <AssistantActionBar.Reload />
      <AssistantActionBar.FeedbackPositive />
      <AssistantActionBar.FeedbackNegative />
    </AssistantActionBar.Root>
  );
};
```

**Usage:**

Decompose `AssistantMessage` into `MyAssistantMessage` and use `MyAssistantActionBar` instead of `AssistantActionBar`.

```ts
const MyAssistantMessage: FC = () => {
  ...
  <MyAssistantActionBar />
  ...
};
```

AssistantActionBar.Root \[#assistantactionbarroot]

Contains all parts of the assistant action bar.

AssistantActionBar.Reload \[#assistantactionbarreload]

Shows a reload button.

AssistantActionBar.Copy \[#assistantactionbarcopy]

Shows a copy button.

AssistantActionBar.SpeechControl \[#assistantactionbarspeechcontrol]

Shows a speech control button (either Speak or StopSpeaking).

AssistantActionBar.Speak \[#assistantactionbarspeak]

Shows a speak button.

AssistantActionBar.StopSpeaking \[#assistantactionbarstopspeaking]

Shows a stop speaking button.

AssistantActionBar.FeedbackPositive \[#assistantactionbarfeedbackpositive]

Shows a positive feedback button.

AssistantActionBar.FeedbackNegative \[#assistantactionbarfeedbacknegative]

Shows a negative feedback button.

BranchPicker \[#branchpicker]

Renders the branch picker.

```tsx
import { BranchPicker } from "@assistant-ui/react-ui";

const MyBranchPicker: FC = () => {
  return (
    <BranchPicker.Root hideWhenSingleBranch>
      <BranchPicker.Previous />
      <BranchPicker.State />
      <BranchPicker.Next />
    </BranchPicker.Root>
  );
};
```

**Usage:**

Decompose `AssistantMessage` and `UserMessage` and use `MyBranchPicker` instead of `BranchPicker`.

```ts
const MyAssistantMessage: FC = () => {
  ...
  <MyBranchPicker />
  ...
};
```

```ts
const MyUserMessage: FC = () => {
  ...
  <MyBranchPicker />
  ...
};
```

BranchPicker.Root \[#branchpickerroot]

Contains all parts of the branch picker.

BranchPicker.Previous \[#branchpickerprevious]

Shows a previous button.

BranchPicker.Next \[#branchpickernext]

Shows a next button.

BranchPicker.State \[#branchpickerstate]

Shows the current branch number and total number of branches.

```tsx
import { BranchPicker } from "@assistant-ui/react-ui";

const MyBranchPickerState: FC = () => {
  return (
    <span className="aui-branch-picker-state">
      <BranchPicker.Number /> / <BranchPicker.Count />
    </span>
  );
};
```

BranchPicker.Number \[#branchpickernumber]

The current branch number.

BranchPicker.Count \[#branchpickercount]

The total number of branches.

UserMessage \[#usermessage]

Renders a user message.

```tsx
import { UserMessage } from "@assistant-ui/react-ui";

const MyUserMessage: FC = () => {
  return (
    <UserMessage.Root>
      <UserMessage.Attachments />
      <UserMessage.Content />
      <UserActionBar />
      <BranchPicker />
    </UserMessage.Root>
  );
};
```

**Usage:**

Decompose `Thread` into `MyThread` and pass `MyUserMessage` to Thread.Messages

```ts
const MyThread: FC<ThreadConfig> = (config) => {
  ...
  <Thread.Messages components={{ UserMessage: MyUserMessage }} />
  ...
};
```

UserMessage.Root \[#usermessageroot]

Contains all parts of the user message.

UserMessage.Content \[#usermessagecontent]

The content of the user message.

UserMessage.Attachments \[#usermessageattachments]

Renders attachments.

UserActionBar \[#useractionbar]

Renders the action bar for the user message.

```tsx
import { UserActionBar } from "@assistant-ui/react-ui";

const MyUserActionBar: FC = () => {
  return (
    <UserActionBar.Root hideWhenRunning autohide="not-last">
      <UserActionBar.Edit />
    </UserActionBar.Root>
  );
};
```

**Usage:**

Decompose `UserMessage` into `MyUserMessage` and use `MyUserActionBar` instead of `UserActionBar`.

```ts
const MyUserMessage: FC = () => {
  ...
  <MyUserActionBar />
  ...
};
```

UserActionBar.Root \[#useractionbarroot]

Contains all parts of the user action bar.

UserActionBar.Edit \[#useractionbaredit]

Shows an edit button.

UserAttachment \[#userattachment]

Renders an attachment.

```tsx
import { UserAttachment } from "@assistant-ui/react-ui";

const MyUserAttachment: FC = () => {
  return <UserAttachment.Root>attachment</UserAttachment.Root>;
};
```

UserAttachment.Root \[#userattachmentroot]

Contains all parts of the user attachment.

EditComposer \[#editcomposer]

Renders a user message being edited.

```tsx
import { EditComposer } from "@assistant-ui/react-ui";

const MyEditComposer: FC = () => {
  return (
    <EditComposer.Root>
      <EditComposer.Input />
      <EditComposer.Footer>
        <EditComposer.Cancel />
        <EditComposer.Send />
      </EditComposer.Footer>
    </EditComposer.Root>
  );
};
```

**Usage:**

Decompose `Thread` into `MyThread` and pass `MyEditComposer` to `Thread.Messages`.

```ts
const MyThread: FC<ThreadConfig> = (config) => {
  ...
  <Thread.Messages components={{ EditComposer: MyEditComposer }} />
  ...
};
```

EditComposer.Root \[#editcomposerroot]

Contains all parts of the edit composer.

EditComposer.Input \[#editcomposerinput]

The text input field for the user to type a new message.

EditComposer.Footer \[#editcomposerfooter]

The footer of the edit composer.

EditComposer.Cancel \[#editcomposercancel]

Sends a cancel action.

EditComposer.Send \[#editcomposersend]

Sends the message.

AssistantModal \[#assistantmodal]

Renders the assistant modal.

```tsx
import {
  AssistantModal,
  Thread,
  type ThreadConfig,
} from "@assistant-ui/react-ui";

const MyAssistantModal: FC<ThreadConfig> = (config) => {
  return (
    <AssistantModal.Root config={config}>
      <AssistantModal.Trigger />
      <AssistantModal.Content>
        <Thread />
      </AssistantModal.Content>
    </AssistantModal.Root>
  );
};
```

**Usage:**

```ts
<MyAssistantModal />
```

ThreadList \[#threadlist]

Renders a thread list.

```tsx
import { ThreadList, ThreadListItem } from "@assistant-ui/react-ui";

const MyThreadList = () => {
  return (
    <ThreadList.Root>
      <ThreadList.New />
      <ThreadList.Items />
    </ThreadList.Root>
  );
};
```

ThreadListItem \[#threadlistitem]

Renders a thread list item.

```tsx
import { ThreadListItem, ThreadListItemPrimitive } from "@assistant-ui/react-ui";

const MyThreadListItem = () => {
  return (
    <ThreadListItem.Root>
      <ThreadListItemTrigger>
        <ThreadListItemTitle />
      </ThreadListItemTrigger>
      <ThreadListItem.Archive />
    </ThreadListItem.Root>
  );
};
```


# Markdown
URL: /docs/legacy/styled/markdown

Enable rich text formatting for assistant messages using markdown.

Allow the assistant to display rich text using markdown.

Enabling markdown support \[#enabling-markdown-support]

<Steps>
  <Step>
    Install @assistant-ui/react-markdown \[#install-assistant-uireact-markdown]

    <InstallCommand npm={["@assistant-ui/react-markdown"]} />
  </Step>

  <Step>
    Setup styles \[#setup-styles]

    <Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
      <>
        <Tab value="Tailwind">
          ```ts {3} title="/tailwind.config.ts" 
          {
            plugins: [
              require("tailwindcss-animate"),
              require("@assistant-ui/react-ui/tailwindcss")
            ],
          }
          ```
        </Tab>

        <Tab value="Tailwind + shadcn-ui">
          ```ts title="/tailwind.config.ts" 
          {
            plugins: [
              require("tailwindcss-animate"),
              require("@assistant-ui/react-ui/tailwindcss")({ shadcn: true })
            ],
          }
          ```
        </Tab>
      </>
    </Tabs>
  </Step>

  <Step>
    Define a MarkdownText component \[#define-a-markdowntext-component]

    ```tsx {1} title="@/components/markdown-text.tsx"
    import { makeMarkdownText } from "@assistant-ui/react-ui";

    export const MarkdownText = makeMarkdownText();
    ```
  </Step>

  <Step>
    Use it with Thread \[#use-it-with-thread]

    Pass the `MarkdownText` component to your `Thread` component.

    ```tsx {1, 7}
    import { MarkdownText } from "@/components/markdown-text";

    const Home = () => {
      return (
        <Thread assistantMessage={{ components: { Text: MarkdownText } }}>
      );
    };
    ```
  </Step>
</Steps>


# Custom Scrollbar
URL: /docs/legacy/styled/scrollbar

Integrate custom scrollbar UI using Radix UI Scroll Area.

If you want to show a custom scrollbar UI of the Thread.Viewport in place of the system default, you can integrate `@radix-ui/react-scroll-area`.
An example implementation of this is [shadcn-ui's Scroll Area](https://ui.shadcn.com/docs/components/scroll-area).

Add shadcn Scroll Area \[#add-shadcn-scroll-area]

```sh
npx shadcn@latest add scroll-area
```

@radix-ui/react-scroll-area v1.2.0 release candidate required \[#radix-uireact-scroll-area-v120-release-candidate-required]

The v1.2.0-rc.x release candidate can be installed via

```sh
pnpm add @radix-ui/react-scroll-area@next
```

Additional Styles \[#additional-styles]

The radix-ui Viewport component adds an intermediate `<div data-radix-scroll-area-content>` element.
Add the following CSS to your `globals.css`:

```css title="@/app/globals.css"
.aui-thread-viewport > [data-radix-scroll-area-content] {
  @apply flex flex-col items-center self-stretch bg-inherit;
}
```

Integration \[#integration]

* Decompose `Thread` into `MyThread` (see [Decomposition](/docs/legacy/styled/decomposition))
* Wrap `Thread.Root` with `<ScrollAreaPrimitive.Root asChild>`
* Wrap `Thread.Viewport` with `<ScrollAreaPrimitive.Viewport asChild>`
* Add shadcn's `<ScrollBar />` to `Thread.Root`

The resulting MyThread component should look like this:

```tsx
import {
  Thread,
  ThreadWelcome,
  Composer,
  type ThreadConfig,
} from "@assistant-ui/react-ui";
import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area"; // [!code highlight]
import { ScrollBar } from "@/components/ui/scroll-area"; // [!code highlight]

const MyThread: FC<ThreadConfig> = (config) => {
  return (
    <ScrollAreaPrimitive.Root asChild> /* [!code highlight] */
      <Thread.Root config={config}>
        <ScrollAreaPrimitive.Viewport asChild> /* [!code highlight] */
          <Thread.Viewport>
            <ThreadWelcome />
            <Thread.Messages />
            <Thread.ViewportFooter>
              <Thread.ScrollToBottom />
              <Composer />
            </Thread.ViewportFooter>
          </Thread.Viewport>
        </ScrollAreaPrimitive.Viewport> /* [!code highlight] */
        <ScrollBar /> /* [!code highlight] */
      </Thread.Root>
    </ScrollAreaPrimitive.Root> /* [!code highlight] */
  );
};
```


# Thread Width
URL: /docs/legacy/styled/thread-width

Customize thread max width using CSS variables.

You can modify the max width of the thread via the CSS variable `--aui-thread-max-width`.

Wider Thread \[#wider-thread]

```css title="@/app/globals.css"
:root {
  --aui-thread-max-width: 600px;
}
```

Take up the whole screen \[#take-up-the-whole-screen]

```css title="@/app/globals.css"
:root {
  --aui-thread-max-width: infinity;
}
```


# Thread
URL: /docs/legacy/styled/thread

Full-screen message list and composer UI for chat interfaces.

Overview \[#overview]

The raw message list and message composer UI. Useful for full screen chat use cases.

Getting Started \[#getting-started]

<Steps>
  <Step>
    Install @assistant-ui/react-ui \[#install-assistant-uireact-ui]

    <InstallCommand npm={["@assistant-ui/react-ui"]} />
  </Step>

  <Step>
    Import CSS styles \[#import-css-styles]

    Add the following to your `tailwind.config.ts`:

    <Tabs items={["Tailwind", "Tailwind + shadcn-ui"]}>
      <>
        <Tab value="Tailwind">
          ```ts title="/tailwind.config.ts" 
          {
            plugins: [
              require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
              require("@assistant-ui/react-ui/tailwindcss")({
                components: ["thread"],
              })
            ],
          }
          ```
        </Tab>

        <Tab value="Tailwind + shadcn-ui">
          ```ts title="/tailwind.config.ts" 
          {
            plugins: [
              require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
              require("@assistant-ui/react-ui/tailwindcss")({
                components: ["thread"],
                shadcn: true
              })
            ],
          }
          ```
        </Tab>
      </>
    </Tabs>
  </Step>

  <Step>
    Use it in your app \[#use-it-in-your-app]

    ```tsx title="/app/page.tsx"
    import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
    import { Thread } from "@assistant-ui/react-ui";

    const MyApp = () => {
      const runtime = useChatRuntime({
        api: "/api/chat",
      });

      return (
        <div className="h-full">
          <Thread runtime={runtime} />
        </div>
      );
    };
    ```
  </Step>
</Steps>


# Introduction
URL: /docs/runtimes/langgraph/tutorial

Build a stockbroker assistant with LangGraph and assistant-ui.

import { redirect } from "next/navigation";

<>
  {redirect(
        "/docs/runtimes/langgraph/tutorial/introduction",
      )}
</>


# Introduction
URL: /docs/runtimes/langgraph/tutorial/introduction

Build a stockbroker assistant with LangGraph and assistant-ui.

In this tutorial, we will build a stockbroker assistant using LangChain.js, LangGraph.js and assistant-ui.

We will go through the necessary steps to integrate assistant-ui with a LangGraph Cloud endpoint.
Code snippets focus on the setup of the frontend, but we will highlight relevant sections of the backend code as well.

This agent leverages the following features:

* 🚄 Streaming of messages from LangGraph state to assistant-ui
* 💅 Rich text rendering using Markdown
* 🛠️ Generative UI: Mapping tool calls to tool UIs
* 🔁 Approval UI: Confirming tool calls before execution (human-in-the-loop)

Prerequisites \[#prerequisites]

* Node.js 18.x or higher

Final Result \[#final-result]

* Demo: [https://assistant-ui-stockbroker.vercel.app/](https://assistant-ui-stockbroker.vercel.app/)
* Source Code: [https://github.com/assistant-ui/assistant-ui-stockbroker](https://github.com/assistant-ui/assistant-ui-stockbroker)

Get Started \[#get-started]

Begin Part 1 of the tutorial by [setting up the frontend](/docs/runtimes/langgraph/tutorial/part-1).


# Part 1: Setup frontend
URL: /docs/runtimes/langgraph/tutorial/part-1

Create a Next.js project with the LangGraph assistant-ui template.

Create a new project \[#create-a-new-project]

Run the following command to create a new Next.js project with the LangGraph assistant-ui template:

```sh
npx create-assistant-ui@latest -t langgraph my-app
cd my-app
```

You should see the following files in your project:

import { File, Folder, Files } from "fumadocs-ui/components/files";

<Files>
  <Folder name="my-app" defaultOpen>
    <Folder name="app" defaultOpen>
      <Folder name="api" defaultOpen>
        <Folder name="[...path]" defaultOpen>
          <File name="route.ts" />
        </Folder>
      </Folder>

      <File name="globals.css" />

      <File name="layout.tsx" />

      <File name="MyRuntimeProvider.tsx" />

      <File name="page.tsx" />
    </Folder>

    <Folder name="lib">
      <File name="chatApi.ts" />
    </Folder>

    <File name="next.config.ts" />

    <File name="package.json" />

    <File name="postcss.config.mjs" />

    <File name="tailwind.config.ts" />

    <File name="tsconfig.json" />
  </Folder>
</Files>

Setup environment variables \[#setup-environment-variables]

Create a `.env.local` file in your project with the following variables:

```sh title="@/.env.local"
LANGGRAPH_API_URL=https://assistant-ui-stockbroker.vercel.app/api
NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=stockbroker
```

This connects the frontend to a LangGraph Cloud endpoint running under\
`https://assistant-ui-stockbroker.vercel.app/api`.\
This endpoint is running the LangGraph agent defined [in this repository](https://github.com/assistant-ui/assistant-ui-stockbroker/blob/main/backend).

Start the server \[#start-the-server]

You can start the server by running the following command:

```sh
npm run dev
```

The server will start and you can view the frontend by opening a browser tab to [http://localhost:3000](http://localhost:3000).

You should be able to chat with the assistant and see LLM responses streaming in real-time.

Explore features \[#explore-features]

Streaming \[#streaming]

Streaming message support is enabled by default. The LangGraph integration includes sophisticated message handling that efficiently manages streaming responses:

* Messages are accumulated and updated in real-time using `LangGraphMessageAccumulator`
* Partial message chunks are automatically merged using `appendLangChainChunk`
* The runtime handles all the complexity of managing streaming state

This means you'll see tokens appear smoothly as they're generated by the LLM, with proper handling of both text content and tool calls.

Markdown support \[#markdown-support]

Rich text rendering using Markdown is enabled by default.

Add conversation starter messages \[#add-conversation-starter-messages]

In order to help users understand what the assistant can do, we can add some conversation starter messages.

import Image from "next/image";
import starter from "./images/conversation-starters.png";

<Image src={starter} alt="Conversation starters" width={600} className="mx-auto rounded-lg border shadow" />

```tsx title="@/app/page.tsx" {5-17}
export default function Home() {
  return (
    <div className="flex h-full flex-col">
      <Thread
        welcome={{
          suggestions: [
            {
              prompt: "How much revenue did Apple make last year?",
            },
            {
              prompt: "Is McDonald's profitable?",
            },
            {
              prompt: "What's the current stock price of Tesla?",
            },
          ],
        }}
        assistantMessage={{ components: { Text: MarkdownText } }}
      />
    </div>
  );
}
```


# Part 2: Generative UI
URL: /docs/runtimes/langgraph/tutorial/part-2

Display stock ticker information with generative UI components.

In the previous step, we set up the frontend to connect to a LangGraph Cloud endpoint.

In this step, we will set up a component to display stock ticker information.

import Image from "next/image";
import price from "./images/acme-price.png";

<Image src={price} alt="Price snapshot" width={600} className="mx-auto rounded-lg border shadow" />

For reference, this the corresponding code in the backend:

[https://github.com/assistant-ui/assistant-ui-stockbroker/blob/main/backend/src/tools.ts#L193C1-L216C3](https://github.com/assistant-ui/assistant-ui-stockbroker/blob/main/backend/src/tools.ts#L193C1-L216C3)

```ts title="assistant-ui-stockbroker/backend/tools/PriceSnapshotTool.ts"
export const priceSnapshotTool = tool(
  async (input) => {
    const data = await callFinancialDatasetAPI<SnapshotResponse>({
      endpoint: "/prices/snapshot",
      params: {
        ticker: input.ticker,
      },
    });
    return JSON.stringify(data, null);
  },
  {
    name: "price_snapshot",
    description:
      "Retrieves the current stock price and related market data for a given company.",
    schema: z.object({
      ticker: z.string().describe("The ticker of the company. Example: 'AAPL'"),
    }),
  },
);
```

PriceSnapshotTool \[#pricesnapshottool]

We create a new file under `/components/tools/price-snapshot/PriceSnapshotTool.tsx` to define the tool.

First, we define the tool arguments and result types:

```ts title="@/components/tools/price-snapshot/PriceSnapshotTool.tsx"
type PriceSnapshotToolArgs = {
  ticker: string;
};

type PriceSnapshotToolResult = {
  snapshot: {
    price: number;
    day_change: number;
    day_change_percent: number;
    time: string;
  };
};
```

Then, we use `makeAssistantToolUI` to define the tool UI:

```tsx title="@/components/tools/price-snapshot/PriceSnapshotTool.tsx"
"use client";

import { makeAssistantToolUI } from "@assistant-ui/react";

export const PriceSnapshotTool = makeAssistantToolUI<
  PriceSnapshotToolArgs,
  string
>({
  toolName: "price_snapshot",
  render: function PriceSnapshotUI({ args, result }) {
    return (
      <div className="mb-4 flex flex-col items-center">
        <pre className="whitespace-pre-wrap break-all text-center">
          price_snapshot({JSON.stringify(args)})
        </pre>
      </div>
    );
  },
});
```

This simply displays the tool name and arguments passed to it, but not the result.

Bind tool UI \[#bind-tool-ui]

```tsx title="@/app/page.tsx" {1,8}
import { PriceSnapshotTool } from "@/components/tools/price-snapshot/PriceSnapshotTool";

export default function Home() {
  return (
    <div className="flex h-full flex-col">
      <Thread
        ...
        tools={[PriceSnapshotTool]}
      />
    </div>
  );
}
```

Try it out! \[#try-it-out]

Ask the assistant for the current stock price of Tesla. You should see the following text appear:

```
price_snapshot({ticker: "TSLA"})
```

Next, we will visualize the function's result.

Visualizing tool results \[#visualizing-tool-results]

Install dependencies \[#install-dependencies]

The tool result component relies on shadcn/ui's `Card` component. We will install it as a dependency.

```sh
npx shadcn@latest add card
```

You will be prompted to setup a `components.json` file, after this step, a `card` UI component will be installed in your project.

Add PriceSnapshot \[#add-pricesnapshot]

We create a new file under `/components/tools/price-snapshot/price-snapshot.tsx` to define the new tool result UI.

```tsx title="@/components/tools/price-snapshot/price-snapshot.tsx"
"use client";

import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

type PriceSnapshotToolArgs = {
  ticker: string;
};

type PriceSnapshotToolResult = {
  price: number;
  day_change: number;
  day_change_percent: number;
  time: string;
};

export function PriceSnapshot({
  ticker,
  price,
  day_change,
  day_change_percent,
  time,
}: PriceSnapshotToolArgs & PriceSnapshotToolResult) {
  const isPositiveChange = day_change >= 0;
  const changeColor = isPositiveChange ? "text-green-600" : "text-red-600";
  const ArrowIcon = isPositiveChange ? ArrowUpIcon : ArrowDownIcon;

  return (
    <Card className="mx-auto w-full max-w-md">
      <CardHeader>
        <CardTitle className="text-2xl font-bold">{ticker}</CardTitle>
      </CardHeader>
      <CardContent>
        <div className="grid grid-cols-2 gap-4">
          <div className="col-span-2">
            <p className="text-3xl font-semibold">${price?.toFixed(2)}</p>
          </div>
          <div>
            <p className="text-muted-foreground text-sm">Day Change</p>
            <p
              className={`flex items-center text-lg font-medium ${changeColor}`}
            >
              <ArrowIcon className="mr-1 h-4 w-4" />$
              {Math.abs(day_change)?.toFixed(2)} (
              {Math.abs(day_change_percent)?.toFixed(2)}%)
            </p>
          </div>
          <div>
            <p className="text-muted-foreground text-sm">Last Updated</p>
            <p className="text-lg font-medium">
              {new Date(time).toLocaleTimeString()}
            </p>
          </div>
        </div>
      </CardContent>
    </Card>
  );
}
```

Update PriceSnapshotTool \[#update-pricesnapshottool]

We will import the new `<PriceSnapshot />` component and use it in the `render` function whenever a tool result is available.

```tsx title="@/components/tools/price-snapshot/PriceSnapshotTool.tsx" {3,25-30,37-42}
"use client";

import { PriceSnapshot } from "./price-snapshot";
import { makeAssistantToolUI } from "@assistant-ui/react";

type PriceSnapshotToolArgs = {
  ticker: string;
};

type PriceSnapshotToolResult = {
  snapshot: {
    price: number;
    day_change: number;
    day_change_percent: number;
    time: string;
  };
};

export const PriceSnapshotTool = makeAssistantToolUI<
  PriceSnapshotToolArgs,
  string
>({
  toolName: "price_snapshot",
  render: function PriceSnapshotUI({ args, result }) {
    let resultObj: PriceSnapshotToolResult | { error: string };
    try {
      resultObj = result ? JSON.parse(result) : {};
    } catch (e) {
      resultObj = { error: result! };
    }

    return (
      <div className="mb-4 flex flex-col items-center gap-2">
        <pre className="whitespace-pre-wrap break-all text-center">
          price_snapshot({JSON.stringify(args)})
        </pre>
        {"snapshot" in resultObj && (
          <PriceSnapshot ticker={args.ticker} {...resultObj.snapshot} />
        )}
        {"error" in resultObj && (
          <p className="text-red-500">{resultObj.error}</p>
        )}
      </div>
    );
  },
});
```

Try it out! \[#try-it-out-1]

Ask the assistant for the current stock price of Tesla. You should see the tool result appear:

import price2 from "./images/tsla-price.png";

<Image src={price2} alt="Price snapshot result" width={600} className="mx-auto rounded-lg border shadow" />

Fallback tool UI \[#fallback-tool-ui]

Instead of defining a custom tool UI for every tool, we can also define a fallback UI for all tools that are not explicitly defined.

This requires shadcn/ui's `Button` component. We will install it as a dependency.

```sh
npx shadcn@latest add button
```

Then create a new file under `/components/tools/ToolFallback.tsx` to define the fallback UI.

```tsx title="@/components/tools/ToolFallback.tsx"
import { ToolCallMessagePartComponent } from "@assistant-ui/react";
import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";

export const ToolFallback: ToolCallMessagePartComponent = ({
  toolName,
  argsText,
  result,
}) => {
  const [isCollapsed, setIsCollapsed] = useState(true);
  return (
    <div className="mb-4 flex w-full flex-col gap-3 rounded-lg border py-3">
      <div className="flex items-center gap-2 px-4">
        <CheckIcon className="size-4" />
        <p className="">
          Used tool: <b>{toolName}</b>
        </p>
        <div className="flex-grow" />
        <Button onClick={() => setIsCollapsed(!isCollapsed)}>
          {isCollapsed ? <ChevronUpIcon /> : <ChevronDownIcon />}
        </Button>
      </div>
      {!isCollapsed && (
        <div className="flex flex-col gap-2 border-t pt-2">
          <div className="px-4">
            <pre className="whitespace-pre-wrap">{argsText}</pre>
          </div>
          {result !== undefined && (
            <div className="border-t border-dashed px-4 pt-2">
              <p className="font-semibold">Result:</p>
              <pre className="whitespace-pre-wrap">
                {typeof result === "string"
                  ? result
                  : JSON.stringify(result, null, 2)}
              </pre>
            </div>
          )}
        </div>
      )}
    </div>
  );
};
```

Bind fallback UI \[#bind-fallback-ui]

```tsx title="@/app/page.tsx" {1,8}
import { ToolFallback } from "@/components/tools/ToolFallback";

export default function Home() {
  return (
    <div className="flex h-full flex-col">
      <Thread
        ...
        assistantMessage={{ components: { Text: MarkdownText, ToolFallback } }}
      />
    </div>
  );
}
```


# Part 3: Approval UI
URL: /docs/runtimes/langgraph/tutorial/part-3

Add human-in-the-loop approval for tool calls.

Background: LangGraph implementation details \[#background-langgraph-implementation-details]

import Image from "next/image";
import approval from "./images/stockbroker-langgraph.png";

<Image src={approval} alt="LangChain LangGraph" width={600} className="mx-auto rounded-lg border shadow" />

Our LangGraph backend interrupts the `purchase_stock` tool execution in order to ensure the user confirms the purchase. The user confirms the purchase by submitting a tool message with the `approve` field set to `true`.

```ts title="assistant-ui-stockbroker/backend/src/index.ts" {6,18-19,32-35}
const purchaseApproval = async (state: typeof GraphAnnotation.State) => {
  const { messages } = state;
  const lastMessage = messages[messages.length - 1];
  if (!(lastMessage instanceof ToolMessage)) {
    // Interrupt the node to request permission to execute the purchase.
    throw new NodeInterrupt("Please confirm the purchase before executing.");
  }
};

const shouldExecutePurchase = (state: typeof GraphAnnotation.State) => {
  const { messages } = state;
  const lastMessage = messages[messages.length - 1];
  if (!(lastMessage instanceof ToolMessage)) {
    // Interrupt the node to request permission to execute the purchase.
    throw new NodeInterrupt("Please confirm the purchase before executing.");
  }

  const { approve } = JSON.parse(lastMessage.content as string);
  return approve ? "execute_purchase" : "agent";
};

const workflow = new StateGraph(GraphAnnotation)
  .addNode("agent", callModel)
  .addEdge(START, "agent")
  .addNode("tools", toolNode)
  .addNode("prepare_purchase_details", preparePurchaseDetails)
  .addNode("purchase_approval", purchaseApproval)
  .addNode("execute_purchase", executePurchase)
  .addEdge("prepare_purchase_details", "purchase_approval")
  .addEdge("execute_purchase", END)
  .addEdge("tools", "agent")
  .addConditionalEdges("purchase_approval", shouldExecutePurchase, [
    "agent",
    "execute_purchase",
  ])
  .addConditionalEdges("agent", shouldContinue, [
    "tools",
    END,
    "prepare_purchase_details",
  ]);
```

Add approval UI \[#add-approval-ui]

We create a new file under `/components/tools/purchase-stock/PurchaseStockTool.tsx` to define the tool.

First, we define the tool arguments and result types:

```ts title="@/components/tools/purchase-stock/PurchaseStockTool.tsx"
type PurchaseStockArgs = {
  ticker: string;
  companyName: string;
  quantity: number;
  maxPurchasePrice: number;
};

type PurchaseStockResult = {
  approve?: boolean;
  cancelled?: boolean;
  error?: string;
};
```

Then we use `makeAssistantToolUI` to define the tool UI:

```tsx title="@/components/tools/purchase-stock/PurchaseStockTool.tsx"
"use client";

import { TransactionConfirmationPending } from "./transaction-confirmation-pending";
import { TransactionConfirmationFinal } from "./transaction-confirmation-final";
import { makeAssistantToolUI } from "@assistant-ui/react";
import { updateState } from "@/lib/chatApi";

export const PurchaseStockTool = makeAssistantToolUI<PurchaseStockArgs, string>(
  {
    toolName: "purchase_stock",
    render: function PurchaseStockUI({ args, result, status, addResult }) {
      const handleReject = async () => {
        addResult({ approve: false });
      };

      const handleConfirm = async () => {
        addResult({ approve: true });
      };

      return (
        <div className="mb-4 flex flex-col items-center gap-2">
          <div>
            <pre className="whitespace-pre-wrap break-all text-center">
              purchase_stock({JSON.stringify(args)})
            </pre>
          </div>
          {!result && status.type !== "running" && (
            <TransactionConfirmationPending
              {...args}
              onConfirm={handleConfirm}
              onReject={handleReject}
            />
          )}
        </div>
      );
    },
  },
);
```

Finally, we add a `TransactionConfirmationPending` component to ask for approval.

This requires shadcn/ui's `Card` and `Button` components. We will install them as a dependency.

<InstallCommand shadcn={["card", "button"]} />

Then create a new file under `/components/tools/purchase-stock/transaction-confirmation-pending.tsx` to define the approval UI.

```tsx title="@/components/tools/purchase-stock/transaction-confirmation-pending.tsx"
"use client";

import { CheckIcon, XIcon } from "lucide-react";

import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

type TransactionConfirmation = {
  ticker: string;
  companyName: string;
  quantity: number;
  maxPurchasePrice: number;
  onConfirm: () => void;
  onReject: () => void;
};

export function TransactionConfirmationPending(props: TransactionConfirmation) {
  const {
    ticker,
    companyName,
    quantity,
    maxPurchasePrice,
    onConfirm,
    onReject,
  } = props;

  return (
    <Card className="mx-auto w-full max-w-md">
      <CardHeader>
        <CardTitle className="text-2xl font-bold">
          Confirm Transaction
        </CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="grid grid-cols-2 gap-2">
          <p className="text-muted-foreground text-sm font-medium">Ticker:</p>
          <p className="text-sm font-bold">{ticker}</p>
          <p className="text-muted-foreground text-sm font-medium">Company:</p>
          <p className="text-sm">{companyName}</p>
          <p className="text-muted-foreground text-sm font-medium">Quantity:</p>
          <p className="text-sm">{quantity} shares</p>
          <p className="text-muted-foreground text-sm font-medium">
            Max Purchase Price:
          </p>
          <p className="text-sm">${maxPurchasePrice?.toFixed(2)}</p>
        </div>
        <div className="bg-muted rounded-md p-3">
          <p className="text-sm font-medium">Total Maximum Cost:</p>
          <p className="text-lg font-bold">
            ${(quantity * maxPurchasePrice)?.toFixed(2)}
          </p>
        </div>
      </CardContent>
      <CardFooter className="flex justify-end">
        <Button variant="outline" onClick={onReject}>
          <XIcon className="mr-2 h-4 w-4" />
          Reject
        </Button>
        <Button onClick={onConfirm}>
          <CheckIcon className="mr-2 h-4 w-4" />
          Confirm
        </Button>
      </CardFooter>
    </Card>
  );
}
```

Bind approval UI \[#bind-approval-ui]

```tsx title="@/app/page.tsx" {1,8}
import { PurchaseStockTool } from "@/components/tools/purchase-stock/PurchaseStockTool";

export default function Home() {
  return (
    <div className="flex h-full flex-col">
      <Thread
        ...
        tools={[PriceSnapshotTool, PurchaseStockTool]}
      />
    </div>
  );
}
```

Try it out! \[#try-it-out]

Ask the assistant to buy 5 shares of Tesla. You should see the following appear:

import purchase from "./images/acme-approve.png";

<Image src={purchase} alt="Approval UI" width={600} className="mx-auto rounded-lg border shadow" />

Add TransactionConfirmationFinal to show approval result \[#add-transactionconfirmationfinal-to-show-approval-result]

We will add a component to display the approval result.

```ts title="@/components/tools/purchase-stock/transaction-confirmation-final.tsx"
"use client";

import { CheckCircle } from "lucide-react";

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

type TransactionConfirmation = {
  ticker: string;
  companyName: string;
  quantity: number;
  maxPurchasePrice: number;
};

export function TransactionConfirmationFinal(props: TransactionConfirmation) {
  const { ticker, companyName, quantity, maxPurchasePrice } = props;

  return (
    <Card className="mx-auto w-full max-w-md">
      <CardHeader className="text-center">
        <CheckCircle className="mx-auto mb-4 h-16 w-16 text-green-500" />
        <CardTitle className="text-2xl font-bold text-green-700">
          Transaction Confirmed
        </CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="rounded-md border border-green-200 bg-green-50 p-4">
          <h3 className="mb-2 text-lg font-semibold text-green-800">
            Purchase Summary
          </h3>
          <div className="grid grid-cols-2 gap-2 text-sm">
            <p className="font-medium text-green-700">Ticker:</p>
            <p className="font-bold text-green-900">{ticker}</p>
            <p className="font-medium text-green-700">Company:</p>
            <p className="text-green-900">{companyName}</p>
            <p className="font-medium text-green-700">Quantity:</p>
            <p className="text-green-900">{quantity} shares</p>
            <p className="font-medium text-green-700">Price per Share:</p>
            <p className="text-green-900">${maxPurchasePrice?.toFixed(2)}</p>
          </div>
        </div>
        <div className="rounded-md border border-green-300 bg-green-100 p-4">
          <p className="text-lg font-semibold text-green-800">Total Cost:</p>
          <p className="text-2xl font-bold text-green-900">
            ${(quantity * maxPurchasePrice)?.toFixed(2)}
          </p>
        </div>
        <p className="text-center text-sm text-green-600">
          Your purchase of {quantity} shares of {companyName} ({ticker}) has
          been successfully processed.
        </p>
      </CardContent>
    </Card>
  );
}
```

Update PurchaseStockTool \[#update-purchasestocktool]

We will import the new `<TransactionConfirmationFinal />` component and use it in the `render` function whenever an approval result is available.

```tsx title="@/components/tools/purchase-stock/PurchaseStockTool.tsx" {3,25-30,37-42}
"use client";

import { TransactionConfirmationPending } from "./transaction-confirmation-pending";
import { TransactionConfirmationFinal } from "./transaction-confirmation-final";
import { makeAssistantToolUI } from "@assistant-ui/react";
import { updateState } from "@/lib/chatApi";

type PurchaseStockArgs = {
  ticker: string;
  companyName: string;
  quantity: number;
  maxPurchasePrice: number;
};

type PurchaseStockResult = {
  approve?: boolean;
  cancelled?: boolean;
  error?: string;
};

export const PurchaseStockTool = makeAssistantToolUI<PurchaseStockArgs, string>(
  {
    toolName: "purchase_stock",
    render: function PurchaseStockUI({ args, result, status, addResult }) {
      let resultObj: PurchaseStockResult;
      try {
        resultObj = result ? JSON.parse(result) : {};
      } catch (e) {
        resultObj = { error: result! };
      }

      const handleReject = () => {
        addResult({ cancelled: true });
      };

      const handleConfirm = async () => {
        addResult({ approve: true });
      };

      return (
        <div className="mb-4 flex flex-col items-center gap-2">
          <div>
            <pre className="whitespace-pre-wrap break-all text-center">
              purchase_stock({JSON.stringify(args)})
            </pre>
          </div>
          {!result && status.type !== "running" && (
            <TransactionConfirmationPending
              {...args}
              onConfirm={handleConfirm}
              onReject={handleReject}
            />
          )}
          {resultObj.approve && <TransactionConfirmationFinal {...args} />}
          {resultObj.approve === false && (
            <pre className="font-bold text-red-600">User rejected purchase</pre>
          )}
          {resultObj.cancelled && (
            <pre className="font-bold text-red-600">Cancelled</pre>
          )}
        </div>
      );
    },
  },
);
```

Try it out! \[#try-it-out-1]

Confirm the purchase of shares. You should see the approval confimration UI appear.

import purchase2 from "./images/acme-confirmed.png";

<Image src={purchase2} alt="Approval result" width={600} className="mx-auto rounded-lg border shadow" />