Thread

Build custom scrollable message containers with auto-scroll, empty states, and message rendering.

The Thread primitive is the scrollable message container. It handles viewport management, auto-scrolling, empty states, message rendering, and suggestions. You provide the layout and styling.

Welcome!

Ask a question to get started.

Quick Start

Minimal example:

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

<ThreadPrimitive.Root>
  <ThreadPrimitive.Viewport>
    <ThreadPrimitive.Messages>
      {() => <MyMessage />}
    </ThreadPrimitive.Messages>
  </ThreadPrimitive.Viewport>
</ThreadPrimitive.Root>

Root renders a <div>, Viewport renders a scrollable <div>, and Messages iterates over the thread's messages. Add your own styles and components.

Info

Runtime setup: primitives require runtime context. Wrap your UI in AssistantRuntimeProvider with a runtime (for example useLocalRuntime(...)). See Pick a Runtime.

Core Concepts

Viewport & Auto-Scroll

Viewport is the scrollable container. It auto-scrolls to the bottom as new content streams in, but only if the user hasn't scrolled up manually. Expanding a disclosure inside a message, such as a collapsible tool call card (a control with aria-expanded="false" that opens no popup, or the <summary> of a closed <details>), pauses it so the card stays where the user opened it; other clicks, text selection and keystrokes keep following, and scrolling back to the bottom or using ThreadPrimitive.ScrollToBottom resumes it. A new run or a thread switch also ends the pause. Set autoScroll={false} to disable this entirely.

<ThreadPrimitive.Viewport autoScroll={true}>
  {/* messages */}
</ThreadPrimitive.Viewport>

Turn Anchor

By default, new messages appear at the bottom and scroll down. With turnAnchor="top", the user's message anchors to the top of the viewport. The question stays at the top and the response streams in below it.

<ThreadPrimitive.Viewport turnAnchor="top">
  {/* messages */}
</ThreadPrimitive.Viewport>

When turnAnchor="top" is set, MessagePrimitive.Root registers the latest assistant message as the top-anchor target and the preceding user message as the anchor, so no additional component is required. The viewport itself manages a stable reserve element that provides the missing scroll range while the assistant response grows. This is the behavior used by the Thread component by default.

Use topAnchorMessageClamp to control how much of a long user message remains visible when turnAnchor="top". Messages up to tallerThan stay fully visible. For messages taller than that, visibleHeight controls how much of the message's bottom edge remains visible above the assistant response:

<ThreadPrimitive.Viewport
  turnAnchor="top"
  topAnchorMessageClamp={{ tallerThan: "10em", visibleHeight: "6em" }}
>
  {/* messages */}
</ThreadPrimitive.Viewport>

Viewport Scroll Options

ThreadPrimitive.Viewport has three event-specific scroll controls:

  • scrollToBottomOnRunStart (default true): scrolls when thread.runStart fires; it has no effect with turnAnchor="top"
  • scrollToBottomOnInitialize (default true): scrolls when the thread's messages first load
  • scrollToBottomOnThreadSwitch (default true): scrolls when threads.selectionChanged fires

These work alongside autoScroll. If autoScroll is omitted, it defaults to true for turnAnchor="bottom" and false for turnAnchor="top".

<ThreadPrimitive.Viewport
  turnAnchor="top"
  autoScroll={false}
  scrollToBottomOnRunStart={true}
  scrollToBottomOnInitialize={false}
  scrollToBottomOnThreadSwitch={true}
>
  <ThreadPrimitive.Messages>
    {({ message }) => {
      if (message.role === "user") return <UserMessage />;
      return <AssistantMessage />;
    }}
  </ThreadPrimitive.Messages>
</ThreadPrimitive.Viewport>

ViewportFooter

ViewportFooter registers its height so the auto-scroll system accounts for it. It does not position itself; add sticky bottom-0 to keep it at the bottom of the viewport. This is where you place your composer:

<ThreadPrimitive.Viewport>
  <ThreadPrimitive.Messages>
    {() => <MyMessage />}
  </ThreadPrimitive.Messages>
  <ThreadPrimitive.ViewportFooter className="sticky bottom-0">
    <MyComposer />
  </ThreadPrimitive.ViewportFooter>
</ThreadPrimitive.Viewport>

Empty State

Warning

ThreadPrimitive.Empty is deprecated. Use AuiIf instead.

<AuiIf condition={(s) => s.thread.isEmpty}>
  <div className="flex flex-col items-center gap-2 text-center">
    <h2>Welcome!</h2>
    <p>How can I help you today?</p>
  </div>
</AuiIf>

Messages Iterator

Messages takes a children render function. It gives you the current message state so you can branch inline:

