# Architecture
URL: /docs/architecture

How components, runtimes, and cloud services fit together.

***

title: "Architecture"
description: How components, runtimes, and cloud services fit together.
-----------------------------------------------------------------------

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

## 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

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

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

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:

#### **1. Direct Integration with External Providers**

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

#### **2. Using your own API endpoint**

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

#### **3. With Assistant Cloud**

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


# CLI
URL: /docs/cli

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

***

title: CLI
description: 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

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

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 uses `create-next-app` with assistant-ui starter templates.

**Available Templates**

| Template    | Description                          | Command                                |
| ----------- | ------------------------------------ | -------------------------------------- |
| `default`   | Basic setup with Vercel AI SDK       | `npx assistant-ui create`              |
| `cloud`     | With Assistant Cloud for persistence | `npx assistant-ui create -t cloud`     |
| `langgraph` | LangGraph integration                | `npx assistant-ui create -t langgraph` |
| `mcp`       | Model Context Protocol support       | `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-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-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 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, cloud, 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

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

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

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

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

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

### 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

```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

```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

```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

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

### 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

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

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

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

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

## 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.

***

title: DevTools
description: Inspect runtime state, context, and events in the browser.
-----------------------------------------------------------------------

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

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.

![Screenshot of the DevTools UI showing logs and state panels](../../../../../.github/assets/devtoolsui.png)

## Setup

<Steps>
  <Step>
    ### Install the DevTools package

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

  <Step>
    ### 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

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

    ![DevTools floating modal anchored in the lower-right corner of a page](../../../../../.github/assets/devtoolsmodal.png)
  </Step>
</Steps>


# Introduction
URL: /docs

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

***

title: Introduction
description: 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.

## 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

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
# Assistant Cloud - with persistence and thread management
npx assistant-ui@latest create -t cloud

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

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

## What's Next?

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

  <Card title="AI-Assisted Development" 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.

***

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

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

## Quick Start

The fastest way to get started with assistant-ui.

![animated gif showing the steps to create a new project](../../../../../.github/assets/assistant-ui-starter.gif)

<Steps>
  <Step>
    ### Initialize assistant-ui

    **Create a new project:**

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

    Or choose a template:

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

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

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

    **Add to an existing project:**

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

  <Step>
    ### Add API key

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

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

  <Step>
    ### Start the app

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

## Manual Setup

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

<Steps>
  <Step>
    ### Add assistant-ui

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

  <Step>
    ### 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"]}>
      ```ts title="/app/api/chat/route.ts" tab="OpenAI"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Anthropic"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Azure"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="AWS"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Gemini"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="GCP"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Groq"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Fireworks"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Cohere"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Ollama"
      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();
      }
      ```

      ```ts title="/app/api/chat/route.ts" tab="Chrome AI"
      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();
      }
      ```
    </Tabs>

    Define environment variables:

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

      ```sh title="/.env.local" tab="Anthropic"
      ANTHROPIC_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="Azure"
      AZURE_RESOURCE_NAME="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      AZURE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="AWS"
      AWS_ACCESS_KEY_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      AWS_REGION="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="Gemini"
      GOOGLE_GENERATIVE_AI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="GCP"
      GOOGLE_VERTEX_PROJECT="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      GOOGLE_VERTEX_LOCATION="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      GOOGLE_APPLICATION_CREDENTIALS="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="Groq"
      GROQ_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="Fireworks"
      FIREWORKS_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh title="/.env.local" tab="Cohere"
      COHERE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ```

      ```sh tab="Ollama"
      <none>
      ```

      ```sh tab="Chrome AI"
      <none>
      ```
    </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

    <Tabs items={["Thread", "AssistantModal"]}>
      ```tsx title="/app/page.tsx" tab="Thread"
      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>
        );
      };
      ```

      ```tsx title="/app/page.tsx" tab="AssistantModal"
      // 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>
        );
      };
      ```
    </Tabs>
  </Step>
</Steps>

## What's 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>


# AI-Assisted Development
URL: /docs/llm

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

***

title: "AI-Assisted Development"
description: 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

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

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

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

`@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)

```bash
npx assistant-ui mcp
```

Or specify your IDE directly:

```bash
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
```

### 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

| 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

* **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.

***

title: Using old React versions
description: Compatibility notes for React 18, 17, and 16.
----------------------------------------------------------

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

<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

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

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

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

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

<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

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


# User Authorization
URL: /docs/cloud/authorization

Configure workspace auth tokens and integrate with auth providers.

***

title: User Authorization
description: Configure workspace auth tokens and integrate with auth providers.
-------------------------------------------------------------------------------

The assistant-ui API can be directly accessed by your frontend. This elliminates the need for a backend server from your side, except for authorization of your users.

This document explains how you can setup your server to authorize users to access the assistant-ui API.

## Workspaces

Authorization is granted to a workspace. Depending on the structure of your app, you might want to use user\_ids as the workspace\_id, or you might want to use a more complex structure.
For example, if your app supports multiple "projects", you might want to use the project\_id + user\_id as the workspace id (thread history scoped to user+project pairs).

## Workspace Auth Tokens

assistant-ui issues workspace auth tokens. These tokens give access to the assistant-ui API for a specific workspace.
Tokens are short lived (5 minutes), so the client needs to periodically request a new token (handled by assistant-ui).

There are two supported approaches to obtain a workspace auth token:

* Direct integration with your auth provider
* From a backend server / serverless function

### Choosing the right approach

Direct integration with your auth provider:

* simpler to setup and maintain
* assigns a workspace\_id to every user (by using the user\_id as the workspace\_id)
* requires a supported auth provider (Clerk, Auth0, Supabase, Firebase, Stytch, Kinde, ...)

Backend server:

* more complex to setup
* more flexible workspace structure (multi-user workspaces, workspaces per project, etc.)
* supports self hosted auth solutions, e.g. Auth.js
* requires a backend server / serverless function

You can always switch between the two approaches without any downtime or necessary database migrations.
Choose direct integration with your auth provider if you can. Otherwise, use a backend server.

### Auth Provider Integration

In the AssistantUI dashboard, go to the "Auth Integrations" tab and add a new integration.
Follow the steps to add your auth provider. (See the auth providers we have guides for at the bottom of this page.)

Then, pass in a function to `authToken` that returns an ID token from your auth provider.

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

const assistantCloud = new AssistantCloud({
  authToken: () => JWT_TOKEN
});
```

### Integration with an Auth Provider

#### Backend API Endpoint

The following is an api route example to create an auth token based on an authenticated user's orgId and userId.

In the Assistant Cloud dashboard, go to the "API Keys" tab and add a new API key, add the key the environment variable `ASSISTANT_API_KEY=[KEY]`

```ts title="/app/api/assistant-ui-token/route.ts"
import { AssistantCloud } from "@assistant-ui/react";
import { auth } from "@clerk/nextjs/server";
 
export const POST = async (req: Request) => {
  const { userId, orgId } = await auth();
 
  if (!userId) throw new Error("User not authenticated");
 
  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);
};
```

#### Frontend Implementation

The following is an api route example to create an auth token based on an authenticated user's orgId and userId.

```ts title="client.ts"
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({
  api: "/api/chat",
  cloud,
});
```

### Anonymous (without auth provider) Frontend Implementation

The following is a example to get auth tokens for Clerk based on the org\_id and user\_id:

```ts title="/app/api/assistant-ui-token/route.ts"
import { AssistantCloud } from "@assistant-ui/react";

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

const runtime = useChatRuntime({
  api: "/api/chat",
  cloud,
});

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

```

### Setting up the Clerk Auth Provider

First, go to the Clerk dashboard and under "Configure" tab, "JWT Templates" section, create a new template. Choose a blank template and name it "assistant-ui".

As the "Claims" field, enter the following:

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

<Callout emoji="⚠️">
  <b>Note:</b> The aud claim ensures that the JWT is only valid for the
  assistant-ui API.
</Callout>

You can leave everything else as default. Take note of the "Issuer" and "JWKS Endpoint" fields.

Then, In the assistant-cloud dashboard, navigate to the "Auth Rules" tab and create a new rule. Choose "Clerk" and enter the Issuer and JWKS Endpoint from the previous step. As the "Audience" field, enter "assistant-ui".


# Overview
URL: /docs/cloud/overview

Hosted service for thread management, chat history, and user authentication.

***

title: Overview
description: Hosted service for thread management, chat history, and user authentication.
-----------------------------------------------------------------------------------------

Assistant Cloud is a hosted service built for assistant-ui frontends that offers comprehensive thread management and message history. It 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.

## Features

### Thread management

Using our `<ThreadList />` component, show the users a list of conversations. Allow the users to seamlessly switch between conversations and even let long running tasks run in the background.

Assistant Cloud automatically persists a list of threads and corresponding metadata. It also automatically generates a title for conversations based on the initial messages.

Supported backends:

* AI SDK
* LangGraph
* Custom

### Chat history

For every conversation, Assistant Cloud can store the history of messages, allowing the user to resume the conversation at any point in time.
This supports human in the loop workflows, where the execution of an agent is interrupted until user feedback is collected.

Supported backends:

* AI SDK
* LangGraph
* Custom (currently only Local Runtime)

### Authorization

Assistant Cloud integrates with your auth provider (Clerk, Auth0, Supabase, Firebase, ...) to identify your users and authorize them to access just the conversations they are allowed to see.

Supported auth providers:

* Clerk
* Auth0
* Supabase
* Firebase
* Your own

## Getting Started

To get started, create an account at [Assistant Cloud Dashboard](https://cloud.assistant-ui.com/) and follow one of the walkthroughs for your preferred backend:

* [AI SDK](/docs/cloud/persistence/ai-sdk)
* [LangGraph](/docs/cloud/persistence/langgraph)

You can also check out our example repositories to see how to integrate Assistant Cloud with your frontend:

* [With AI SDK](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud)
* [With LangGraph](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-langgraph)


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

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

***

title: Assistant Transport
description: 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

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

```mermaid
graph LR
    Frontend -->|Commands| Agent[Agent Server]
    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

Commands go through the following lifecycle:

```mermaid
graph LR
    queued -->|sent to backend| in_transit
    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
graph LR
    idle -->|new command| sending
    sending -->|request completes| check{check queue}
    check -->|queue has commands| sending
    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

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

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

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).

### 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

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

### 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`

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`

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

<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

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,
  onResponse?: (response: Response) => void,
  onFinish?: () => void,
  onError?: (error: Error) => void,
  onCancel?: () => void
}
```

### 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

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

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

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

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

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(),
  }),
});
```

## 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

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

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

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

<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

### 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

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

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

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

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.

***

title: Data Stream Protocol
description: Integration with data stream protocol endpoints for streaming AI responses.
----------------------------------------------------------------------------------------

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

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

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

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

## Basic Usage

<Steps>
  <Step>
    ### 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

    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

### Custom Headers and Authentication

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

### Dynamic Headers

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

### 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

```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

<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

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

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

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

### 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

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

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

### 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

```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

```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

* **[Basic Data Stream Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream)** - Simple streaming chat
* **[Tool Integration Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream-tools)** - Frontend and backend tools
* **[Authentication Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-data-stream-auth)** - Secure endpoints

## 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.

***

title: Helicone
description: 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

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)

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

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.

***

title: LangChain LangServe
description: Connect to LangServe endpoints via Vercel AI SDK integration.
--------------------------------------------------------------------------

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

## Overview

Integration with a LangServe server via Vercel AI SDK.

## Getting Started

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

<Steps>
  <Step>
    ### Create a Next.JS project

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

  <Step>
    ### Install `@langchain/core`, AI SDK and `@assistant-ui/react`

    <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`

    ```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

    ```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`

    ```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.

***

title: Picking a Runtime
description: 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

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

## 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

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

### 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

**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

### 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

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

## Common Implementation Patterns

### Vercel AI SDK with Streaming

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

export function MyAssistant() {
  const runtime = useChatRuntime({
    api: "/api/chat",
  });

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

### 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`

```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

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
* **[OpenAI Assistants Example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-openai-assistants)** - OpenAI Assistants API

## Common Pitfalls to Avoid

### 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

* **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

* **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

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>


# AssistantModal
URL: /docs/ui/assistant-modal

Floating chat bubble for support widgets and help desks.

***

title: AssistantModal
description: Floating chat bubble for support widgets and help desks.
---------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
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

<Steps>
  <Step>
    ### 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

    ```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

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

### 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

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

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

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

