Assistant Context API

🗂️  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.)
        │   ├── 🧠 ChainOfThought (chainOfThought) - Reasoning steps within a message
        │   │   └── 📝 Part (part) - Individual reasoning/tool-call step
        │   ├── 📎 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

💡 Suggestions (suggestions) - Follow-up message suggestions
    └── 💬 Suggestion (suggestion) - Individual suggestion item
🔧 Tools (tools) - Custom UI components for tool calls
🧩 ModelContext (modelContext) - Model context and tool registration

// Inside a message component
function MessageButton() {
  // ✅ Available: message scope (current message)
  const role = useAuiState((s) => s.message.role);

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

import { useAuiState } from "@assistant-ui/react";

// Basic usage - extract a single property
const role = useAuiState((s) => s.message.role); // "user" | "assistant"
const isRunning = useAuiState((s) => s.thread.isRunning); // boolean

// Access nested data
const attachmentCount = useAuiState(
  (s) => s.composer.attachments.length,
);
const lastMessage = useAuiState((s) => s.thread.messages.at(-1));

// Access multiple scopes
const canSend = useAuiState(
  (s) => !s.thread.isRunning && s.composer.text.length > 0,
);

// Compute derived state
const messageCount = useAuiState((s) => s.thread.messages.length);

// ❌ Bad - creates new object every time
const data = useAuiState((s) => ({
  role: s.message.role,
  content: s.message.content,
}));

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

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

// Thread actions
aui.thread.append(message);
aui.thread.startRun(config);
aui.thread.resumeRun(config);
aui.thread.cancelRun();
aui.thread.loadEarlier();
aui.thread.getState();
aui.thread.message({ index: idx });
aui.thread.message({ id: messageId });
aui.thread.composer();

// Message actions
aui.message.reload();
aui.message.speak();
aui.message.stopSpeaking();
aui.message.submitFeedback({ type: "positive" });
aui.message.submitFeedback({ type: "negative", comment: "Quoted the wrong date" });
aui.message.switchToBranch({ position, branchId });
aui.message.getState();
aui.message.part({ index: idx });
aui.message.part({ toolCallId });
aui.message.composer();

// Part actions
aui.part.addToolResult(result);
aui.part.resumeToolCall(result);
aui.part.getState();

// Composer actions
aui.composer.send();
aui.composer.setText(text);
aui.composer.setRole(role);
aui.composer.addAttachment(file); // File object
aui.composer.addAttachment({ name, content }); // external source
await aui.composer.clearAttachments();
await 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.reload();
await aui.threads.getLoadThreadsPromise();
aui.threads.getState();

// ThreadListItem actions
aui.threadListItem.switchTo();
aui.threadListItem.rename(title);
aui.threadListItem.updateCustom(custom);
aui.threadListItem.archive();
aui.threadListItem.unarchive();
aui.threadListItem.delete();
aui.threadListItem.getState();

// Suggestions actions
aui.suggestions.getState();
aui.suggestions.suggestion({ index: 0 });

// Suggestion actions
aui.suggestion.getState();

// ChainOfThought actions
aui.chainOfThought.getState();
aui.chainOfThought.setCollapsed(collapsed);
aui.chainOfThought.part({ index: 0 });

// ModelContext actions — see /docs/copilots/model-context for full usage
aui.modelContext.register(provider);
aui.modelContext.getState();

// Tools actions
aui.tools.setToolUI(toolName, render);
aui.tools.getState();

import { useAuiEvent } from "@assistant-ui/react";

// Listen to current scope events (most common)
useAuiEvent("composer.send", (event) => {
  console.log("Composer sent message in thread:", event.threadId);
});

// Listen to thread events
useAuiEvent("thread.modelContextUpdate", (event) => {
  console.log("Model context updated in thread:", event.threadId);
});

// Listen to all events of a type across all scopes
useAuiEvent({ event: "composer.send", scope: "*" }, (event) => {
  console.log("Any composer sent a message:", event.threadId);
});

// Listen to ALL events (useful for debugging or analytics)
useAuiEvent("*", (event) => {
  console.log("Event occurred:", event.event, event.payload);
});

// Practical example: Track user interactions
function AnalyticsTracker() {
  useAuiEvent("composer.send", (event) => {
    analytics.track("message_sent", {
      threadId: event.threadId,
    });
  });

  return null; // This component only tracks events
}

function MessageButton() {
  const aui = useAui();

  // Automatically uses the current message scope
  const handleReload = () => {
    aui.message.reload();
  };

  return <button onClick={handleReload}>Reload</button>;
}

const role = useAuiState((s) => s.optional.message?.role);

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 list item by ID, index, or the "main" selector
const threadItem = aui.threads.item({ id: "thread_123" });
const threadByIndex = aui.threads.item({ index: 0 });
const archivedThread = aui.threads.item({ index: 0, archived: true });

// Traverse to the main thread directly
const mainThread = aui.threads.thread("main");
const message = aui.threads.thread("main").message({ id: "msg_123" });

function RunIndicator() {
  const isRunning = useAuiState((s) => s.thread.isRunning);

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

function CopyButton() {
  const aui = useAui();

  const handleCopy = () => {
    navigator.clipboard.writeText(aui.message.getCopyText());
  };

  return <button onClick={handleCopy}>Copy</button>;
}

function SmartComposer() {
  const aui = useAui();
  const isRunning = useAuiState((s) => s.thread.isRunning);
  const text = useAuiState((s) => s.composer.text);

  const canSend = !isRunning && text.length > 0;

  return (
    <div>
      <textarea
        value={text}
        onChange={(e) => aui.composer.setText(e.target.value)}
        disabled={isRunning}
      />
      <button onClick={() => aui.composer.send()} disabled={!canSend}>
        Send
      </button>
    </div>
  );
}

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

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

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

const aui = useAui();

// Bound to the thread current at this render
aui.thread.append({ role: "user", content: "Hello" });

// After a thread switch, the component re-renders with a new client.
// Accessors read from a previous render keep pointing at the old thread.

// ❌ Expensive computation in selector (runs on every update of the thread)
const result = useAuiState(
  (s) => s.thread.messages.filter((m) => m.role === "user").length,
);

// ✅ Memoize expensive computations
const messages = useAuiState((s) => s.thread.messages);
const userCount = useMemo(
  () => messages.filter((m) => m.role === "user").length,
  [messages],
);

// ❌ Subscribes to entire thread state
const thread = useAuiState((s) => s.thread);

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

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

// ✅ Read through the optional view — unavailable scopes resolve to undefined
const role = useAuiState((s) => s.optional.message?.role ?? "none");

// ❌ Creating new objects in selectors causes infinite re-renders
const data = useAuiState((s) => ({
  role: s.message.role,
  content: s.message.content, // New object every time!
}));

// ✅ Return primitive values or use separate selectors
const role = useAuiState((s) => s.message.role);
const content = useAuiState((s) => s.message.content);

// ❌ 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]);

// Read state
const value = useAuiState((s) => s.scope.property);

// Perform action
const aui = useAui();
aui.scope.action();

// Listen to events
useAuiEvent("source.event", (e) => {});

// Read a scope that may be unavailable
const maybe = useAuiState((s) => s.optional.scope?.property);

// Get state imperatively
const state = aui.scope.getState();

// Navigate scopes
aui.thread.message({ id: "..." }).getState();