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

Start Here#

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

The lower sections on this page show how the contexts nest and where each primitive, hook, and runtime object is available.

Cloud#

• AssistantCloud

Runtime API#

AI SDK#

• useChatRuntime
• useAISDKRuntime

Data Stream#

• useDataStreamRuntime
• useCloudRuntime
• toLanguageModelMessages (AI SDK specific)

assistant-stream (Framework-Agnostic)#

• toGenericMessages
• toToolsJSONSchema
• GenericMessage

LangGraph#

• useLangGraphRuntime

Local Runtime#

• useLocalRuntime

External Store Runtime#

• useExternalStoreRuntime
• createMessageConverter

Thread List Runtime#

• useRemoteThreadListRuntime
• useCloudThreadListRuntime

Runtime Adapters#

Attachment#

• AttachmentAdapter
• SimpleImageAttachmentAdapter
• SimpleTextAttachmentAdapter
• CompositeAttachmentAdapter

Feedback#

• FeedbackAdapter

Speech#

• SpeechSynthesisAdapter
• WebSpeechSynthesisAdapter

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/assistant-runtime-provider"
tooltip="Provides the highest level context for the assistant-ui"
props="runtime={runtime}"

<Component
name="TextMessagePartProvider"
isContextProvider={true}
providedContexts={[
{
name: "Text MessagePart Context",
color: contextColors["MessagePart Context"],
link: "#MessagePart-context",
},
]}
docsLink="./context-providers/text-message-part-provider"
tooltip="Provides context for text message parts"
props="text={text}"

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

Instructions#

Add system prompt instructions

• useAssistantInstructions

Tool UI#

Register tool UIs

• makeAssistantTool
• makeAssistantToolUI
• useAssistantTool
• useAssistantToolUI

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.

<Component
name="ThreadListPrimitive.Root"
docsLink="#thread-list-primitive-root"
tooltip="Root component for the thread list"

<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={...}"
/>

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

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

ModelContext#

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

ThreadViewportStore#

• useThreadViewport
• useThreadViewportStore

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"

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"

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

Composer Context#

Manages the state and actions for the message composer

ComposerRuntime#

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

ComposerPrimitive#

<Component
name="ComposerPrimitive.Root"
docsLink="#composer-primitive-root"
tooltip="Root component for the composer"



<Component
name="ComposerPrimitive.Attachments"
isContextProvider={true}
providedContexts={[
{
name: "Attachment Context",
color: contextColors["Attachment Context"],
},
]}
docsLink="#composer-primitive-attachments"
tooltip="Manages attachments in the composer"
/>

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

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#

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

ActionBarPrimitive#

<Component
name="ActionBarPrimitive.Root"
docsLink="#action-bar-primitive-root"
tooltip="Root component for the action bar"

BranchPickerPrimitive#

<Component
name="BranchPickerPrimitive.Root"
docsLink="#branch-picker-primitive-root"
tooltip="Root component for the branch picker"

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

MessagePart Context#

Manages the state and actions for message parts within messages

MessagePartRuntime#

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

MessagePartPrimitive#

MarkdownText#

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

Attachment Context#

Manages the state and actions for attachments in messages and composer

AttachmentRuntime#

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

AttachmentPrimitive#

<Component
name="AttachmentPrimitive.Root"
docsLink="#attachment-primitive-root"
tooltip="Root component for an attachment"

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

ThreadListItem Context#

Manages the state and actions for individual thread list items

ThreadListItemRuntime#

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

ThreadListItem#

<Component
name="ThreadListItemPrimitive.Root"
docsLink="#thread-list-item-primitive-root"
tooltip="Root component for a thread list item"
<Component
name="ThreadListItemPrimitive.Trigger"
docsLink="#thread-list-item-primitive-trigger"
tooltip="Trigger for thread list item actions"

Utilities#

• useThreadViewportAutoScroll
• useInlineRender