* [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.

***

title: AssistantSidebar
description: Side panel chat for co-pilot experiences and inline assistance.
----------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
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

<Steps>
  <Step>
    ### 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

    ```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

### 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

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

* [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.

***

title: Attachment
description: UI components for attaching and viewing files in messages.
-----------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { AttachmentSample } from "@/components/docs/samples/attachment";
import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";

<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

<Steps>
  <Step>
    ### 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

    ```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

### Composer Attachments

#### ComposerPrimitive.Attachments

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

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

#### MessagePrimitive.Attachments

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

#### AttachmentPrimitive.Root

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

Renders the attachment's file name.

#### AttachmentPrimitive.Remove

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

Attachments have the following structure:

```typescript
type Attachment = {
  id: string;
  type: "image" | "document" | "file";
  name: string;
  contentType: string;
  file?: File;
  status:
    | { type: "running" | "requires-action" | "incomplete"; progress?: number }
    | { type: "complete" };
};
```

## Related Components

* [Thread](/docs/ui/thread) - Main chat interface that displays attachments
* [Attachments Guide](/docs/guides/attachments) - Complete setup instructions for attachment adapters


# File
URL: /docs/ui/file

Display file message parts with icon, name, size, and download button.

***

title: File
description: Display file message parts with icon, name, size, and download button.
-----------------------------------------------------------------------------------

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

<FileSample />

## Getting Started

<Steps>
  <Step>
    ### Add `file`

    <InstallCommand shadcn={["file"]} />
  </Step>

  <Step>
    ### 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

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

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

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     |

## 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

Pass `children` to `File.Icon` to override the default MIME type icon:

```tsx
<File.Icon>
  <MyCustomIcon className="size-5" />
</File.Icon>
```

## 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

* [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.

***

title: Image
description: Display image message parts with preview, loading states, and fullscreen dialog.
---------------------------------------------------------------------------------------------

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

<ImageSample />

## Getting Started

<Steps>
  <Step>
    ### Add `image`

    <InstallCommand shadcn={["image"]} />
  </Step>

  <Step>
    ### 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

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

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
```

## 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

* [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.

***

title: Markdown
description: Display rich text with headings, lists, links, and code blocks.
----------------------------------------------------------------------------

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

<MarkdownSample />

<Callout>
  Markdown support is already included by default in the `Thread` component.
</Callout>

## Enabling markdown support

<Steps>
  <Step>
    ### 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

    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 is not included by default, see [Syntax Highlighting](/docs/ui/syntax-highlighting) to learn how to add it.

## 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.

***

title: "Mermaid Diagrams"
description: Render Mermaid diagrams in chat messages with streaming support.
-----------------------------------------------------------------------------

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

<MermaidSample />

## Getting Started

<Steps>
  <Step>
    ### 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`

    ```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

Configure mermaid options in `mermaid-diagram.tsx`:

```tsx title="/components/assistant-ui/mermaid-diagram.tsx"
mermaid.initialize({ theme: "default" });
```

## 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

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

* [Markdown](/docs/ui/markdown) - Rich text rendering where mermaid is integrated
* [Syntax Highlighting](/docs/ui/syntax-highlighting) - Code highlighting for other languages


# ModelSelector
URL: /docs/ui/model-selector

Model picker with unified overlay positioning and runtime integration.

***

title: ModelSelector
description: Model picker with unified overlay positioning and runtime integration.
-----------------------------------------------------------------------------------

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
import { ParametersTable } from "@/components/docs/tables/ParametersTable";
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

<Steps>
  <Step>
    ### Add `model-selector`

    <InstallCommand shadcn={["model-selector"]} />
  </Step>

  <Step>
    ### 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

    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

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

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

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

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`.

## 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 |

## API Reference

### 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

<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.

***

title: Message Part Grouping
description: Organize message parts into custom groups with flexible grouping functions.
----------------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
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

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

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

### 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

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

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

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

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

When using assistant-stream libraries, you can add custom metadata to parts:

### 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
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

### MessagePrimitive.Unstable\_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

```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

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

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

### 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

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

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(({ message }) => 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.

***

title: Reasoning
description: Collapsible UI for displaying AI reasoning and thinking messages.
------------------------------------------------------------------------------

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
import { ReasoningSample, ReasoningGroupSample } from "@/components/docs/samples/reasoning";

<ReasoningSample />

## Getting Started

<Steps>
  <Step>
    ### Add `reasoning`

    <InstallCommand shadcn={["reasoning"]} />

    This adds a `/components/assistant-ui/reasoning.tsx` file to your project.
  </Step>

  <Step>
    ### 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

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

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` 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(({ message }) => {
    if (message.status?.type !== "running") return false;
    const lastIndex = message.parts.length - 1;
    if (lastIndex < 0) return false;
    const lastType = 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>
  );
};
```

## 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

* [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.

***

title: Custom Scrollbar
description: Replace the default scrollbar with a custom Radix UI scroll area.
------------------------------------------------------------------------------

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

<ScrollbarSample />

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

<InstallCommand shadcn={["scroll-area"]} />

## 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;
}
```

## Integration

* Wrap `Thread.Root` with `<ScrollAreaPrimitive.Root asChild>`
* Wrap `Thread.Viewport` with `<ScrollAreaPrimitive.Viewport className="thread-viewport" asChild>`
* Add shadcn's `<ScrollBar />` to `Thread.Root`

The resulting MyThread component should look like this:

```tsx {1-2,6,8,12-13,15}
import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
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>
  );
};
```

## 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.

***

title: Select
description: A dropdown select component with composable sub-components.
------------------------------------------------------------------------

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import {
  SelectSample,
  SelectDisabledItemsSample,
  SelectPlaceholderSample,
  SelectDisabledSample,
  SelectGroupsSample,
  SelectVariantsSample,
  SelectSizesSample,
  SelectScrollableSample,
} from "@/components/docs/samples/select";

A styled select component built on Radix UI Select primitives. Provides a convenient options-based API and composable sub-components for custom layouts.

<Callout>
  This is a **standalone component** that does not depend on the assistant-ui runtime. Use it anywhere in your application.
</Callout>

<SelectSample />

## Installation

<InstallCommand shadcn={["select"]} />

## 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

### 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

Use the `size` prop on `SelectTrigger` to change the height.

<SelectSizesSample />

```tsx
<SelectTrigger size="default" /> // 36px (default)
<SelectTrigger size="sm" />      // 32px
```

### Scrollable

Long lists automatically become scrollable.

<SelectScrollableSample />

### Groups

Use the composable API for grouped options:

<SelectGroupsSample />

```tsx
import {
  SelectRoot,
  SelectTrigger,
  SelectContent,
  SelectItem,
  SelectGroup,
  SelectLabel,
  SelectSeparator,
  SelectValue,
} from "@/components/assistant-ui/select";

export function FrameworkPicker() {
  const [value, setValue] = useState("react");

  return (
    <SelectRoot value={value} onValueChange={setValue}>
      <SelectTrigger className="w-48">
        <SelectValue placeholder="Select a framework..." />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          <SelectLabel>Frontend</SelectLabel>
          <SelectItem value="react">React</SelectItem>
          <SelectItem value="vue">Vue</SelectItem>
          <SelectItem value="svelte">Svelte</SelectItem>
        </SelectGroup>
        <SelectSeparator />
        <SelectGroup>
          <SelectLabel>Backend</SelectLabel>
          <SelectItem value="node">Node.js</SelectItem>
          <SelectItem value="python">Python</SelectItem>
        </SelectGroup>
      </SelectContent>
    </SelectRoot>
  );
}
```

### Disabled Items

<SelectDisabledItemsSample />

```tsx
<Select
  value={value}
  onValueChange={setValue}
  options={[
    { value: "free", label: "Free" },
    { value: "pro", label: "Pro" },
    { value: "enterprise", label: "Enterprise", disabled: true },
  ]}
/>
```

### With Placeholder

<SelectPlaceholderSample />

```tsx
<Select
  value={value}
  onValueChange={setValue}
  options={options}
  placeholder="Choose an option..."
/>
```

### Disabled Select

<SelectDisabledSample />

```tsx
<Select
  value={value}
  onValueChange={setValue}
  options={options}
  disabled
/>
```

## API Reference

### Select

<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

<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.",
  },
]}
/>

### Composable API

| Component                | Description                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `SelectRoot`             | The root component that manages state.                                                                                                      |
| `SelectTrigger`          | The button that opens the dropdown. Accepts `variant` (`"outline"` \| `"ghost"` \| `"muted"`) and `size` (`"default"` \| `"sm"` \| `"lg"`). |
| `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.                                                                                                            |


# Sources
URL: /docs/ui/sources

Display URL sources with favicon, title, and external link.

***

title: Sources
description: Display URL sources with favicon, title, and external link.
------------------------------------------------------------------------

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

<SourcesSample />

## Getting Started

<Steps>
  <Step>
    ### Add `sources`

    <InstallCommand shadcn={["sources"]} />
  </Step>

  <Step>
    ### 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

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

Use the `size` prop to change the size.

```tsx
<Source size="sm" />      // Small
<Source size="default" /> // Default
<Source size="lg" />      // Large
```

## 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

* [PartGrouping](/docs/ui/part-grouping) - Group sources by parentId


# Syntax Highlighting
URL: /docs/ui/syntax-highlighting

Code block syntax highlighting with react-shiki or react-syntax-highlighter.

***

title: Syntax Highlighting
description: Code block syntax highlighting with react-shiki or react-syntax-highlighter.
-----------------------------------------------------------------------------------------

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
import { SyntaxHighlightingSample } from "@/components/docs/samples/syntax-highlighting";

<SyntaxHighlightingSample />

<Callout type="warn">Syntax highlighting is not enabled in markdown by default.</Callout>

<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

<Steps>
  <Step>
    #### 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`

    ```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

<TypeTable
  type={Object.fromEntries(
  Object.entries({
    theme: {
      description:
        "Shiki built-in or custom textmate themes. Accepts a single theme or an object of themes mapped to theme mode strings.",
      type: "Theme | Themes",
      typeDescriptionLink:
        "https://github.com/AVGVSTVS96/react-shiki/blob/694433ef697c9791b3816cf94d12d571e8abbb3a/package/src/types.ts#L51",
      default: "github-dark",
      required: true,
    },
    language: {
      description:
        "Shiki built-in or custom textmate grammar object for highlighting",
      type: "Language (string | object)",
      typeDescriptionLink:
        "https://github.com/AVGVSTVS96/react-shiki/blob/694433ef697c9791b3816cf94d12d571e8abbb3a/package/src/types.ts#L24",
      default: "text",
      required: true,
    },
    as: {
      description: "The code block container element type",
      type: "React.ElementType",
      default: "pre",
    },
    className: {
      description: "Custom CSS classes for the code block container element",
      type: "string",
      default: "",
    },
    style: {
      description: "Inline styles for the code block container element",
      type: "React.CSSProperties",
      default: undefined,
    },
    delay: {
      description:
        "Delay in milliseconds between consecutive highlights, useful for streamed code responses.",
      type: "number",
      default: 0,
    },
    customLanguages: {
      description: "Custom languages to preload for highlighting",
      type: "Language[]",
      typeDescriptionLink:
        "https://github.com/AVGVSTVS96/react-shiki/blob/694433ef697c9791b3816cf94d12d571e8abbb3a/package/src/types.ts#L24",
      default: "",
    },
    codeToHastOptions: {
      description: "All other options supported by Shiki's `codeToHast`",
      type: "CodeToHastOptions",
      typeDescriptionLink:
        "https://github.com/shikijs/shiki/blob/main/packages/types/src/options.ts#L121",
      default: "{}",
      required: true,
    },
    // This reverts the order of the type table, fumadocs reversed the order on 4/22/25 in:
    // https://github.com/fuma-nama/fumadocs/commit/3a5595aa65acfa5c20be2377d09c03fbb1de72a6
  }).reverse(),
)}
/>

### 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

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>

### Dual/multi theme support

To use multiple theme modes, pass an object with your multi-theme configuration to the `theme` prop in the `ShikiHighlighter` component:

```tsx title="/components/assistant-ui/shiki-highlighter.tsx"
<ShikiHighlighter
  /* ... */
  theme={{
    light: "github-light",
    dark: "github-dark",
  }}
  /* ... */
>
```

To make themes responsive to your site's theme mode, add one of the following CSS snippets to your project:

```css title="shiki.css"
/* for class based dark mode */
html.dark .shiki,
html.dark .shiki span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
  /* Optional, if you also want font styles */
  font-style: var(--shiki-dark-font-style) !important;
  font-weight: var(--shiki-dark-font-weight) !important;
  text-decoration: var(--shiki-dark-text-decoration) !important;
}

/* for query based dark mode */
@media (prefers-color-scheme: dark) {
  .shiki,
  .shiki span {
    color: var(--shiki-dark) !important;
    background-color: var(--shiki-dark-bg) !important;
    /* Optional, if you also want font styles */
    font-style: var(--shiki-dark-font-style) !important;
    font-weight: var(--shiki-dark-font-weight) !important;
    text-decoration: var(--shiki-dark-text-decoration) !important;
  }
}
```

For more information, see [Shiki's documentation on dual and multi themes](https://shiki.style/guide/dual-themes).

***

## 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`

    <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`

    ```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

Supports all options from [`react-syntax-highlighter`](https://github.com/react-syntax-highlighter/react-syntax-highlighter#props).

### Bundle Optimization

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

* [Markdown](/docs/ui/markdown) - Rich text rendering that uses syntax highlighting
* [Mermaid](/docs/ui/mermaid) - Render diagrams instead of code blocks


# ThreadList
URL: /docs/ui/thread-list

Switch between conversations. Supports sidebar or dropdown layouts.

***

title: ThreadList
description: Switch between conversations. Supports sidebar or dropdown layouts.
--------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
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

<Steps>
  <Step>
    ### Add the component

    Use `threadlist-sidebar` for a complete sidebar layout or `thread-list` for custom layouts.

    #### ThreadListSidebar

    <InstallCommand shadcn={["threadlist-sidebar"]} />

    #### ThreadList

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

  <Step>
    ### 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

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

### ThreadListPrimitive.Root

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

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

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

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

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

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

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

A button to restore an archived thread.

### ThreadListItemPrimitive.Delete

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.",
  },
]}
/>

