# Utility Hooks
URL: /docs/api-reference/hooks/utilities

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

> For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths.

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](/docs/api-reference/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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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) =&gt; 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`