ThreadPrimitive

Primitives for the message list, viewport, and welcome screen.

A conversation between a user and an assistant.

Anatomy

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

const Thread = () => (
  <ThreadPrimitive.Root>
    <ThreadPrimitive.Viewport>
      <AuiIf condition={(s) => s.thread.isEmpty}>...</AuiIf>
      <ThreadPrimitive.Messages components={...} />
    </ThreadPrimitive.Viewport>
    <Composer />
  </ThreadPrimitive.Root>
);

API Reference

Root

Containts all parts of the thread.

This primitive renders a <div> element unless asChild is set.

ThreadPrimitiveRootProps

asChild: boolean= false

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

Viewport

The scrollable area containing all messages. Anchors scroll to the bottom as new messages are added.

This primitive renders a <div> element unless asChild is set.

ThreadPrimitiveViewportProps

asChild: boolean= false

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

autoScroll: boolean= true

Whether to automatically scroll to the bottom of the viewport when new messages are added while the viewport is was previously scrolled to the bottom.

Messages

Renders all messages. This primitive renders a separate component for each message.

ThreadPrimitiveMessagesProps

components?: MessageComponents

The component to render for each message.

MessageComponents

Message?: ComponentType

The component to render for each message.

UserMessage?: ComponentType

The component to render for user messages.

EditComposer?: ComponentType

The component to render for user messages that are being edited.

AssistantMessage?: ComponentType

The component to render for assistant messages.

MessageByIndex

Renders a single message at the specified index in the current thread.

<ThreadPrimitive.MessageByIndex
  index={0}
  components={{
    UserMessage: MyUserMessage,
    AssistantMessage: MyAssistantMessage
  }}
/>

ThreadPrimitive.MessageByIndex.Props

indexrequired: number

The index of the message to render.

components?: MessageComponents

The component configuration for rendering the message.

MessageComponents

Message?: ComponentType

The component to render for each message.

UserMessage?: ComponentType

The component to render for user messages.

EditComposer?: ComponentType

The component to render for user messages that are being edited.

AssistantMessage?: ComponentType

The component to render for assistant messages.

Empty

Renders children only when there are no messages.

ScrollToBottom

A button to scroll the viewport to the bottom. Disabled when the viewport is already at bottom.

This primitive renders a <button> element unless asChild is set.

ThreadPrimitiveScrollToBottomProps

asChild: boolean= false

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

`ThreadPrimitive.Suggestions`

Renders all configured suggestions from the Suggestions API. Each suggestion is rendered using the provided Suggestion component.

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

const SuggestionsList = () => {
  return (
    <div className="grid grid-cols-2 gap-2">
      <ThreadPrimitive.Suggestions
        components={{
          Suggestion: SuggestionItem,
        }}
      />
    </div>
  );
};

const SuggestionItem = () => (
  <SuggestionPrimitive.Trigger send asChild>
    <button className="p-3 border rounded">
      <SuggestionPrimitive.Title />
      <SuggestionPrimitive.Description />
    </button>
  </SuggestionPrimitive.Trigger>
);

ThreadPrimitiveSuggestionsProps

components?: { Suggestion: ComponentType }

Custom component to render each suggestion.

Configure suggestions using the Suggestions() API in your runtime provider. See the Suggestions guide for details.