### ThreadListItemMore

A dropdown menu for additional thread actions, built on Radix UI DropdownMenu:

* `ThreadListItemMorePrimitive.Root` - Menu container
* `ThreadListItemMorePrimitive.Trigger` - Button to open the menu
* `ThreadListItemMorePrimitive.Content` - Menu content container
* `ThreadListItemMorePrimitive.Item` - Individual menu item
* `ThreadListItemMorePrimitive.Separator` - Visual separator between items

## 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.

***

title: Thread
description: The main chat container with messages, composer, and auto-scroll.
------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
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

The Thread component is built with the following primitives:

```tsx
import { ThreadPrimitive, AuiIf } from "@assistant-ui/react";

<ThreadPrimitive.Root>
  <ThreadPrimitive.Viewport>
    <ThreadPrimitive.Empty />
    <ThreadPrimitive.Messages
      components={{
        EditComposer,
        UserMessage,
        AssistantMessage,
      }}
    />
    <ThreadPrimitive.ScrollToBottom />
  </ThreadPrimitive.Viewport>
  <ThreadPrimitive.Suggestion />
  <AuiIf condition={...} />
</ThreadPrimitive.Root>
```

## Getting Started

<Steps>
  <Step>
    ### 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

    ```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

### Welcome Screen

```tsx
<AuiIf condition={({ thread }) => thread.isEmpty}>
  <ThreadWelcome />
</AuiIf>
```

### Viewport Spacer

```tsx
<AuiIf condition={({ thread }) => !thread.isEmpty}>
  <div className="min-h-8 grow" />
</AuiIf>
```

### Conditional Send/Cancel Button

```tsx
<AuiIf condition={({ thread }) => !thread.isRunning}>
  <ComposerPrimitive.Send>
    Send
  </ComposerPrimitive.Send>
</AuiIf>

<AuiIf condition={({ thread }) => thread.isRunning}>
  <ComposerPrimitive.Cancel>
    Cancel
  </ComposerPrimitive.Cancel>
</AuiIf>
```

### Suggestions

```tsx
<ThreadPrimitive.Suggestion
  prompt="What's the weather in San Francisco?"
  send
/>
```

## API Reference

The following primitives are used within the Thread component and can be customized in your `/components/assistant-ui/thread.tsx` file.

### 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

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

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

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

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

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.

### Suggestion

Shows a suggestion to the user. When clicked, replaces the composer's value with the suggestion and optionally sends it.

```tsx
<ThreadPrimitive.Suggestion
  prompt="Tell me about React hooks"
  send
/>
```

<ParametersTable
  type="ThreadPrimitiveSuggestionProps"
  parameters={[
  {
    name: "prompt",
    type: "string",
    required: true,
    description: "The suggestion text to use when clicked.",
  },
  {
    name: "send",
    type: "boolean",
    description:
      "When true, automatically sends the message. When false, replaces or appends the composer text with the suggestion - depending on the value of `clearComposer`",
  },
  {
    name: "clearComposer",
    type: "boolean",
    default: "true",
    description:
      "Whether to clear the composer after sending. When send is set to false, determines if composer text is replaced with suggestion (true, default), or if the suggestion's prompt is appended to the composer text (false).",
  },
  {
    name: "autoSend",
    type: "boolean",
    deprecated: true,
    description: "Deprecated. Use 'send' instead.",
  },
  {
    name: "method",
    type: "'replace'",
    deprecated: true,
    description: "Deprecated. This parameter is no longer used.",
  },
  {
    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.

### 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={({ thread }) => thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>

<AuiIf condition={({ thread }) => thread.isRunning}>
  <LoadingIndicator />
</AuiIf>

<AuiIf condition={({ message }) => 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

* [ThreadList](/docs/ui/thread-list) - List of threads, with or without sidebar


# ToolFallback
URL: /docs/ui/tool-fallback

Default UI component for tools without dedicated custom renderers.

***

title: ToolFallback
description: Default UI component for tools without dedicated custom renderers.
-------------------------------------------------------------------------------

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
import {
  ToolFallbackSample,
  ToolFallbackRunningSample,
  ToolFallbackCancelledSample,
  ToolFallbackStreamingSample,
} from "@/components/docs/samples/tool-fallback";

<ToolFallbackSample />

## Getting Started

<Steps>
  <Step>
    ### 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

    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

### Streaming Demo

Interactive demo showing the full tool call lifecycle: running → complete.

<ToolFallbackStreamingSample />

### Running State

Shows a loading spinner and shimmer animation while the tool is executing.

<ToolFallbackRunningSample />

### Cancelled State

Shows a muted appearance when a tool call was cancelled.

<ToolFallbackCancelledSample />

## 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

* [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.

***

title: ToolGroup
description: Wrapper for consecutive tool calls with collapsible and styled options.
------------------------------------------------------------------------------------

import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
import { ParametersTable } from "@/components/docs/tables/ParametersTable";
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

<Steps>
  <Step>
    ### 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

    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

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

### 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

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

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

### 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

<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)

<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

* [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

***

title: Assistant Frame API
description: 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

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

### 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)

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

### 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

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

#### 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

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

### AssistantFrameProvider

Static class that manages model context providers in an iframe.

#### Methods

##### `addModelContextProvider(provider, 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()`

Cleans up all resources and removes all providers.

```tsx
AssistantFrameProvider.dispose();
```

### AssistantFrameHost

Class that connects to an iframe's model context providers.

#### Constructor

```tsx
const host = new AssistantFrameHost(
  iframeWindow,
  targetOrigin? // Optional origin restriction
);
```

#### Methods

##### `getModelContext()`

Returns the current merged model context from the iframe.

```tsx
const context = host.getModelContext();
// { system: "...", tools: { ... } }
```

##### `subscribe(callback)`

Subscribes to model context changes.

```tsx
const unsubscribe = host.subscribe(() => {
  console.log("Context updated:", host.getModelContext());
});
```

##### `dispose()`

Cleans up the connection to the iframe.

```tsx
host.dispose();
```

### useAssistantFrameHost

React hook that manages the lifecycle of an AssistantFrameHost.

```tsx
useAssistantFrameHost({
  iframeRef: RefObject<HTMLIFrameElement>,
  targetOrigin?: string,
});
```

### ModelContextRegistry

A flexible registry for managing model context with dynamic updates.

#### Methods

##### `addTool(tool)`

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)`

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)`

Adds another model context provider.

```tsx
const handle = registry.addProvider(anotherProvider);
handle.remove(); // Remove provider
```

## Use Cases

### 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

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

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.

***

title: makeAssistantVisible
description: 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

```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

### Parameters

* `Component`: The base React component to enhance
* `config`: Optional configuration object
  * `clickable`: When true, enables the assistant to programmatically click the component

### 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

```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

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.

***

title: makeAssistantToolUI
description: Register custom UI components to render tool executions and their status.
--------------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

The `makeAssistantToolUI` utility is used to register a tool UI component with the Assistant.

## Usage

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

const MyToolUI = makeAssistantToolUI({
  toolName: "myTool",
  render: ({ args, result, status }) => {
    // render your tool UI here
  },
});
```

## API

### 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

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

```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.

***

title: makeAssistantTool
description: Create React components that provide reusable tools to the assistant.
----------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

`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

```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

### 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 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

```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

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.

***

title: Model Context
description: 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

### 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 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

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

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

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.

***

title: Intelligent Components
description: 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

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

With assistant-ui, we can enhance this component with intelligence using four powerful APIs:

### 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)

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)

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)

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

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

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.

***

title: useAssistantInstructions
description: 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

```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

### 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

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

```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.

***

title: Attachments
description: Let users attach files, images, and documents to messages.
-----------------------------------------------------------------------

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

Enable users to attach files to their messages, enhancing conversations with images, documents, and other content.

<AttachmentSample />

## 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

<Steps>
  <Step>
    ### 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)

    For `useChatRuntime`, attachments work automatically without additional configuration:

    ```tsx title="/app/MyRuntimeProvider.tsx"
    import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

    const runtime = useChatRuntime({
      api: "/api/chat",
    });
    ```

    <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

    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

### 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

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

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

Build your own adapters for specialized file handling. Below are complete examples for common use cases.

### 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

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

### 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

### 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

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
  }
}
```

### 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

### With Vercel AI SDK

Attachments are sent to the backend as file content parts.

## 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

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

* [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.

***

title: Message Branching
description: 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

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

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
```


# Context API
URL: /docs/guides/context-api

Read and update assistant state to build custom components.

***

title: Context API
description: 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

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

### 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(({ message }) => message.role);

  // ✅ Available: thread scope (parent)
  const isRunning = useAuiState(({ thread }) => thread.isRunning);
}
```

### 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

### 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(({ message }) => message.role); // "user" | "assistant"
const isRunning = useAuiState(({ thread }) => thread.isRunning); // boolean

// Access nested data
const attachmentCount = useAuiState(
  ({ composer }) => composer.attachments.length,
);
const lastMessage = useAuiState(({ thread }) => 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(
  ({ thread, composer }) => !thread.isRunning && composer.text.length > 0,
);

// Compute derived state
const messageCount = useAuiState(({ thread }) => 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(({ message }) => ({
  role: message.role,
  content: message.content,
}));

// ✅ Good - returns stable values
const role = useAuiState(({ message }) => message.role);
const content = useAuiState(({ message }) => message.content);
```

### 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);
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

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

### 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

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

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

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

### Conditional Rendering

```tsx
function RunIndicator() {
  const isRunning = useAuiState(({ thread }) => thread.isRunning);

  if (!isRunning) return null;
  return <div>Assistant is thinking...</div>;
}
```

### 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

```tsx
function SmartComposer() {
  const aui = useAui();
  const isRunning = useAuiState(({ thread }) => thread.isRunning);
  const text = useAuiState(({ composer }) => 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

```tsx
function MessageCounter() {
  const [sendCount, setSendCount] = useState(0);

  useAuiEvent("composer.send", () => {
    setSendCount((c) => c + 1);
  });

  return <div>Messages sent: {sendCount}</div>;
}
```

## Advanced Topics

### 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

**Selector optimization:**

```tsx
// ❌ Expensive computation in selector (runs on every store update)
const result = useAuiState(
  ({ thread }) => thread.messages.filter((m) => m.role === "user").length,
);

