logoassistant-ui
Reference

Context API

assistant-ui components and APIs use React Context to store information and interact with the runtime.

The context is split into four hierarchies:

  • Assistant Context: Wraps your entire app. An app can contain multiple threads.
  • Thread Context: Provides access to the thread state. A thread can contain multiple messages.
  • Message Context: Provides access to the message state. A message can contain multiple content parts.
  • Content Part Context: Provides access to the content part state.

Assistant Context

useAssistantActions

import { useAssistantActions } from "@assistant-ui/react";
 
const actions = useAssistantActions();
const switchToNewThread = useAssistantActions((m) => m.switchToThread);

AssistantActionsState

switchToThread:

(threadId: string | null) => void

Switch to a new thread.

getRuntime:

() => AssistantRuntime

Get the current runtime.

useToolUIs

import { useToolUIs } from "@assistant-ui/react";
 
const toolUIs = useToolUIs();
const getToolUI = useToolUIs((m) => m.getToolUI);

AssistantToolUIsState

getToolUI:

(toolName: string) => ToolCallContentPartProps

Gets the current tool UI for a given tool name.

ToolCallContentPartProps<TArgs, TResult>

part?:

ToolCallContentPart<TArgs, TResult>

The tool call content part.

status?:

ContentPartStatus

The tool call status.

addResult?:

(result: TResult) => void

Adds a result to the tool call.

setToolUI:

(toolName: string, render: ToolCallContentPartComponent) => Unsubscribe

Sets the tool UI.

Thread Context

useThread

import { useThread } from "@assistant-ui/react";
 
const thread = useThread();
const isRunning = useThread((m) => m.isRunning);

ThreadState

isRunning:

boolean

Whether the thread is running.

isDisabled:

boolean

Whether the thread is disabled.

useThreadMessages

import { useThreadMessages } from "@assistant-ui/react";
 
const messages = useThreadMessages();
const firstMessage = useThreadMessages((m) => m[0]);

ThreadMessagesState

messages:

readonly ThreadMessage[]

The messages in the thread.

useThreadActions

import { useThreadActions } from "@assistant-ui/react";
 
const actions = useThreadActions();
const getBranches = useThreadActions((m) => m.getBranches);

ThreadActionsState

getBranches:

(messageId: string) => readonly string[]

A function to get the branches for a message.

switchToBranch:

(branchId: string) => void

A function to switch to a branch.

append:

(message: AppendMessage) => void

A function to append a message to the thread.

startRun:

(parentId: string | null) => void

A function to start a run.

cancelRun:

() => void

A function to cancel a run.

addToolResult:

(options: AddToolResultOptions) => void

A function to add a tool result.

useThreadRuntime

import { useThreadRuntime } from "@assistant-ui/react";
 
const runtime = useThreadRuntime();

useThreadComposer

import { useThreadComposer } from "@assistant-ui/react";
 
const composer = useThreadComposer();
const text = useThreadComposer((m) => m.text);

ComposerState

text:

string

The current text of the composer.

setText:

(text: string) => void

A function to set the text of the composer.

attachments:

readonly Attachment[]

The current attachments of the composer.

addAttachment:

(attachment: Attachment) => void

A function to add an attachment to the composer.

removeAttachment:

(attachmentId: string) => void

A function to remove an attachment from the composer.

reset:

() => void

A function to reset the composer.

canCancel:

true

Whether the composer can be canceled.

isEditing:

true

Whether the composer is in edit mode.

send:

() => void

A function to send the message.

cancel:

() => void

A function to cancel the run.

focus:

() => void

A function to focus the composer.

onFocus:

(listener: () => void) => Unsubscribe

A function to subscribe to focus events.

useThreadViewport

import { useThreadViewport } from "@assistant-ui/react";
 
const threadViewport = useThreadViewport();
const isAtBottom = useThreadViewport((m) => m.isAtBottom);

ThreadViewportState

isAtBottom:

boolean

Whether the thread is at the bottom.

scrollToBottom:

() => void

A function to scroll to the bottom.

onScrollToBottom:

(callback: () => void) => Unsubscribe

A function to subscribe to scroll to bottom events.

