Utility Hooks

Focused helpers for message parts, quotes, timing, and viewport behavior.

Utility hooks expose commonly needed slices of assistant-ui behavior without requiring a full primitive.

Message Helpers

useMessageQuote reads the quote state for the current message.
useMessageTiming reads timing metadata for the current message.

Message Part Helpers

useMessagePartText
useMessagePartReasoning
useMessagePartSource
useMessagePartFile
useMessagePartImage
useMessagePartData

These hooks are intended for custom message part renderers. They read the nearest message part context established by MessagePrimitive.Parts, MessagePartPrimitive, or the lower-level providers.

Viewport Helpers

useThreadViewport reads and controls the thread viewport.
useThreadViewportAutoScroll wires auto-scroll behavior for custom viewport compositions.
useScrollLock helps reasoning and grouped-part UIs preserve scroll behavior while content changes.

For primitive-specific prop APIs, see Primitives.

API Reference

Generated reference for Utilities.

unstable_useCloudThreadListAdapter

Deprecated: Use useCloudThreadListAdapter instead.

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

Source: packages/core/src/react/runtimes/cloud/useCloudThreadListAdapter.tsx

unstable_useMentionAdapter

Deprecated: Under active development and might change without notice.

Creates a spreadable \{ adapter, directive \} bundle for @ mentions. Supports tools registered via useAssistantTool, explicit items, or both — flat or categorized.

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

Source: packages/react/src/unstable/useMentionAdapter.ts

unstable_useSlashCommandAdapter

Deprecated: Under active development and may change without notice.

Bundles slash command definitions (with inline execute callbacks) into \{adapter, action\} that plug directly into ComposerTriggerPopover. execute stays in the hook closure and is never attached to the returned TriggerItem, keeping items serializable.

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

Source: packages/react/src/unstable/useSlashCommandAdapter.ts

unstable_useTriggerPopoverRootContext

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

Source: packages/react/src/primitives/composer/trigger/TriggerPopoverRootContext.tsx

unstable_useTriggerPopoverRootContextOptional

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

Source: packages/react/src/primitives/composer/trigger/TriggerPopoverRootContext.tsx

unstable_useTriggerPopoverScopeContext

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

Source: packages/react/src/primitives/composer/trigger/TriggerPopover.tsx

unstable_useTriggerPopoverScopeContextOptional

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

Source: packages/react/src/primitives/composer/trigger/TriggerPopover.tsx

unstable_useTriggerPopoverTriggers

Live map of registered triggers, re-rendering on change. Prefer subscribeLifecycle for incremental add/remove handling.

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

Source: packages/react/src/primitives/composer/trigger/TriggerPopoverRootContext.tsx

unstable_useTriggerPopoverTriggersOptional

Like useTriggerPopoverTriggers but returns an empty map outside a root.

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

Source: packages/react/src/primitives/composer/trigger/TriggerPopoverRootContext.tsx

useAssistantApi

Deprecated: Use useAui instead. This alias will be removed in v0.13.

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

Source: packages/store/src/useAui.ts

useAssistantEvent

Deprecated: Use useAuiEvent instead. This alias will be removed in v0.13.

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

Source: packages/store/src/useAuiEvent.ts

useAssistantFrameHost

React hook that manages the lifecycle of an AssistantFrameHost and its binding to the current AssistantRuntime.

Usage example:

function MyComponent() {
  const iframeRef = useRef<HTMLIFrameElement>(null);

  useAssistantFrameHost({
    iframeRef,
    targetOrigin: "https://trusted-domain.com", // optional
  });

  return <iframe ref={iframeRef} src="..." />;
}

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

Source: packages/react/src/model-context/frame/useAssistantFrameHost.ts

useAssistantState

Deprecated: Use useAuiState instead. This alias will be removed in v0.13.

Hook to access a slice of the assistant state with automatic subscription

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

Source: packages/store/src/useAuiState.ts

useAttachment

Deprecated: Use useAuiState((s) => s.attachment) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/AttachmentContext.ts

useCloudThreadListAdapter

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