// ✅ Memoize expensive computations
const messages = useAuiState(({ thread }) => 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(({ thread }) => thread);

// ✅ Subscribe only to needed values
const isRunning = useAuiState(({ thread }) => thread.isRunning);
```

## API Reference

### 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          | 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

| 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)`, `reset()`           | Text input and message composition        |
| Part           | `addResult(result)`, `getState()`                                     | Tool call result handling                 |
| Attachment     | `remove()`, `getState()`                                              | File management                           |

### 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

### Common Errors

**"Cannot access \[scope] outside of \[scope] context"**

```tsx
// ❌ This will throw if not inside a message component
const role = useAuiState(({ message }) => message.role);

// ✅ Check scope availability first
function SafeMessageButton() {
  const aui = useAui();

  const role = useAuiState(({ message }) =>
    api.message.source !== undefined ? 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(({ message }) => ({
  role: message.role,
  content: message.content, // New object every time!
}));

// ✅ Return primitive values or use separate selectors
const role = useAuiState(({ message }) => message.role);
const content = useAuiState(({ message }) => 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

```tsx
// Read state
const value = useAuiState(({ scope }) => 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

***

## title: Speech-to-Text (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

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

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

const runtime = useChatRuntime({
  api: "/api/chat",
  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

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

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

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

You can create custom adapters to integrate with any dictation service by implementing the `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

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

[ElevenLabs Scribe](https://elevenlabs.io/docs/capabilities/speech-to-text) provides ultra-low latency (\~150ms) real-time transcription via WebSocket.

#### Install Dependencies

```bash
npm install @elevenlabs/client
```

#### 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

```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

```tsx
const runtime = useChatRuntime({
  api: "/api/chat",
  adapters: {
    dictation: new ElevenLabsScribeAdapter({
      tokenEndpoint: "/api/scribe-token",
      languageCode: "en", // Optional: supports 90+ languages
      disableInputDuringDictation: true, // Default: true (recommended for ElevenLabs)
    }),
  },
});
```

#### 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.

***

title: Message Editing
description: Allow users to edit their messages with custom editor interfaces.
------------------------------------------------------------------------------

Give the user the ability to edit their message.

## 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.

***

title: LaTeX
description: 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

    ```bash
    npm i katex rehype-katex remark-math
    ```
  </Step>

  <Step>
    ### Add KaTeX CSS to your layout

    ```tsx title="/app/layout.tsx"
    import "katex/dist/katex.min.css"; // [!code ++]
    ```
  </Step>

  <Step>
    ### Update `markdown-text.tsx`

    ```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

By default, remark-math supports:

* `$...$` for inline math
* `$$...$$` for display math
* Fenced code blocks with the `math` language identifier

## 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>


# Text-to-Speech (Speech Synthesis)
URL: /docs/guides/speech

Read messages aloud with Web Speech API or custom TTS.

***

title: Text-to-Speech (Speech Synthesis)
description: 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

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

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

The following example uses the `WebSpeechSynthesisAdapter`.

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

const runtime = useChatRuntime({
  api: "/api/chat",
  adapters: {
    speech: new WebSpeechSynthesisAdapter(),
  },
});
```


# Generative UI
URL: /docs/guides/tool-ui

Render tool calls as interactive UI instead of plain text.

***

title: Generative UI
description: 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

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

There are two main approaches to creating tool UIs in assistant-ui:

### 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`)

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

This example shows how to implement the UI-only approach using `makeAssistantToolUI`:

<Steps>
  <Step>
    ### 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

    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)

    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

### 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

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

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

### 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

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

### 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

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

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

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

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

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

### 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

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

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

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

* [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.

***

title: Tools
description: 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

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>

## Tool Creation Methods

assistant-ui offers multiple ways to create and register tools, each suited for different use cases:

* **`makeAssistantTool`**: Register client-defined tools with the assistant context
* **`useAssistantTool`**: Hook-based dynamic tool registration
* **`makeAssistantToolUI`**: UI-only components for existing tools
* **Direct context registration**: Advanced registration with full model context control

### 1. Using `makeAssistantTool`

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

// Define the tool
const weatherTool = tool({
  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 }) => {
    // Tool execution logic
    const weather = await fetchWeatherAPI(location, unit);
    return weather;
  },
});

// Create the component
const WeatherTool = makeAssistantTool({
  ...weatherTool,
  toolName: "getWeather",
});

// Place the tool component inside AssistantRuntimeProvider
function App() {
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <WeatherTool />
      <Thread />
    </AssistantRuntimeProvider>
  );
}
```

<Callout type="tip">
  When using server-side runtimes like Vercel AI SDK, you can pass
  client-defined tools to your backend using `frontendTools`. See the
  [Client-Defined Tools with
  frontendTools](#client-defined-tools-with-frontendtools) section below.
</Callout>

### 2. Using `useAssistantTool` Hook

Register tools dynamically using React hooks. Useful for conditional tools or when tool availability depends on component state:

```tsx
import { useAssistantTool } from "@assistant-ui/react";
import { z } from "zod";

function DynamicTools() {
  const [dataSource, setDataSource] = useState<"local" | "cloud">("local");

  useAssistantTool({
    toolName: "searchData",
    description: "Search through the selected data source",
    parameters: z.object({
      query: z.string(),
    }),
    execute: async ({ query }) => {
      if (dataSource === "local") {
        return await searchLocalDatabase(query);
      } else {
        return await searchCloudDatabase(query);
      }
    },
    // Re-register when data source changes
    enabled: true,
  });

  return null;
}
```

### 3. Using `makeAssistantToolUI`

Create generative UI components for tools that are defined elsewhere. This is UI-only - the tool's execution logic must be registered separately (e.g., in your backend, MCP server, or another component):

<Callout type="note">
  This creates only the UI component. The actual tool execution happens where
  you've defined it (typically in your API route with server-based runtimes like
  Vercel AI SDK).
</Callout>

```tsx
import { makeAssistantToolUI, AssistantToolUI } from "@assistant-ui/react";

const SearchResultsUI = makeAssistantToolUI<
  {
    query: string;
  },
  {
    results: Array<{
      id: string;
      url: string;
      title: string;
      snippet: string;
    }>;
  }
>({
  toolName: "webSearch", // Must match the registered tool's name
  render: ({ args, result }) => {
    return (
      <div className="search-results">
        <h3>Search: {args.query}</h3>
        {result.results.map((item) => (
          <div key={item.id}>
            <a href={item.url}>{item.title}</a>
            <p>{item.snippet}</p>
          </div>
        ))}
      </div>
    );
  },
});

// Place the tool component inside AssistantRuntimeProvider
function App() {
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <SearchResultsUI />
      <Thread />
    </AssistantRuntimeProvider>
  );
}
```

### 4. Advanced: Direct Context Registration

Use `aui.modelContext().register()` when you need to configure more than just tools:

```tsx
import { tool, useAui } from "@assistant-ui/react";
import { useEffect, useState } from "react";
import { z } from "zod";

function MyComponent() {
  const aui = useAui();
  const [isCreativeMode, setIsCreativeMode] = useState(false);

  useEffect(() => {
    const calculateTool = tool({
      description: "Perform mathematical calculations",
      parameters: z.object({
        expression: z.string(),
      }),
      execute: async ({ expression }) => {
        return eval(expression); // Note: Use proper math parser in production
      },
    });

    // Register tools with model configuration
    return aui.modelContext().register({
      getModelContext: () => ({
        tools: { calculate: calculateTool },
        callSettings: {
          temperature: isCreativeMode ? 0.9 : 0.2,
          maxTokens: 1000,
        },
        priority: 10, // Higher priority overrides other providers
      }),
    });
  }, [api, isCreativeMode]);

  return <div>{/* Your component */}</div>;
}
```

Use this approach when you need:

* Dynamic model parameters (temperature, maxTokens, etc.)
* Priority-based context merging
* Multiple context types in one registration

## Tool Paradigms

### Frontend Tools

Tools that execute in the browser, accessing client-side resources:

```tsx
const screenshotTool = tool({
  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 };
  },
});

const ScreenshotTool = makeAssistantTool({
  ...screenshotTool,
  toolName: "screenshot",
});
```

### Backend Tools

Tools that trigger server-side operations:

```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 }) => {
          // Server-side database access
          const results = await db.query(query, { table });
          return results;
        },
      },
    },
  });

  return result.toUIMessageStreamResponse();
}
```

### Client-Defined Tools with frontendTools

Currently, the Vercel AI SDK adapter implements automatic serialization of client-defined tools. When using this adapter, tools registered via `makeAssistantTool`, `useAssistantTool`, or `registerModelContextProvider` are automatically included in API requests. The `frontendTools` utility helps you use these tools server-side:

```tsx
// Frontend: Define tool with makeAssistantTool
import { makeAssistantTool, tool } from "@assistant-ui/react";

const calculateTool = tool({
  description: "Perform calculations",
  parameters: z.object({
    expression: z.string(),
  }),
  execute: async ({ expression }) => {
    return eval(expression); // Note: Use proper math parser in production
  },
});

const CalculateTool = makeAssistantTool({
  ...calculateTool,
  toolName: "calculate",
});

// 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 application database",
        inputSchema: zodSchema(z.object({ query: z.string() })),
        execute: async ({ query }) => {
          return await db.query(query);
        },
      },
    },
  });

  return result.toUIMessageStreamResponse();
}
```

<Callout type="note">
  The `frontendTools` utility is currently only available for the Vercel AI SDK
  integration. Other adapters like LangGraph follow a server-side tool
  definition model and don't yet implement client tool serialization. Learn more
  in the [Vercel AI SDK integration guide](/docs/runtimes/ai-sdk/use-chat-hook).
</Callout>

### Human-in-the-Loop Tools

Tools that require human approval or input:

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

const refundTool = tool({
  description: "Process a customer refund",
  parameters: z.object({
    orderId: z.string(),
    amount: z.number(),
    reason: z.string(),
  }),
  execute: async ({ orderId, amount, reason }) => {
    // Wait for human approval
    const approved = await requestHumanApproval({
      action: "refund",
      details: { orderId, amount, reason },
    });

    if (!approved) {
      throw new Error("Refund rejected by administrator");
    }

    return await processRefund(orderId, amount);
  },
});

const RefundTool = makeAssistantTool({
  ...refundTool,
  toolName: "requestRefund",
});
```

### Tool Human Input

Tools can pause their execution to request user input or approval before continuing. This is useful for:

* Requesting user confirmation for sensitive operations
* Collecting additional information mid-execution
* Implementing progressive disclosure workflows
* Building interactive, multi-step tool experiences

```tsx
import { makeAssistantTool, tool } from "@assistant-ui/react";
import { z } from "zod";

const confirmationTool = tool({
  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",
        message: "Email sending cancelled by user",
      };
    }

    // Proceed with sending the email
    await sendEmail({ to, subject, body });
    return { status: "sent", message: `Email sent to ${to}` };
  },
});

const EmailTool = makeAssistantTool({
  ...confirmationTool,
  toolName: "sendEmail",
  render: ({ args, result, interrupt, resume }) => {
    // The interrupt payload is available when the tool is waiting for user input
    if (interrupt) {
      return (
        <div className="confirmation-dialog">
          <h3>Confirm Email</h3>
          <p>Send email to: {interrupt.payload.details.to}</p>
          <p>Subject: {interrupt.payload.details.subject}</p>
          <div className="actions">
            <button onClick={() => resume(true)}>Confirm</button>
            <button onClick={() => resume(false)}>Cancel</button>
          </div>
        </div>
      );
    }

    // Show the result after completion
    if (result) {
      return (
        <div className="email-result">
          <p>{result.message}</p>
        </div>
      );
    }

    // Show loading state
    return <div>Preparing email...</div>;
  },
});
```

#### Human Input Behavior

* **Payload**: The object passed to `human()` is available in the `render` function as `interrupt.payload`
* **Type**: The `interrupt` object has the structure `{ type: "human", payload: ... }`
* **Resume**: Call `resume(payload)` to continue execution - the payload becomes the resolved value of the `human()` call
* **Multiple Requests**: If `human()` is called multiple times, previous requests are automatically rejected with an error
* **Cancellation**: If the tool execution is aborted (e.g., user cancels the message), all pending requests are rejected

#### Advanced Human Input Patterns

You can use human input for complex multi-step interactions:

```tsx
const wizardTool = tool({
  description: "Multi-step data processing wizard",
  parameters: z.object({
    dataSource: z.string(),
  }),
  execute: async ({ dataSource }, { human }) => {
    // Step 1: Load data
    const data = await loadData(dataSource);

    // Step 2: Request user to select columns
    const selectedColumns = await human({
      type: "column-selection",
      availableColumns: data.columns,
    });

    // Step 3: Request processing options
    const options = await human({
      type: "processing-options",
      columns: selectedColumns,
    });

    // Step 4: Process data with user selections
    const result = await processData(data, selectedColumns, options);
    return result;
  },
});

const WizardTool = makeAssistantTool({
  ...wizardTool,
  toolName: "dataWizard",
  render: ({ args, result, interrupt, resume }) => {
    if (interrupt?.payload.type === "column-selection") {
      return (
        <ColumnSelector
          columns={interrupt.payload.availableColumns}
          onSelect={(cols) => resume(cols)}
        />
      );
    }

    if (interrupt?.payload.type === "processing-options") {
      return (
        <ProcessingOptions
          columns={interrupt.payload.columns}
          onConfirm={(opts) => resume(opts)}
        />
      );
    }

    if (result) {
      return <ResultDisplay data={result} />;
    }

    return <div>Loading...</div>;
  },
});
```

<Callout type="note">
  When a tool calls `human()` multiple times (e.g., for multi-step
  workflows), each new request automatically rejects any previous pending
  request. Make sure to handle potential errors if you need to support
  cancellation of earlier steps.
</Callout>

### MCP (Model Context Protocol) Tools

Integration with MCP servers using AI SDK v5's experimental MCP support:

<Callout type="warning">
  MCP support in AI SDK v5 is experimental. The API may change in future
  releases. Make sure to install the MCP SDK: `npm install
    @modelcontextprotocol/sdk`
</Callout>

```tsx
// Server-side usage (e.g., in your API route)
import { experimental_createMCPClient, streamText } from "ai";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

export async function POST(req: Request) {
  // Create MCP client with stdio transport
  const client = await experimental_createMCPClient({
    transport: new StdioClientTransport({
      command: "npx",
      args: ["@modelcontextprotocol/server-github"],
    }),
  });

  try {
    // Get tools from the MCP server
    const tools = await client.tools();

    const result = streamText({
      model: openai("gpt-4o"),
      tools,
      messages: convertToModelMessages(messages),
    });

    return result.toUIMessageStreamResponse();
  } finally {
    // Always close the client to release resources
    await client.close();
  }
}

// Frontend usage with assistant-ui
const runtime = useChatRuntime({
  api: "/api/chat", // Your API route that uses MCP tools
});
```

Alternative transport options:

```tsx
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

// HTTP transport
const httpClient = await experimental_createMCPClient({
  transport: new StreamableHTTPClientTransport(
    new URL("http://localhost:3000/mcp"),
  ),
});

// Server-Sent Events transport
const sseClient = await experimental_createMCPClient({
  transport: new SSEClientTransport(new URL("http://localhost:3000/sse")),
});
```

## Advanced Patterns

### Tool Composition

Combining multiple tools for complex workflows:

```tsx
const travelPlannerTool = tool({
  description: "Plan a complete trip itinerary",
  parameters: z.object({
    destination: z.string(),
    dates: z.object({
      start: z.string(),
      end: z.string(),
    }),
  }),
  execute: async ({ destination, dates }) => {
    // Execute multiple operations
    const weather = await getWeatherAPI(destination);
    const hotels = await searchHotelsAPI({
      location: destination,
      dates,
    });
    const activities = await findActivitiesAPI({
      location: destination,
      weather: weather.forecast,
    });

    return {
      weather,
      hotels,
      activities,
      itinerary: generateItinerary({ weather, hotels, activities }),
    };
  },
});

const TravelPlannerTool = makeAssistantTool({
  ...travelPlannerTool,
  toolName: "planTrip",
});
```