<ThreadPrimitive.Messages>
  {({ message }) => {
    if (message.composer.isEditing) return <MyEditComposer />;
    if (message.role === "user") return <MyUserMessage />;
    return <MyAssistantMessage />;
  }}
</ThreadPrimitive.Messages>

components is deprecated. Use the children render function instead.

Suggestions Iterator

Suggestions follows the same pattern. Prefer the children render function when rendering custom suggestion UIs:

<ThreadPrimitive.Suggestions>
  {() => <MySuggestionButton />}
</ThreadPrimitive.Suggestions>

Parts

Root

Top-level container for a thread layout. Renders a <div> element unless asChild is set.

<ThreadPrimitive.Root className="flex h-full flex-col">
  <ThreadPrimitive.Viewport>
    <ThreadPrimitive.Messages>
      {() => <MyMessage />}
    </ThreadPrimitive.Messages>
  </ThreadPrimitive.Viewport>
</ThreadPrimitive.Root>

Viewport

The scrollable area with auto-scroll behavior. Renders a <div> element unless asChild is set.

<ThreadPrimitive.Viewport
  turnAnchor="top"
  autoScroll={false}
  scrollToBottomOnRunStart={true}
>
  <ThreadPrimitive.Messages>
    {({ message }) => {
      if (message.role === "user") return <UserMessage />;
      return <AssistantMessage />;
    }}
  </ThreadPrimitive.Messages>
</ThreadPrimitive.Viewport>

Prop

Type

ViewportFooter

Footer container that registers its height with the viewport scroll system. Renders a <div> element unless asChild is set.

<ThreadPrimitive.ViewportFooter className="sticky bottom-0 pt-2">
  <ComposerPrimitive.Root>...</ComposerPrimitive.Root>
</ThreadPrimitive.ViewportFooter>

ViewportProvider

Provides viewport context without rendering a scrollable element. Use this when you have a custom scroll container.

<ThreadPrimitive.ViewportProvider>
  <div className="flex-1 overflow-y-auto">
    <ThreadPrimitive.Messages>
      {() => <MyMessage />}
    </ThreadPrimitive.Messages>
    <ThreadPrimitive.ViewportFooter>
      <MyComposer />
    </ThreadPrimitive.ViewportFooter>
  </div>
</ThreadPrimitive.ViewportProvider>

ViewportSlack

Warning

ThreadPrimitive.ViewportSlack has been removed from the public API. Top-anchor target registration is handled automatically by MessagePrimitive.Root when turnAnchor="top". Remove ViewportSlack from your tree; if you customized fillClampThreshold or fillClampOffset on ViewportSlack or MessagePrimitive.Root, replace those props with topAnchorMessageClamp on ThreadPrimitive.Viewport.

Messages

Renders a component for each message in the thread, resolved by role and edit state.

<ThreadPrimitive.Messages>
  {({ message }) => {
    if (message.composer.isEditing) return <MyEditComposer />;
    if (message.role === "user") return <MyUserMessage />;
    return <MyAssistantMessage />;
  }}
</ThreadPrimitive.Messages>

Prop

Type

MessageByIndex

Renders a single message at a specific index in the thread.

<ThreadPrimitive.MessageByIndex
  index={0}
  components={{ Message: MyMessage }}
/>

Prop

Type

index
number
components
MessagesComponentConfig

Unstable_MessageById

Renders a single message by id with the same components surface as MessageByIndex. Pair it with unstable_useThreadMessageIds for virtualized or custom message lists that should stay attached to messages across reordering and windowing. Unknown ids render null.

const messageIds = unstable_useThreadMessageIds();

messageIds.map((messageId) => (
  <ThreadPrimitive.Unstable_MessageById
    key={messageId}
    messageId={messageId}
    components={{ Message: MyMessage }}
  />
));

Warning

unstable_useThreadMessageIds and ThreadPrimitive.Unstable_MessageById are experimental and may change in any release.

Row

Renders one row of a thread flattened by createThreadRowsSelector, for virtualized lists: a whole user or system message (or any message being edited), one top-level node of an assistant message's part grouping, or the end of a turn. It mounts only the row's message scope and, for a part row, only that row's parts; a row whose message has left the thread renders nothing. The render function switches on type, and a part row receives part and children exactly as MessagePrimitive.GroupedParts passes them. See the virtualization guide.

const selectRows = createThreadRowsSelector();

function Rows() {
  const rows = useAuiState(selectRows);
  return rows.map((row) => (
    <ThreadPrimitive.Row key={row.key} row={row}>
      {renderRow}
    </ThreadPrimitive.Row>
  ));
}

ScrollToBottom

Scrolls the viewport to the bottom. Disabled when the viewport is already at the bottom. Renders a <button> element unless asChild is set.

<ThreadPrimitive.ScrollToBottom className="rounded-full bg-background p-2 shadow-md">
  <ArrowDownIcon />