Source: packages/core/src/react/runtimes/cloud/useCloudThreadListAdapter.tsx

useComposer

Deprecated: Use useAuiState((s) => s.composer) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

Hook to access the current composer state.

This hook provides reactive access to the composer's state, including text content, attachments, editing status, and send/cancel capabilities.

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

Source: packages/react/src/legacy-runtime/hooks/ComposerContext.ts

useEditComposer

Deprecated: Use useAuiState((s) => s.message.composer) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/MessageContext.ts

useEditComposerAttachment

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

Source: packages/react/src/legacy-runtime/hooks/AttachmentContext.ts

useExternalMessageConverter

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

Source: packages/core/src/react/runtimes/external-message-converter.ts

useMessage

Deprecated: Use useAuiState((s) => s.message) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

Hook to access the current message state.

This hook provides reactive access to the message's state, including content, role, status, and other message-level properties.

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

Source: packages/react/src/legacy-runtime/hooks/MessageContext.ts

useMessageAttachment

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

Source: packages/react/src/legacy-runtime/hooks/AttachmentContext.ts

useMessagePart

Deprecated: Use useAuiState((s) => s.part) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/MessagePartContext.ts

useMessagePartData

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

Source: packages/react/src/primitives/messagePart/useMessagePartData.ts

useMessagePartFile

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

Source: packages/react/src/primitives/messagePart/useMessagePartFile.ts

useMessagePartImage

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

Source: packages/react/src/primitives/messagePart/useMessagePartImage.ts

useMessagePartReasoning

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

Source: packages/react/src/primitives/messagePart/useMessagePartReasoning.ts

useMessagePartSource

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

Source: packages/react/src/primitives/messagePart/useMessagePartSource.ts

useMessagePartText

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

Source: packages/react/src/primitives/messagePart/useMessagePartText.ts

useMessageQuote

Hook that returns the quote info for the current message, if any.

Reads from message.metadata.custom.quote.

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

Source: packages/react/src/hooks/useMessageQuote.ts

useMessageTiming

Hook that returns timing information for the current assistant message.

Reads from message.metadata.timing.

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

Source: packages/react/src/hooks/useMessageTiming.ts

useRuntimeAdapters

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

Source: packages/core/src/react/runtimes/RuntimeAdapterProvider.tsx

useScrollLock

Locks scroll position during collapsible/height animations and hides scrollbar.

This utility prevents page jumps when content height changes during animations, providing a smooth user experience. It finds the nearest scrollable ancestor and temporarily locks its scroll position while the animation completes.

Prevents forced reflows: no layout reads, mutations scoped to scrollable parent only
Reactive: only intercepts scroll events when browser actually adjusts
Cleans up automatically after animation duration

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

Source: packages/react/src/primitives/reasoning/useScrollLock.ts

useThread

Deprecated: Use useAuiState((s) => s.thread) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

Hook to access the current thread state.

This hook provides reactive access to the thread's state, including messages, running status, capabilities, and other thread-level properties.

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

Source: packages/react/src/legacy-runtime/hooks/ThreadContext.ts

useThreadComposer

Deprecated: Use useAuiState((s) => s.thread.composer) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/ThreadContext.ts

useThreadComposerAttachment

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

Source: packages/react/src/legacy-runtime/hooks/AttachmentContext.ts

useThreadList

Deprecated: Use useAuiState((s) => s.threads) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/AssistantContext.ts

useThreadListItem

Deprecated: Use useAuiState((s) => s.threadListItem) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/ThreadListItemContext.ts

useThreadModelContext

Deprecated: Use useAuiState((s) => s.thread.modelContext) instead. See migration guide: https://assistant-ui.com/docs/migrations/v0-12

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

Source: packages/react/src/legacy-runtime/hooks/ThreadContext.ts

useThreadViewport

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

Source: packages/react/src/context/react/ThreadViewportContext.ts

useThreadViewportAutoScroll

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

Source: packages/react/src/primitives/thread/useThreadViewportAutoScroll.ts

useThreadViewportStore

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

Source: packages/react/src/context/react/ThreadViewportContext.ts