### Conditional Tool Availability

Tools that appear based on context:

```tsx
function ConditionalTools() {
  const { user } = useAuth();
  const { subscription } = useSubscription();

  // Premium features
  useAssistantTool({
    toolName: "advancedAnalysis",
    description: "Perform advanced data analysis",
    parameters: z.object({
      dataset: z.string(),
    }),
    execute: async (args) => {
      // Premium analysis logic
    },
    enabled: subscription?.tier === "premium",
  });

  // Role-based tools
  useAssistantTool({
    toolName: "adminPanel",
    description: "Access admin controls",
    parameters: z.object({}),
    execute: async () => {
      // Admin actions
    },
    enabled: user?.role === "admin",
  });
}
```

### Tool Error Handling

Robust error handling and recovery:

```tsx
const resilientTool = tool({
  description: "Fetch data with retry logic",
  parameters: z.object({
    endpoint: z.string(),
  }),
  execute: async ({ endpoint }, { abortSignal }) => {
    const maxRetries = 3;
    let lastError;

    for (let i = 0; i < maxRetries; i++) {
      try {
        const response = await fetch(endpoint, { signal: abortSignal });
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
      } catch (error) {
        lastError = error;
        if (abortSignal.aborted) throw error; // Don't retry on abort
        await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)));
      }
    }

    throw new Error(
      `Failed after ${maxRetries} attempts: ${lastError.message}`,
    );
  },
});

const ResilientTool = makeAssistantTool({
  ...resilientTool,
  toolName: "fetchWithRetries",
});
```

## Best Practices

1. **Clear Descriptions**: Write descriptive tool descriptions that help the LLM understand when to use each tool
2. **Parameter Validation**: Use Zod schemas to ensure type safety and provide clear parameter descriptions
3. **Error Handling**: Always handle potential errors gracefully with user-friendly messages
4. **Loading States**: Provide visual feedback during tool execution
5. **Security**: Validate permissions and sanitize inputs, especially for destructive operations
6. **Performance**: Use abort signals for cancellable operations and implement timeouts
7. **Testing**: Test tools in isolation and with the full assistant flow

## 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: Request user confirmation
  const userResponse = await context.human({
    message: "Are you sure?",
  });
};
```

The execution context provides:

* **`abortSignal`**: An `AbortSignal` that triggers when the tool execution is cancelled
* **`toolCallId`**: A unique identifier for this specific tool invocation
* **`human`**: A function that pauses execution and requests user input. The payload passed to `human()` becomes available in the render function, and the value passed to `resume()` becomes the resolved value of the `human()` call

## Runtime Integration

Each integration handles tools differently:

* **Vercel AI SDK**: Tools defined in API routes with `streamText({ tools: {...} })`. Also supports client-defined tools via `frontendTools`.
* **LangGraph**: Tools defined in your LangGraph graph configuration.
* **Mastra**: Tools defined as typed functions used by agents and workflows.

All integrations support tool UI customization via `makeAssistantToolUI`.


# Overview
URL: /docs/api-reference/overview

API reference for primitives, runtime hooks, and context providers.

***

title: Overview
description: 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

* [`AssistantCloud`](#assistant-cloud)

## Runtime API

### AI SDK

* [`useChatRuntime`](#use-chat-runtime)
* [`useAISDKRuntime`](#use-aisdk-runtime)

### Data Stream

* [`useDataStreamRuntime`](#use-data-stream-runtime)
* [`useCloudRuntime`](#use-cloud-runtime)
* [`toLanguageModelMessages`](#to-language-model-messages) (AI SDK specific)

### assistant-stream (Framework-Agnostic)

* [`toGenericMessages`](#to-generic-messages)
* [`toToolsJSONSchema`](#to-tools-json-schema)
* [`GenericMessage`](#generic-message)

### LangGraph

* [`useLangGraphRuntime`](#use-lang-graph-runtime)

### Local Runtime

* [`useLocalRuntime`](#use-local-runtime)

### External Store Runtime

* [`useExternalStoreRuntime`](#use-external-store-runtime)
* [`createMessageConverter`](#create-message-converter)

### Thread List Runtime

* [`useRemoteThreadListRuntime`](#use-remote-thread-list-runtime)
* [`useCloudThreadListRuntime`](#use-cloud-thread-list-runtime)

## Runtime Adapters

### Attachment

* [`AttachmentAdapter`](#attachment-adapter)
* [`SimpleImageAttachmentAdapter`](#simple-image-attachment-adapter)
* [`SimpleTextAttachmentAdapter`](#simple-text-attachment-adapter)
* [`CompositeAttachmentAdapter`](#composite-attachment-adapter)

### Feedback

* [`FeedbackAdapter`](#feedback-adapter)

### Speech

* [`SpeechSynthesisAdapter`](#speech-synthesis-adapter)
* [`WebSpeechSynthesisAdapter`](#web-speech-synthesis-adapter)

## 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

  The context available to components inside `<AssistantRuntimeProvider />`. You usually wrap your entire application in this context.

  ### AssistantRuntime

  Programmatically access the assistant's state and actions.

  * [`useAssistantRuntime`](#use-assistant-runtime)

  ### Instructions

  Add system prompt instructions

  * [`useAssistantInstructions`](#use-assistant-instructions)

  ### 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

  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

  The context for a single thread. Currently always corresponds to the runtime's main thread.

  ### ThreadRuntime

  Programmatically access the thread's state and actions.

  * [`useThread`](#use-thread)
  * [`useThreadComposer`](#use-thread-composer)
  * [`useThreadRuntime`](#use-thread-runtime)

  ### ModelContext

  * [`useThreadModelContext`](#use-thread-model-context)

  ### ThreadViewportStore

  * [`useThreadViewport`](#use-thread-viewport)
  * [`useThreadViewportStore`](#use-thread-viewport-store)

  ### 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

  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

  Manages the state and actions for the message composer

  ### ComposerRuntime

  * [`useComposer`](#use-composer)
  * [`useComposerRuntime`](#use-composer-runtime)

  ### 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

  Manages the state and actions for individual messages

  ### MessageRuntime

  * [`useMessage`](#use-message)
  * [`useEditComposer`](#use-edit-composer)
  * [`useMessageRuntime`](#use-message-runtime)

  ### MessageUtilsStore

  * [`useMessageUtils`](#use-message-utils)
  * [`useMessageUtilsStore`](#use-message-utils-store)

  ### 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

  <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

  <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

  Manages the state and actions for message parts within messages

  ### MessagePartRuntime

  * [`useMessagePart`](#use-content-part)
  * [`useMessagePartText`](#use-content-part-text)
  * [`useMessagePartReasoning`](#use-content-part-reasoning)
  * [`useMessagePartRuntime`](#use-content-part-runtime)

  ### MessagePartPrimitive

  <Component name="MessagePartPrimitive.Text" docsLink="#content-part-text" tooltip="Represents a text part of the message content" />

  ### MarkdownText

  <Component name="MarkdownText" docsLink="#markdown-text" tooltip="Renders markdown text in the message" />
</ContextLevel>

<ContextLevel color={contextColors["Attachment Context"]}>
  ## Attachment Context

  Manages the state and actions for attachments in messages and composer

  ### AttachmentRuntime

  * [`useAttachment`](#use-attachment)
  * [`useAttachmentRuntime`](#use-attachment-runtime)

  ### 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

  Manages the state and actions for individual thread list items

  ### ThreadListItemRuntime

  * [`useThreadListItem`](#use-thread-list-item)
  * [`useThreadListItemRuntime`](#use-thread-list-item-runtime)

  ### 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

* [`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.

***

title: Deprecation Policy
description: 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

These features may be removed at any time without notice.

* Anything marked as `unstable_`, `experimental_`, or `internal`
* The `RuntimeCore` API (considered internal)

## 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

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.

***

title: Migrating to react-langgraph v0.7
description: Guide to upgrading to the simplified LangGraph integration API.
----------------------------------------------------------------------------

## 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

### 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

The `stream` function now receives an `initialize` parameter that handles thread creation and loading automatically.

### 3. Direct Cloud Integration

Cloud persistence can now be configured directly in `useLangGraphRuntime` with the `cloud` parameter.

## Migration Steps

<Steps>
  <Step>
    ### Update Your Runtime Implementation

    #### 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)

    ```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

    Remove unused imports:

    ```diff
    - import {
    -   useCloudThreadListRuntime,
    -   useThreadListItemRuntime,
    - } from "@assistant-ui/react";
    + import { AssistantCloud } from "@assistant-ui/react";
    ```
  </Step>

  <Step>
    ### 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

    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

### Old API

```typescript
type OldLangGraphRuntimeOptions = {
  threadId?: string;
  stream: (messages: Message[]) => AsyncGenerator;
  onSwitchToNewThread?: () => Promise<void>;
  onSwitchToThread?: (threadId: string) => Promise<ThreadState>;
};
```

### 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

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

<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

**Solution**: Remove references to `useThreadListItemRuntime()`. Use the `initialize` parameter in the stream function instead.

### Issue: Thread switching doesn't work

**Solution**: Ensure you've implemented both `create` and `load` functions. The runtime needs both to manage thread lifecycle.

### Issue: Cloud persistence not working

**Solution**: Pass the `AssistantCloud` instance directly to `useLangGraphRuntime` via the `cloud` parameter.

## Example: Complete Migration

Here's a complete before and after example for a typical LangGraph integration:

### 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

```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?

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.

***

title: Migration to v0.11
description: ContentPart renamed to MessagePart for better semantic clarity.
----------------------------------------------------------------------------

## ContentPart renamed to MessagePart

All ContentPart-related types, hooks, and components have been renamed to MessagePart for better semantic clarity and consistency.

### What changed

The following types and components have been renamed:

#### 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

* `ThreadUserContentPart` → `ThreadUserMessagePart`
* `ThreadAssistantContentPart` → `ThreadAssistantMessagePart`

#### Runtime and State Types

* `ContentPartRuntime` → `MessagePartRuntime`
* `ContentPartState` → `MessagePartState`

#### Hooks

* `useContentPart` → `useMessagePart`
* `useContentPartRuntime` → `useMessagePartRuntime`
* `useContentPartText` → `useMessagePartText`
* `useContentPartReasoning` → `useMessagePartReasoning`
* `useContentPartSource` → `useMessagePartSource`
* `useContentPartFile` → `useMessagePartFile`
* `useContentPartImage` → `useMessagePartImage`
* `useTextContentPart` → `useTextMessagePart`

#### Component Types

* `EmptyContentPartComponent` → `EmptyMessagePartComponent`
* `TextContentPartComponent` → `TextMessagePartComponent`
* `ReasoningContentPartComponent` → `ReasoningMessagePartComponent`
* `SourceContentPartComponent` → `SourceMessagePartComponent`
* `ImageContentPartComponent` → `ImageMessagePartComponent`
* `FileContentPartComponent` → `FileMessagePartComponent`
* `Unstable_AudioContentPartComponent` → `Unstable_AudioMessagePartComponent`
* `ToolCallContentPartComponent` → `ToolCallMessagePartComponent`

#### Props Types

* `EmptyContentPartProps` → `EmptyMessagePartProps`
* `TextContentPartProps` → `TextMessagePartProps`
* `ReasoningContentPartProps` → `ReasoningMessagePartProps`
* `SourceContentPartProps` → `SourceMessagePartProps`
* `ImageContentPartProps` → `ImageMessagePartProps`
* `FileContentPartProps` → `FileMessagePartProps`
* `Unstable_AudioContentPartProps` → `Unstable_AudioMessagePartProps`
* `ToolCallContentPartProps` → `ToolCallMessagePartProps`

#### Providers and Context

* `TextContentPartProvider` → `TextMessagePartProvider`
* `TextContentPartProviderProps` → `TextMessagePartProviderProps`
* `ContentPartRuntimeProvider` → `MessagePartRuntimeProvider`
* `ContentPartContext` → `MessagePartContext`
* `ContentPartContextValue` → `MessagePartContextValue`

#### Primitives

* `ContentPartPrimitive` → `MessagePartPrimitive`
* `ContentPartPrimitiveText` → `MessagePartPrimitiveText`
* `ContentPartPrimitiveImage` → `MessagePartPrimitiveImage`
* `ContentPartPrimitiveInProgress` → `MessagePartPrimitiveInProgress`

### MessagePrimitive.Content renamed to MessagePrimitive.Parts

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

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

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?

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.

***

title: Migration to v0.12
description: Unified state API replaces individual context hooks.
-----------------------------------------------------------------

## 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

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

### 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

