assistant-ui logo/Docs/API Reference

API Reference

Complete assistant-ui React API reference for building AI chat UIs with primitives, hooks, runtimes, adapters, tools, transport, voice, and integrations.

Start Here

The React API reference is organized by how you build with assistant-ui:

Tools

Define toolkits, install tool resources, and render tool or data parts.

Model Context

Provide instructions, merge model context, and register inline renderers for model-facing state.

Transport

Assistant transport, frame provider, and serialized frame protocol APIs for cross-boundary runtimes.

External Store

Runtime and message conversion APIs for apps that own their message store.

Voice

Realtime voice sessions, speech synthesis adapters, and dictation adapters.

Primitives

Composable React components such as ThreadPrimitive, MessagePrimitive, and ComposerPrimitive.

Hooks

Reactive state hooks, runtime hooks, model context hooks, and utility hooks.

Adapters

Runtime extension points for attachments, persistence, feedback, speech, dictation, and suggestions.

Integrations

Package-level APIs for integrations such as @assistant-ui/react-ai-sdk and @assistant-ui/cloud-ai-sdk.

Runtime State

Runtime action and state shapes used by useAui and useAuiState.

The lower sections on this page show how the core React contexts nest and where the primary primitives, hooks, and runtime objects are available. Feature-first APIs such as tools, model context, transport, external store, and voice now live in their own generated sections.

Highest Level Context Providers

<AssistantRuntimeProvider runtime={runtime} />
Context Provider
Provides: Assistant Context, Thread Context, Thread Composer Context
<ThreadPrimitive />
<ThreadListPrimitive />
<TextMessagePartProvider text={text} />
Context Provider
Provides: Text MessagePart Context
<MessagePartPrimitive />

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 via useAui().

Instructions

Add system prompt instructions

Tool UI

Register toolkits and tool UIs

Programmatically access the list of registered tool UIs via useAuiState((s) => s.tools) and useAui().tools().

ThreadListPrimitive

Shows a list of threads and allows the user to switch between them.

<ThreadListPrimitive.Root />
<ThreadListPrimitive.New />
<ThreadListPrimitive.Items components={...} />
Context Provider
Provides: ThreadListItem 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.

  • State: useAuiState((s) => s.thread)
  • Actions: useAui().thread()
  • Composer: useAuiState((s) => s.composer)

ModelContext

  • useAui().thread().getModelContext()

ThreadViewportStore

ThreadPrimitive

A conversation thread.

<ThreadPrimitive.Root />
<ThreadPrimitive.Viewport />
<ThreadPrimitive.Messages />
Context Provider
Provides: Message Context, Edit Composer Context
<MessagePrimitive />
<ThreadPrimitive.ScrollToBottom />
<AuiIf />
<ThreadPrimitive.Suggestion />
<ComposerPrimitive />

AssistantModalPrimitive

A floating modal that usually appears in the lower right corner of the screen. Common for support use cases.

<AssistantModalPrimitive.Root />
<AssistantModalPrimitive.Trigger />
<AssistantModalPrimitive.Anchor />
<AssistantModalPrimitive.Content />

Composer Context

Manages the state and actions for the message composer

ComposerRuntime

  • State: useAuiState((s) => s.composer)
  • Actions: useAui().composer()

ComposerPrimitive

<ComposerPrimitive.Root />
<ComposerPrimitive.Input />
<ComposerPrimitive.Send />
<ComposerPrimitive.Cancel />
<ComposerPrimitive.Attachments />
Context Provider
Provides: Attachment Context
<ComposerPrimitive.AddAttachment />

Message Context

Manages the state and actions for individual messages

MessageRuntime

  • State: useAuiState((s) => s.message)
  • Edit Composer: useAuiState((s) => s.message.composer)
  • Actions: useAui().message()
  • Utilities: useAuiState((s) => s.message.isCopied) / useAuiState((s) => s.message.isHovering)

MessagePrimitive

<MessagePrimitive.Root />
<MessagePrimitive.Parts />
Context Provider
Provides: MessagePart Context
<MessagePrimitive.Attachments />
Context Provider
Provides: Attachment Context
<AuiIf />

ActionBarPrimitive

<ActionBarPrimitive.Root />
<ActionBarPrimitive.Copy />
<ActionBarPrimitive.Edit />
<ActionBarPrimitive.Reload />
<ActionBarPrimitive.Speak />
<ActionBarPrimitive.StopSpeaking />
<ActionBarPrimitive.FeedbackPositive />
<ActionBarPrimitive.FeedbackNegative />

BranchPickerPrimitive

<BranchPickerPrimitive.Root />
<BranchPickerPrimitive.Previous />
<BranchPickerPrimitive.Number />
<BranchPickerPrimitive.Next />

MessagePart Context

Manages the state and actions for message parts within messages

MessagePartRuntime

  • State: useAuiState((s) => s.part)
  • Actions: useAui().part()

MessagePartPrimitive

<MessagePartPrimitive.Text />

MarkdownText

<MarkdownText />

Attachment Context

Manages the state and actions for attachments in messages and composer

AttachmentRuntime

  • State: useAuiState((s) => s.attachment)
  • Actions: useAui().attachment()

AttachmentPrimitive

<AttachmentPrimitive.Root />
<AttachmentPrimitive.Name />
<AttachmentPrimitive.Remove />
<AttachmentPrimitive.unstable_Thumb />

ThreadListItem Context

Manages the state and actions for individual thread list items

ThreadListItemRuntime

  • State: useAuiState((s) => s.threadListItem)
  • Actions: useAui().threadListItem()

ThreadListItem

<ThreadListItemPrimitive.Root />
<ThreadListItemPrimitive.Trigger />
<ThreadListItemPrimitive.Title />
<ThreadListItemPrimitive.Archive />
<ThreadListItemPrimitive.Unarchive />
<ThreadListItemPrimitive.Delete />

Utilities