Message Context

useMessage

import { useMessage } from "@assistant-ui/react";
 
const { message } = useMessage();
const message = useMessage((m) => m.message);

MessageState

message:

Readonly<ThreadMessage>

The current message.

parentId:

string | null

The parent message id.

branches:

readonly string[]

The branches for the message.

isLast:

boolean

Whether the message is the last in the thread.

useMessageUtils

import { useMessageUtils } from "@assistant-ui/react";
 
const messageUtils = useMessageUtils();
const isCopied = useMessageUtils((m) => m.isCopied);

MessageUtilsState

isCopied:

boolean

Whether the message is copied.

setIsCopied:

(value: boolean) => void

A function to set the is copied.

isHovering:

boolean

Whether the message is being hovered.

setIsHovering:

(value: boolean) => void

A function to set the is hovering.

isSpeaking:

boolean

Whether the message is currently being spoken.

stopSpeaking:

() => void

A function to stop the message from being spoken.

addUtterance:

(utterance: SpeechSynthesisAdapter.Utterance) => void

A function to add a speech utterance.

useEditComposer

import { useEditComposer } from "@assistant-ui/react";
 
const editComposer = useEditComposer();
const text = useEditComposer((m) => m.text);

EditComposerState

text:

string

The current text of the composer.

setText:

(text: string) => void

A function to set the text of the composer.

attachments:

readonly Attachment[]

The current attachments of the composer.

addAttachment:

(attachment: Attachment) => void

A function to add an attachment to the composer.

removeAttachment:

(attachmentId: string) => void

A function to remove an attachment from the composer.

reset:

() => void

A function to reset the composer.

canCancel:

boolean

Whether the composer can be canceled.

isEditing:

boolean

Whether the composer is in edit mode.

edit:

() => void

A function to enter edit mode.

send:

() => void

A function to send the message.

cancel:

() => void

A function to exit the edit mode.

Content Part Context

useContentPart

import { useContentPart } from "@assistant-ui/react";
 
const part = useContentPart((m) => m.part);
const part = useContentPart.getState().part;
 
const status = useContentPart((m) => m.status);
const status = useContentPart.getState().status;

ContentPartState

part:

Readonly<ContentPartState>

The current content part.

status:

MessageStatus

The current content part status.

MessageStatus

type:

'running' | 'requires-action' | 'complete' | 'incomplete'

The status.

finish-reason?:

'stop' | 'cancelled' | 'length' | 'content-filter' | 'tool-calls' | 'other' | 'unknown'

The finish reason if the status is 'incomplete'.

error?:

unknown

The error object if the status is 'error'.

Composer Context

Grabs the nearest composer state (either the edit composer or the thread's new message composer).

useComposer

import { useComposer } from "@assistant-ui/react";
 
const composer = useComposer();
const text = useComposer((m) => m.text);

Attachment Context

Grabs the attachment state (either the composer or message attachment).

useAttachment

import { useAttachment } from "@assistant-ui/react";
 
const { attachment } = useAttachment();
const attachment = useAttachment((m) => m.attachment);

useComposerAttachment (Composer)

import { useComposerAttachment } from "@assistant-ui/react";
 
const { attachment } = useComposerAttachment();
const attachment = useComposerAttachment((m) => m.attachment);

ComposerAttachmentState

attachment:

ComposerAttachment

The current composer attachment.

useMessageAttachment (Message)

import { useMessageAttachment } from "@assistant-ui/react";
 
const { attachment } = useMessageAttachment();
const attachment = useMessageAttachment((m) => m.attachment);

MessageAttachmentState

attachment:

MessageAttachment

The current message attachment.

Previous

Runtime API

Next

@assistant-ui/react-ai-sdk

On this page

Assistant ContextuseAssistantActionsuseToolUIsThread ContextuseThreaduseThreadMessagesuseThreadActionsuseThreadRuntimeuseThreadComposeruseThreadViewportMessage ContextuseMessageuseMessageUtilsuseEditComposerContent Part ContextuseContentPartComposer ContextuseComposerAttachment ContextuseAttachmentuseComposerAttachment (Composer)useMessageAttachment (Message)
Edit on Github