**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(({ thread }) => 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

All individual context hooks have been replaced with a single `useAuiState` hook and `useAui` for actions.

#### What changed

The following hooks have been removed:

**Removed Hooks:**

* `useMessageUtils` → Use `useAuiState(({ message }) => message.isHovering)` / `useAuiState(({ message }) => message.isCopied)`
* `useMessageUtilsStore` → Use `useAui()` with `aui.message().setIsHovering()` / `aui.message().setIsCopied()`
* `useToolUIs` → Use `useAuiState(({ tools }) => tools)` and `useAui()` with `aui.tools()`
* `useToolUIsStore` → Use `useAui()` with `aui.tools()`

**Deprecated Hooks:**

* `useAssistantRuntime` → Use `useAui()`
* `useThread` → Use `useAuiState(({ thread }) => thread)`
* `useThreadRuntime` → Use `useAui()` with `aui.thread()`
* `useMessage` → Use `useAuiState(({ message }) => message)`
* `useMessageRuntime` → Use `useAui()` with `aui.message()`
* `useComposer` → Use `useAuiState(({ composer }) => composer)`
* `useComposerRuntime` → Use `useAui()` with `aui.composer()`
* `useEditComposer` → Use `useAuiState(({ message }) => message.composer)`
* `useThreadListItem` → Use `useAuiState(({ threadListItem }) => threadListItem)`
* `useThreadListItemRuntime` → Use `useAui()` with `aui.threadListItem()`
* `useMessagePart` → Use `useAuiState(({ part }) => part)`
* `useMessagePartRuntime` → Use `useAui()` with `aui.part()`
* `useAttachment` → Use `useAuiState(({ attachment }) => attachment)`
* `useAttachmentRuntime` → Use `useAui()` with `aui.attachment()`
* `useThreadModelContext` / `useThreadModelConfig` → Use `useAuiState(({ thread }) => thread.modelContext)`
* `useThreadComposer` → Use `useAuiState(({ thread }) => thread.composer)`
* `useThreadList` → Use `useAuiState(({ threads }) => threads)`

#### 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(({ thread }) => thread.messages);
  const isRunning = useAuiState(({ thread }) => thread.isRunning);
  const composerText = useAuiState(({ composer }) => composer.text);
  const messageRole = useAuiState(({ message }) => 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

Event names used with `useAuiEvent` have been standardized to use camelCase instead of kebab-case.

#### What changed

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

**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

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)


# Chat History for AI SDK
URL: /docs/cloud/persistence/ai-sdk

Integrate cloud persistence and thread management with Vercel AI SDK.

***

title: Chat History for AI SDK
description: Integrate cloud persistence and thread management with Vercel AI SDK.
----------------------------------------------------------------------------------

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

## Overview

assistant-cloud provides thread management and persistent chat history for applications built with the [AI SDK by Vercel](https://sdk.vercel.ai/). This guide shows you how to integrate cloud persistence into your AI SDK application.

## 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

<Steps>
  <Step>
    ### 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

    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 the required packages:

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

  <Step>
    ### 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({
        api: "/api/chat", // Your AI SDK endpoint
        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>

## Authentication

The example above uses `anonymous: true` which creates a browser session-based user ID. This is suitable for public demos or prototypes.

For production apps with user accounts, see the [Cloud Authorization](/docs/cloud/authorization) guide to persist threads per user or workspace.

## Next Steps

* Learn about [user authentication](/docs/cloud/authorization) for multi-user applications
* Explore [runtime hooks](/docs/api-reference/integrations/vercel-ai-sdk) and integration options
* Check out the [complete example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-cloud) on GitHub


# Chat History for LangGraph Cloud
URL: /docs/cloud/persistence/langgraph

Integrate cloud persistence and thread management with LangGraph Cloud.

***

title: Chat History for LangGraph Cloud
description: Integrate cloud persistence and thread management with LangGraph Cloud.
------------------------------------------------------------------------------------

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

## Overview

assistant-cloud provides thread management and persistent chat history for applications built with [LangGraph Cloud](https://langchain-ai.github.io/langgraph/cloud/). This guide shows you how to integrate cloud persistence into your LangGraph application.

## 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

<Steps>
  <Step>
    ### 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

    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 the required packages:

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

  <Step>
    ### 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

    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

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

* 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


# AI SDK v5
URL: /docs/runtimes/ai-sdk/use-chat

Integrate Vercel AI SDK v5 with useChatRuntime for streaming chat.

***

title: AI SDK v5
description: Integrate Vercel AI SDK v5 with useChatRuntime for streaming chat.
-------------------------------------------------------------------------------

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

## Overview

Integration with the Vercel AI SDK v5 using the new `useChatRuntime` hook from `@assistant-ui/react-ai-sdk`.
This provides a streamlined way to integrate AI SDK v5 features including the new streamText API and improved TypeScript support.

## Getting Started

<Steps>
  <Step>
    ### Create a Next.JS project

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

  <Step>
    ### Install AI SDK v5 and `@assistant-ui/react`

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

  <Step>
    ### Setup a backend route under `/api/chat`

    `@/app/api/chat/route.ts`

    ```tsx
    import { openai } from "@ai-sdk/openai";
    import { streamText, UIMessage, convertToModelMessages, tool, zodSchema } from "ai";
    import { frontendTools } from "@assistant-ui/react-ai-sdk";
    import { z } from "zod";

    // Allow streaming responses up to 30 seconds
    export const maxDuration = 30;

    export async function POST(req: Request) {
      const {
        messages,
        system,
        tools,
      }: {
        messages: UIMessage[];
        system?: string; // System message forwarded from AssistantChatTransport
        tools?: any; // Frontend tools forwarded from AssistantChatTransport
      } = await req.json();

      const result = streamText({
        model: openai("gpt-4o"),
        system, // Use the system message from the frontend if provided
        messages: convertToModelMessages(messages),
        tools: {
          // Wrap frontend tools with frontendTools helper
          ...frontendTools(tools),
          // Backend 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>
    ### Wrap your app with `AssistantRuntimeProvider` using `useChatRuntime`

    `@/app/page.tsx`

    ```tsx
    "use client";

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

    export default function Home() {
      const runtime = useChatRuntime({
        transport: new AssistantChatTransport({
          api: "/api/chat",
        }),
      });

      return (
        <AssistantRuntimeProvider runtime={runtime}>
          <div className="h-full">
            <Thread />
          </div>
        </AssistantRuntimeProvider>
      );
    }
    ```
  </Step>
</Steps>

## API Reference

### useChatRuntime

Creates a runtime directly with AI SDK v5's `useChat` hook integration.

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

const runtime = useChatRuntime({
  api: "/api/chat",
  // All standard useChat options are supported
});
```

<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>

### Custom Transport Configuration

If you need to customize the transport configuration:

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

// Example 1: Custom API URL while keeping system/tools forwarding
const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat", // Custom API URL with forwarding
  }),
});

// Example 2: Disable system/tools forwarding
const runtime = useChatRuntime({
  api: "/api/chat",
  transport: new DefaultChatTransport(), // Standard AI SDK transport without forwarding
});
```

<Callout type="warning">
  When customizing the API URL, you must explicitly use `AssistantChatTransport`
  if you want to keep frontend system messages and tools forwarding. Simply
  passing `api` to `useChatRuntime` will use the default transport
  configuration.
</Callout>

#### Transport Options

* **`AssistantChatTransport`** (default): Automatically forwards system messages and frontend tools from the assistant-ui context to your backend
* **`DefaultChatTransport`**: Standard AI SDK transport without automatic forwarding

### Using Frontend Tools with `frontendTools`

When using `AssistantChatTransport`, frontend tools are forwarded to your backend. Use the `frontendTools` helper to properly integrate them:

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

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();
}
```

The `frontendTools` helper converts frontend tool definitions to the AI SDK format and ensures they are properly handled by the streaming response.

### 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

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.


# AI SDK v4 (Legacy)
URL: /docs/runtimes/ai-sdk/v4-legacy

Legacy integration for Vercel AI SDK v4 using data stream runtime.

***

title: AI SDK v4 (Legacy)
description: Legacy integration for Vercel AI SDK v4 using data stream runtime.
-------------------------------------------------------------------------------

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

## 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

### Option 1: Using @assistant-ui/react-data-stream (Recommended)

<Steps>
  <Step>
    ### 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

    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

    `@/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)

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

### `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

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

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

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.


# Custom Thread List
URL: /docs/runtimes/custom/custom-thread-list

Plug a custom thread database for multi-thread persistence.

***

title: Custom Thread List
description: Plug a custom thread database for multi-thread persistence.
------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## 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

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

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

<Steps>
  <Step>
    ### 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

    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

    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

<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

* `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

<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

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.

***

title: ExternalStoreRuntime
description: Bring your own Redux, Zustand, or state manager.
-------------------------------------------------------------

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

## 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

```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

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

<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

### How It Works

`ExternalStoreRuntime` acts as a bridge between your state management and assistant-ui:

```mermaid
graph TD
    A[Your State Management] -->|messages| B[ExternalStoreAdapter]
    B --> C[ExternalStoreRuntime]
    C --> D[assistant-ui Components]
    D -->|user actions| B
    B -->|state updates| A
```

### 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

<Steps>
  <Step>
    ### Install Dependencies

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

  <Step>
    ### 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

    ```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

### Message Conversion

Two approaches for converting your message format:

#### 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`

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

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

#### 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

```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

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

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

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

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

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

#### 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

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

<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

### 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)

```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

```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

### 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

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

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

### 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

```tsx
const ToolUI = makeAssistantToolUI({
  render: () => {
    const originalMessages = useMessagePart((p) => getExternalStoreMessages(p));
    // Access original message data for this message part
  },
});
```

## Debugging

### 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

### 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

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

```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`

### 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          | `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

<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

* 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

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

### `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`

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",
    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)",
  },
  {
    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`

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

* [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

* [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.

***

title: LocalRuntime
description: Quickest path to a working chat. Handles state while you handle the API.
-------------------------------------------------------------------------------------

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

## 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

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

<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

<Steps>
  <Step>
    ### Create a Next.js project

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

  <Step>
    ### Install `@assistant-ui/react`

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

  <Step>
    ### Add `assistant-ui` Thread component

    ```sh npm2yarn
    npx assistant-ui@latest add thread
    ```
  </Step>

  <Step>
    ### 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`

    ```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

    ```tsx title="app/page.tsx"
    import { Thread } from 'components/assistant-ui/thread.tsx'

    export default function Page() {
      return <Thread />;
    }
    ```
  </Step>
</Steps>

## 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

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

`LocalRuntime` supports OpenAI-compatible function calling with automatic or human-in-the-loop execution.

### Basic Tool Definition

```tsx
const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather in a location",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA",
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
          },
        },
        required: ["location"],
      },
    },
  },
];

const runtime = useLocalRuntime(MyModelAdapter, {
  // Tools are passed via context
  context: { tools },
});
```

### 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

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

`LocalRuntime` supports multiple conversation threads through two approaches:

### 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

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

<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

```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

Extend `LocalRuntime` capabilities with adapters. The runtime automatically enables/disables UI features based on which adapters are provided.

### 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

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

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

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

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

### 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

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

### 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

```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

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`

| 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

### 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

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

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

### `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`

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`

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`

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