</ThreadPrimitive.ScrollToBottom>

Prop

Type

behavior?
ScrollBehavior

LoadEarlier

Loads the page before the first loaded message through aui.thread.loadEarlier(). Disabled while thread.hasEarlier is false; a press while a page loads (thread.isLoadingEarlier) joins that load, so the button keeps keyboard focus until the page lands. The runtime decides both, for example an external store adapter's hasEarlier and onLoadEarlier. Renders a <button> element unless asChild is set. The viewport keeps the visible messages in place when the page lands above them.

<AuiIf condition={(s) => s.thread.hasEarlier || s.thread.isLoadingEarlier}>
  <ThreadPrimitive.LoadEarlier className="self-center text-sm">
    Load earlier messages
  </ThreadPrimitive.LoadEarlier>
</AuiIf>

Suggestions

Renders suggestion prompts via a component.

<ThreadPrimitive.Suggestions>
  {({ suggestion }) => <MySuggestionButton prompt={suggestion.prompt} />}
</ThreadPrimitive.Suggestions>

Prop

Type

SuggestionByIndex

Renders a single suggestion at a specific index.

<ThreadPrimitive.SuggestionByIndex
  index={0}
  components={{ Suggestion: MySuggestion }}
/>

Prop

Type

index
number
components
SuggestionsComponentConfig

Suggestion

Self-contained suggestion button that takes its prompt as a prop instead of reading the suggestions scope. Renders a <button> element unless asChild is set.

<ThreadPrimitive.Suggestion prompt="Write a blog post" send />

Prop

Type

Empty

Warning

Deprecated. Use AuiIf with s.thread.isEmpty instead.

Legacy helper that only renders its children when the thread is empty.

<ThreadPrimitive.Empty>
  <div className="text-center text-muted-foreground">
    No messages yet.
  </div>
</ThreadPrimitive.Empty>

If (deprecated)

Warning

Deprecated. Use AuiIf instead.

// Before (deprecated)
<ThreadPrimitive.If empty>...</ThreadPrimitive.If>
<ThreadPrimitive.If running>...</ThreadPrimitive.If>
<ThreadPrimitive.If disabled>...</ThreadPrimitive.If>

// After
<AuiIf condition={(s) => s.thread.isEmpty}>...</AuiIf>
<AuiIf condition={(s) => s.thread.isRunning}>...</AuiIf>
<AuiIf condition={(s) => s.thread.isDisabled}>...</AuiIf>

Patterns

Welcome Screen with Suggestions

<AuiIf condition={(s) => s.thread.isEmpty}>
  <div className="flex flex-col items-center gap-4 text-center">
    <h2>What can I help with?</h2>
    <div className="grid grid-cols-2 gap-2">
      <ThreadPrimitive.Suggestions>
        {() => <MySuggestionButton />}
      </ThreadPrimitive.Suggestions>
    </div>
  </div>
</AuiIf>

Scroll-to-Bottom Button

<ThreadPrimitive.ScrollToBottom className="fixed bottom-24 right-4 rounded-full bg-background p-2 shadow-md">
  <ArrowDownIcon />
</ThreadPrimitive.ScrollToBottom>

Turn Anchor Top Layout

<ThreadPrimitive.Root className="flex h-full flex-col">
  <ThreadPrimitive.Viewport turnAnchor="top" className="flex-1 overflow-y-auto">
    <ThreadPrimitive.Messages>
      {({ message }) => {
        if (message.role === "user") return <UserMessage />;
        return <AssistantMessage />;
      }}
    </ThreadPrimitive.Messages>
    <ThreadPrimitive.ViewportFooter className="sticky bottom-0">
      <MyComposer />
    </ThreadPrimitive.ViewportFooter>
  </ThreadPrimitive.Viewport>
</ThreadPrimitive.Root>

Custom Message Components

<ThreadPrimitive.Messages>
  {({ message }) => {
    if (message.role === "user") {
      return (
        <MessagePrimitive.Root>
          <div className="ml-auto rounded-xl bg-blue-500 p-3 text-white">
            <MessagePrimitive.Parts />
          </div>
        </MessagePrimitive.Root>
      );
    }

    return (
      <MessagePrimitive.Root>
        <div className="rounded-xl bg-gray-100 p-3">
          <MessagePrimitive.Parts />
        </div>
      </MessagePrimitive.Root>
    );
  }}
</ThreadPrimitive.Messages>

Relationship to Components

The Thread component is a full chat interface built from these primitives with Tailwind styling. Start there for a default implementation. Reach for ThreadPrimitive when you need a custom layout, different scroll behavior, or a non-standard thread structure.

API Reference

For full prop details on every part, see the ThreadPrimitive API Reference.

Related:

On this page

View as MarkdownEdit on GitHub