* [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

* [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.

***

title: Getting Started
description: Connect to LangGraph Cloud API for agent workflows with streaming.
-------------------------------------------------------------------------------

## 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

<Steps>
  <Step>
    ### 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

    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>

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

## Installation in existing React project

<Steps>
  <Step>
    ### Install dependencies

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

  <Step>
    ### 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

    ```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();
      return client.runs.stream(
        params.threadId,
        process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
        {
          input: {
            messages: params.messages,
          },
          streamMode: "messages",
          ...params.config
        },
      );
    };
    ```
  </Step>

  <Step>
    ### 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

    ```tsx twoslash title="@/app/page.tsx" {2,8}
    // @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

    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

    Follow the [UI Components](/docs/ui/thread) guide to setup the UI components.
  </Step>
</Steps>

## Advanced APIs

### 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

Use `convertLangChainMessages` to transform LangChain messages to assistant-ui format:

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

const threadMessage = convertLangChainMessages(langChainMessage);
```

## Thread Management

### 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

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/persistence/langgraph) for detailed setup instructions.

## 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.

***

title: Full-Stack Integration
description: Integrate Mastra directly into Next.js API routes.
---------------------------------------------------------------

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

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

    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

    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

    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

    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

    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

    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

    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

    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

    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.

***

title: Overview
description: 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

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.

***

title: Separate Server Integration
description: Run Mastra as a standalone server connected to your frontend.
--------------------------------------------------------------------------

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

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

    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

    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

    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

    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

    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

    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

    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

    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.

***

title: <AssistantRuntimeProvider />
description: Root provider that connects your runtime to assistant-ui components.
---------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
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

<ParametersTable {...AssistantRuntimeProvider} />


# <TextMessagePartProvider />
URL: /docs/api-reference/context-providers/text-message-part-provider

Context provider for reusing text components outside of message content.

***

title: <TextMessagePartProvider />
description: Context provider for reusing text components outside of message content.
-------------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
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

<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.

***

title: "@assistant-ui/react-data-stream"
description: Hooks for connecting to data stream protocol endpoints and Assistant Cloud.
----------------------------------------------------------------------------------------

Data Stream protocol integration for assistant-ui.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## API Reference

### `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`

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`

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

For custom integrations that don't use the AI SDK, use these utilities from `assistant-stream`:

### `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`

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.

***

title: "@assistant-ui/react-hook-form"
description: React Hook Form integration for AI-assisted form filling.
----------------------------------------------------------------------

A React Hook Form integration for @assistant-ui.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## API Reference

### `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

<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`

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.

***

title: "@assistant-ui/react-ai-sdk"
description: Vercel AI SDK v5 integration with chat runtime hooks and transport utilities.
------------------------------------------------------------------------------------------

Vercel AI SDK integration for assistant-ui.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

<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

### `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`

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`

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`

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

***

## title: ActionBarMorePrimitive

A dropdown menu for additional actions that don't fit in the main action bar.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { DataAttributesTable } from "@/components/docs/tables/DataAttributesTable";
import { Code } from "@radix-ui/themes";

## 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

### 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

A button that toggles the dropdown menu.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarMorePrimitiveTriggerProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-state]",
    values: <Code>"open" | "closed"</Code>,
  },
  {
    attribute: "[data-disabled]",
    values: "Present when disabled",
  },
]}
/>

### 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.",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-state]",
    values: <Code>"open" | "closed"</Code>,
  },
  {
    attribute: "[data-side]",
    values: <Code>"top" | "right" | "bottom" | "left"</Code>,
  },
  {
    attribute: "[data-align]",
    values: <Code>"start" | "center" | "end"</Code>,
  },
]}
/>

Refer to Radix UI's Documentation for [DropdownMenu.Content](https://www.radix-ui.com/primitives/docs/components/dropdown-menu#content) for more details.

### 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.",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-disabled]",
    values: "Present when disabled",
  },
  {
    attribute: "[data-highlighted]",
    values: "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

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

### 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

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(({ composer }) => 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.

***

title: ActionBarPrimitive
description: Buttons for message actions like copy, edit, reload, speak, and feedback.
--------------------------------------------------------------------------------------

Buttons to interact with the message.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { DataAttributesTable } from "@/components/docs/tables/DataAttributesTable";
import { Code } from "@radix-ui/themes";

## 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

### 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>
    ),
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-floating]",
    values: "Present when floating",
  },
]}
/>

### Edit

Enables edit mode on user message.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveEditProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### Reload

Regenerates the assistant message.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveReloadProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

{" "}

### 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",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-copied]",
    values: "Present when the message was recently copied.",
  },
]}
/>

#### Copied state

Show a different icon for a few seconds after the message is copied.

```tsx
<ActionBarPrimitive.Copy>
  <AuiIf condition={({ message }) => !message.isCopied}>
    <CopyIcon />
  </AuiIf>
  <AuiIf condition={({ message }) => 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

Plays the message text as speech.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveSpeakProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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

Shows a positive feedback submission button.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveFeedbackPositiveProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-submitted]",
    values: "Present when positive feedback was submitted.",
  },
]}
/>

### Feedback Negative

Shows a negative feedback submission button.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ActionBarPrimitiveFeedbackNegativeProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-submitted]",
    values: "Present when negative feedback was submitted.",
  },
]}
/>

### 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

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.

***

title: AuiIf
description: Conditional rendering component based on thread, message, or composer state.
-----------------------------------------------------------------------------------------

Conditionally render children based on assistant state.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## Anatomy

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

<AuiIf condition={({ thread }) => thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>
```

## 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

<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

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

### Thread State Conditions

```tsx
// Show welcome screen when thread is empty
<AuiIf condition={({ thread }) => thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>

// Show loading indicator while running
<AuiIf condition={({ thread }) => thread.isRunning}>
  <LoadingSpinner />
</AuiIf>

// Conditional send/cancel button
<AuiIf condition={({ thread }) => !thread.isRunning}>
  <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
</AuiIf>
<AuiIf condition={({ thread }) => thread.isRunning}>
  <ComposerPrimitive.Cancel>Cancel</ComposerPrimitive.Cancel>
</AuiIf>
```

### Message State Conditions

```tsx
// Show avatar only for assistant messages
<AuiIf condition={({ message }) => message.role === "assistant"}>
  <AssistantAvatar />
</AuiIf>

// Show disclaimer on last message
<AuiIf condition={({ message }) => message.isLast}>
  <Disclaimer />
</AuiIf>

// Toggle copy icon based on copied state
<ActionBarPrimitive.Copy>
  <AuiIf condition={({ message }) => !message.isCopied}>
    <CopyIcon />
  </AuiIf>
  <AuiIf condition={({ message }) => message.isCopied}>
    <CheckIcon />
  </AuiIf>
</ActionBarPrimitive.Copy>

// Show speak/stop button based on speech state
<AuiIf condition={({ message }) => message.speech == null}>
  <ActionBarPrimitive.Speak>
    <SpeakIcon />
  </ActionBarPrimitive.Speak>
</AuiIf>
<AuiIf condition={({ message }) => message.speech != null}>
  <ActionBarPrimitive.StopSpeaking>
    <StopIcon />
  </ActionBarPrimitive.StopSpeaking>
</AuiIf>
```

### Composer State Conditions

```tsx
// Show placeholder when composer is empty
<AuiIf condition={({ composer }) => composer.isEmpty}>
  <PlaceholderText />
</AuiIf>

// Show attachment preview when editing
<AuiIf condition={({ composer }) => composer.isEditing}>
  <EditingIndicator />
</AuiIf>
```

### Complex Conditions

```tsx
// Combine multiple conditions
<AuiIf condition={({ thread, message }) =>
  !thread.isRunning && message.role === "assistant"
}>
  <ActionBar />
</AuiIf>

// Custom logic
<AuiIf condition={({ thread }) =>
  thread.messages.length > 0 && !thread.isRunning
}>
  <FollowUpSuggestions />
</AuiIf>
```

## 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 = ({ thread }) => thread.isEmpty;

<AuiIf condition={isThreadEmpty}>
  <WelcomeScreen />
</AuiIf>
```

## 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={({ thread }) => thread.isEmpty}>`                |
| `<ThreadPrimitive.If running>`         | `<AuiIf condition={({ thread }) => thread.isRunning}>`              |
| `<ThreadPrimitive.If running={false}>` | `<AuiIf condition={({ thread }) => !thread.isRunning}>`             |
| `<MessagePrimitive.If user>`           | `<AuiIf condition={({ message }) => message.role === "user"}>`      |
| `<MessagePrimitive.If assistant>`      | `<AuiIf condition={({ message }) => message.role === "assistant"}>` |
| `<MessagePrimitive.If copied>`         | `<AuiIf condition={({ message }) => message.isCopied}>`             |
| `<MessagePrimitive.If speaking>`       | `<AuiIf condition={({ message }) => message.speech != null}>`       |
| `<MessagePrimitive.If last>`           | `<AuiIf condition={({ message }) => message.isLast}>`               |
| `<ComposerPrimitive.If editing>`       | `<AuiIf condition={({ composer }) => composer.isEditing}>`          |


# AssistantModalPrimitive
URL: /docs/api-reference/primitives/assistant-modal

A popover chat interface for floating assistant UI in the corner of the screen.

***

title: AssistantModalPrimitive
description: 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.

import { Code } from "@radix-ui/themes";
import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { DataAttributesTable } from "@/components/docs/tables/DataAttributesTable";

## 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

### 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

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",
  },
]}
/>

<DataAttributesTable
  data={[
  {
    attribute: "[data-state]",
    values: <Code>"open" | "closed"</Code>,
  },
]}
/>

### 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

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.

***

title: AttachmentPrimitive
description: Components for displaying and managing file attachments in messages and composer.
----------------------------------------------------------------------------------------------

Buttons to interact with attachments.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { DataAttributesTable } from "@/components/docs/tables/DataAttributesTable";
import { Code } from "@radix-ui/themes";

<Callout>
  **Dual Use!** Attachments can appear in both messages and composers.
</Callout>

## 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

### Container

Containts all parts of the attachment.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveRootProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### Thumbnail

The thumbnail of the attachment.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveThumbnailProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### Name

The name of the attachment.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="AttachmentPrimitiveNameProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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.

***

title: BranchPickerPrimitive
description: Navigate between conversation branches with previous/next controls.
--------------------------------------------------------------------------------

View and switch between branches.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## Anatomy

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

const BranchPicker = () => (
  <BranchPickerPrimitive.Root>
    <BranchPickerPrimitive.Previous />
    <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
    <BranchPickerPrimitive.Next />
  </BranchPickerPrimitive.Root>
);
```

## API Reference

### 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

The current branch number.

This primitive renders the raw number as a string.

### Count

The total number of branches.

This primitive renders the raw number as a string.

### Previous

Navigates to the previous branch.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="BranchPickerPrimitivePreviousProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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.

***

title: ComposerPrimitive
description: Primitives for the text input, send button, and attachments.
-------------------------------------------------------------------------

The user interface to add new messages or edit existing ones.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { KeyboardTable } from "@/components/docs/tables/KeyboardTable";
import { Code } from "@radix-ui/themes";

<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

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

// creating a new message
const Composer = () => (
  <ComposerPrimitive.Root>
    <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

### Root

Containts all parts of the composer.

This primitive renders a `<form>` element unless `asChild` is set.

<ParametersTable
  type="ComposerRootProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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",
  },
]}
/>

#### Keyboard Shortcuts

<KeyboardTable
  data={[
  {
    keys: ["Enter"],
    description: "Sends the message.",
  },
  {
    keys: ["Escape"],
    description: "Sends a cancel action.",
  },
]}
/>

### 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

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

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

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

Renders a button to add an attachment.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveAddAttachmentProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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

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

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>
```

### 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.

***

title: Composition
description: How to compose primitives with custom components using asChild.
----------------------------------------------------------------------------

import { Code } from "@radix-ui/themes";

`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.

***

title: ErrorPrimitive
description: Components for displaying error messages in the chat interface.
----------------------------------------------------------------------------

A component for displaying error messages in the UI.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## Anatomy

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

const ErrorDisplay = () => (
  <ErrorPrimitive.Root>
    <ErrorPrimitive.Message />
  </ErrorPrimitive.Root>
);
```

## API Reference

### 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

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

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.

***

title: MessagePartPrimitive
description: Primitives for text, images, tool calls, and other message content.
--------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
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 or tool-call.

## Message part Types

### Text

Standard text content, used for both user and assistant messages.

### Reasoning

Exposes the assistant's reasoning process, showing how it arrived at its responses. This is typically used only in assistant messages.

### Audio

Audio content that can be played back.

### Tool Call

Interactive elements that represent tool operations.

## Anatomy

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

const TextMessagePart = () => {
  return <MessagePartPrimitive.Text />;
};
```

## Primitives

### Plain Text

```tsx
import { MessagePartPrimitive } from "@assistant/react";

<MessagePartPrimitive.Text />;
```

### Markdown Text

Renders the message's text as Markdown.

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

<MarkdownTextPrimitive />;
```

### Audio

Coming soon.

### InProgress

Renders children only if the message part is in progress.

```tsx
import { MessagePartPrimitive } from "@assistant/react";

<MessagePartPrimitive.InProgress>
  <LoadingIndicator />
</MessagePartPrimitive.InProgress>;
```

### 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>
    );
  },
});
```

## Context Provider

Message part context is provided by `MessagePrimitive.Parts` or `TextMessagePartProvider`

### MessagePrimitive.Parts

```tsx
import { MessagePrimitive } from "@assistant/react";

<MessagePrimitive.Parts
  components={{
    Text: MyText,
    Reasoning: MyReasoning,
    Audio: MyAudio,
    tools: {
      by_name: {
        get_weather: MyWeatherToolUI,
      },
      Fallback: MyFallbackToolUI,
    },
  }}
/>;
```

### 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

### `useMessagePartRuntime`

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

const MessagePartRuntime = useMessagePartRuntime();
```

<ParametersTable {...MessagePartRuntime} />

### `useMessagePart`

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

const MessagePart = useMessagePart();
```

<ParametersTable {...TextMessagePartState} />

<ParametersTable {...AudioMessagePartState} />

<ParametersTable {...ToolCallMessagePartState} />

### `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.

***

title: MessagePrimitive
description: Components for rendering message content, parts, and attachments.
------------------------------------------------------------------------------

A single message in a conversation. Messages may consist of multiple parts.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## 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

### Root

Containts all parts of the message.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="MessagePrimitiveRootProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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

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

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

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.",
  },
]}
/>

### 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>
```


# ThreadListItemMorePrimitive
URL: /docs/api-reference/primitives/thread-list-item-more

Dropdown menu for additional thread actions like archive and delete.

***

title: ThreadListItemMorePrimitive
description: 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).

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## 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

### 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

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

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

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

A visual separator between menu items. Wraps Radix UI's `DropdownMenu.Separator`.

<ParametersTable
  type="ThreadListItemMorePrimitiveSeparatorProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

## Examples

### 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

```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.

***

title: ThreadListItemPrimitive
description: Individual thread item with title, archive, and delete controls.
-----------------------------------------------------------------------------

A single thread item within a thread list.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## 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

### 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

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

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

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

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

A button to permanently delete the thread.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListItemPrimitiveDeleteProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

## Examples

### 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

```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.

***

title: ThreadListPrimitive
description: Display and manage multiple conversation threads with create and archive actions.
----------------------------------------------------------------------------------------------

Displays a list of conversation threads.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## Anatomy

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

const ThreadList = () => (
  <ThreadListPrimitive.Root>
    <ThreadListPrimitive.New />
    <ThreadListPrimitive.Items
      components={{
        ThreadListItem: MyThreadListItem
      }}
    />
  </ThreadListPrimitive.Root>
);
```

## API Reference

### 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

A button to create a new thread.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ThreadListPrimitiveNewProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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

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.

***

title: ThreadPrimitive
description: Primitives for the message list, viewport, and welcome screen.
---------------------------------------------------------------------------

A conversation between a user and an assistant.

import { ParametersTable } from "@/components/docs/tables/ParametersTable";

## Anatomy

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

const Thread = () => (
  <ThreadPrimitive.Root>
    <ThreadPrimitive.Viewport>
      <ThreadPrimitive.Empty>...</ThreadPrimitive.Empty>
      <ThreadPrimitive.Messages components={...} />
    </ThreadPrimitive.Viewport>
    <Composer />
  </ThreadPrimitive.Root>
);
```

## API Reference

### Root

Containts all parts of the thread.

This primitive renders a `<div>` element unless `asChild` is set.

<ParametersTable
  type="ThreadPrimitiveRootProps"
  parameters={[
  {
    name: "asChild",
  },
]}
/>

### 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

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

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

Renders children only when there are no messages.

### 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.Suggestion`

Shows a suggestion to the user. When the user clicks on the suggestion, the composer's value is set to the suggestion's prompt.

This primitive renders a `<button>` element unless `asChild` is set.

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

const Suggestion = () => {
  return (
    <ThreadPrimitive.Suggestion
      prompt="I need help with product search"
      send
    />
  );
};
```

<ParametersTable
  type="ThreadPrimitiveSuggestionProps"
  parameters={[
  {
    name: "prompt",
    type: "string",
    description: "The suggestion's prompt.",
  },
  {
    name: "send",
    type: "boolean",
    description:
      "When true, automatically sends the message. When false, replaces or appends the composer text with the suggestion - depending on the value of `clearComposer`",
  },
  {
    name: "clearComposer",
    type: "boolean",
    default: "true",
    description:
      "Whether to clear the composer after sending. When send is set to false, determines if composer text is replaced with suggestion (true, default), or if the suggestion's prompt is appended to the composer text (false).",
  },
  {
    name: "autoSend",
    type: "boolean",
    deprecated: true,
    description: "Deprecated. Use 'send' instead.",
  },
  {
    name: "method",
    type: "'replace'",
    deprecated: true,
    description: "Deprecated. This parameter is no longer used.",
  },
]}
/>


# AssistantRuntime
URL: /docs/api-reference/runtimes/assistant-runtime

Root runtime for managing threads, tool UIs, and assistant state.

***

title: AssistantRuntime
description: Root runtime for managing threads, tool UIs, and assistant state.
------------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { AssistantRuntime, AssistantToolUIsState } from "@/generated/typeDocs";

The `AssistantRuntime` is the root runtime of the application.

### `useAssistantRuntime`

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

const runtime = useAssistantRuntime();
```

<ParametersTable {...AssistantRuntime} />

### 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.

***

title: AttachmentRuntime
description: Hooks for accessing attachment state in composer and messages.
---------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import {
  ComposerAttachmentState,
  MessageAttachmentState,
} from "@/components/docs/tables/parameters/context";

### `useAttachment`

Access the current attachment state:

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

const { attachment } = useAttachment();
const att = useAttachment((m) => m.attachment);
```

### `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)

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.

***

title: ComposerRuntime
description: 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 { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { ComposerRuntime, ThreadComposerRuntime, ThreadComposerState, EditComposerState } from "@/generated/typeDocs";

### `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`

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`

The state of the thread composer which is the composer the user can interact with at the bottom.

<ParametersTable {...ThreadComposerState} />

### `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.

***

title: MessagePartRuntime
description: Hook for accessing message part state within parts.
----------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { MessagePartState } from "@/components/docs/tables/parameters/context";

### `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.

***

title: MessageRuntime
description: Hooks for accessing message state, utilities, and edit composer.
-----------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import {
  MessageState,
  MessageUtilsState,
  EditComposerState,
} from "@/components/docs/tables/parameters/context";

### `useMessage`

Retrieve the message object:

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

const { message } = useMessage();
const msg = useMessage((m) => m.message);
```

<ParametersTable {...MessageState} />

### `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`

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.

***

title: ThreadListItemRuntime
description: Runtime for managing individual thread list items.
---------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import {
  ThreadListItemRuntime,
  ThreadListItemState,
} from "@/generated/typeDocs";

### `useThreadListItemRuntime`

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

const threadListItemRuntime = useThreadListItemRuntime();
```

<ParametersTable {...ThreadListItemRuntime} />

### `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.

***

title: ThreadListRuntime
description: Runtime for accessing and managing the list of threads.
--------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { ThreadListRuntime, ThreadListState } from "@/generated/typeDocs";

### 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`

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.

***

title: ThreadRuntime
description: Runtime for thread state, messages, and viewport management.
-------------------------------------------------------------------------

import { ParametersTable } from "@/components/docs/tables/ParametersTable";
import { ThreadRuntime, ThreadState } from "@/generated/typeDocs";
import { ThreadMessagesState, ThreadViewportState } from "@/components/docs/tables/parameters/context";

### `useThreadRuntime`

Get the thread runtime object:

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

const thread = useThreadRuntime();
```

<ParametersTable {...ThreadRuntime} />

### `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`

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.

***

title: AssistantModal
description: Chat bubble component for support or Q\&A use cases.
-----------------------------------------------------------------

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

## Overview

A chat bubble shown in the bottom right corner of the screen. Useful for support or Q\&A use cases.

## Getting Started

<Steps>
  <Step>
    ### Install `@assistant-ui/react-ui`

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

  <Step>
    ### Import CSS styles

    Add the following to your `tailwind.config.ts`:

    <Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
      ```ts title="/tailwind.config.ts" tab="Tailwind"
      {
        plugins: [
          require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
          require("@assistant-ui/react-ui/tailwindcss")({
            components: ["assistant-modal"],
          })
        ],
      }
      ```

      ```ts title="/tailwind.config.ts" tab="Tailwind + shadcn-ui"
      {
        plugins: [
          require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
          require("@assistant-ui/react-ui/tailwindcss")({
            components: ["assistant-modal"],
            shadcn: true
          })
        ],
      }
      ```

      ```ts title="/app/layout.tsx" tab="Not using Tailwind"
      import "@assistant-ui/react-ui/styles/index.css";
      import "@assistant-ui/react-ui/styles/modal.css";
      ```
    </Tabs>
  </Step>

  <Step>
    ### 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.

***

title: Decomposition
description: Break down styled components into smaller customizable parts.
--------------------------------------------------------------------------

## 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

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

Contains all parts of the thread. Accepts a `config` prop which is used by many other styled components.

### Thread.Viewport

The scrollable area containing all messages. Anchors scroll to the bottom as new messages are added.

### Thread.Messages

Renders all messages. This renders a separate component for each message (passed to the `components` prop).

### Thread.ViewportFooter

Renders the footer of the thread viewport. This is the sticky footer that does not scroll with the messages.

### Thread.ScrollToBottom

A button to scroll the viewport to the bottom. Hidden when the viewport is already at bottom.

## 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

Contains all parts of the welcome message.

### ThreadWelcome.Center

The centered content of the welcome message.

### ThreadWelcome.Avatar

The avatar of the assistant.

### ThreadWelcome.Message

The welcome message.

### ThreadWelcome.Suggestions

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

A conversation starter suggestion.

## 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

Contains all parts of the composer.

### Composer.Input

The text input field for the user to type a new message.

### Composer.Action

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={({ thread }) => !thread.isRunning}>
        <Composer.Send />
      </AuiIf>
      <AuiIf condition={({ thread }) => thread.isRunning}>
        <Composer.Cancel />
      </AuiIf>
    </>
  );
};
```

### Composer.Send

The button to send the message.

### Composer.Cancel

Sends a cancel action.

### Composer.Attachments

Renders attachments.

### Composer.AddAttachment

Renders an add attachment button.

## 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

Contains all parts of the composer attachment.

### AttachmentUI.Remove

Renders a remove attachment button.

## 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

Contains all parts of the assistant message.

### AssistantMessage.Avatar

The avatar of the assistant.

### AssistantMessage.Content

The content of the assistant message.

## 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

Contains all parts of the assistant action bar.

### AssistantActionBar.Reload

Shows a reload button.

### AssistantActionBar.Copy

Shows a copy button.

### AssistantActionBar.SpeechControl

Shows a speech control button (either Speak or StopSpeaking).

### AssistantActionBar.Speak

Shows a speak button.

### AssistantActionBar.StopSpeaking

Shows a stop speaking button.

### AssistantActionBar.FeedbackPositive

Shows a positive feedback button.

### AssistantActionBar.FeedbackNegative

Shows a negative feedback button.

## 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

Contains all parts of the branch picker.

### BranchPicker.Previous

Shows a previous button.

### BranchPicker.Next

Shows a next button.

### BranchPicker.State

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

The current branch number.

### BranchPicker.Count

The total number of branches.

## 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

Contains all parts of the user message.

### UserMessage.Content

The content of the user message.

### UserMessage.Attachments

Renders attachments.

## 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

Contains all parts of the user action bar.

### UserActionBar.Edit

Shows an edit button.

## UserAttachment

Renders an attachment.

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

const MyUserAttachment: FC = () => {
  return <UserAttachment.Root>attachment</UserAttachment.Root>;
};
```

### UserAttachment.Root

Contains all parts of the user attachment.

## 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

Contains all parts of the edit composer.

### EditComposer.Input

The text input field for the user to type a new message.

### EditComposer.Footer

The footer of the edit composer.

### EditComposer.Cancel

Sends a cancel action.

### EditComposer.Send

Sends the message.

## 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

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

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.

***

title: Markdown
description: Enable rich text formatting for assistant messages using markdown.
-------------------------------------------------------------------------------

Allow the assistant to display rich text using markdown.

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

## Enabling markdown support

<Steps>
  <Step>
    ### Install `@assistant-ui/react-markdown`

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

  <Step>
    ### Setup styles

    <Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
      ```ts {3} title="/tailwind.config.ts" tab="Tailwind"
      {
        plugins: [
          require("tailwindcss-animate"),
          require("@assistant-ui/react-ui/tailwindcss")
        ],
      }
      ```

      ```ts title="/tailwind.config.ts" tab="Tailwind + shadcn-ui"
      {
        plugins: [
          require("tailwindcss-animate"),
          require("@assistant-ui/react-ui/tailwindcss")({ shadcn: true })
        ],
      }
      ```

      ```ts title="/app/layout.tsx" tab="Not using Tailwind"
      import "@assistant-ui/react-ui/styles/index.css";
      import "@assistant-ui/react-ui/styles/markdown.css";
      ```
    </Tabs>
  </Step>

  <Step>
    ### 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`

    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.

***

title: Custom Scrollbar
description: 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

```sh
npx shadcn@latest add scroll-area
```

### @radix-ui/react-scroll-area v1.2.0 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

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

* 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.

***

title: Thread Width
description: 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

```css title="@/app/globals.css"
:root {
  --aui-thread-max-width: 600px;
}
```

## 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.

***

title: Thread
description: Full-screen message list and composer UI for chat interfaces.
--------------------------------------------------------------------------

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

## Overview

The raw message list and message composer UI. Useful for full screen chat use cases.

## Getting Started

<Steps>
  <Step>
    ### Install `@assistant-ui/react-ui`

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

  <Step>
    ### Import CSS styles

    Add the following to your `tailwind.config.ts`:

    <Tabs items={["Tailwind", "Tailwind + shadcn-ui", "Not using Tailwind"]}>
      ```ts title="/tailwind.config.ts" tab="Tailwind"
      {
        plugins: [
          require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
          require("@assistant-ui/react-ui/tailwindcss")({
            components: ["thread"],
          })
        ],
      }
      ```

      ```ts title="/tailwind.config.ts" tab="Tailwind + shadcn-ui"
      {
        plugins: [
          require("tailwindcss-animate"), // make sure to "npm install tailwindcss-animate"
          require("@assistant-ui/react-ui/tailwindcss")({
            components: ["thread"],
            shadcn: true
          })
        ],
      }
      ```

      ```ts title="/app/layout.tsx" tab="Not using Tailwind"
      import "@assistant-ui/react-ui/styles/index.css";
      ```
    </Tabs>
  </Step>

  <Step>
    ### 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.

***

title: "Introduction"
description: 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.

***

title: "Introduction"
description: 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

* Node.js 18.x or higher

## 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

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.

***

title: "Part 1: Setup frontend"
description: Create a Next.js project with the LangGraph assistant-ui template.
-------------------------------------------------------------------------------

## 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

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

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

### 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

Rich text rendering using Markdown is enabled by default.

## 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.

***

title: "Part 2: Generative UI"
description: 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

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

```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!

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

### 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`

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`

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!

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

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

```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.

***

title: "Part 3: Approval UI"
description: Add human-in-the-loop approval for tool calls.
-----------------------------------------------------------

## Background: LangGraph implementation details

import Image from "next/image";
import { InstallCommand } from "@/components/docs/fumadocs/install/install-command";
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

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

```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!

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

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`

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!

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" />