# ThreadPrimitive
URL: /docs/api-reference/primitives/thread

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

A conversation between a user and an assistant.

Anatomy \[#anatomy]

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

const Thread = () => (
  <ThreadPrimitive.Root>
    <ThreadPrimitive.Viewport>
      <AuiIf condition={(s) => s.thread.isEmpty}>...</AuiIf>
      <ThreadPrimitive.Messages>{...}</ThreadPrimitive.Messages>
      <ThreadPrimitive.ViewportFooter className="sticky bottom-0">
        <Composer />
      </ThreadPrimitive.ViewportFooter>
    </ThreadPrimitive.Viewport>
  </ThreadPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the thread.

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

<ParametersTable
  type="ThreadPrimitiveRootProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

Viewport \[#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.

<ParametersTable
  type="ThreadPrimitiveViewportProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
{
name: &#x22;autoScroll&#x22;,
type: &#x22;boolean&#x22;,
default: 'true (false when turnAnchor is &#x22;top&#x22;)',
description:
&#x22;Whether to automatically scroll to the bottom of the viewport when new messages are added while the viewport was previously scrolled to the bottom.&#x22;,
},
{
name: &#x22;turnAnchor&#x22;,
type: '&#x22;top&#x22; | &#x22;bottom&#x22;',
default: '&#x22;bottom&#x22;',
description:
'Controls scroll anchoring behavior for new messages. &#x22;bottom&#x22; is the classic chat behavior where messages anchor at the bottom. &#x22;top&#x22; anchors new user messages at the top of the viewport for a focused reading experience.',
},
{
name: &#x22;scrollToBottomOnRunStart&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description: &#x22;Whether to scroll to bottom when a new run starts.&#x22;,
},
{
name: &#x22;scrollToBottomOnInitialize&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to scroll to bottom when thread history is first loaded.&#x22;,
},
{
name: &#x22;scrollToBottomOnThreadSwitch&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to scroll to bottom when switching to a different thread.&#x22;,
},
]"
/>

ViewportFooter \[#viewportfooter]

A footer container placed inside `ThreadPrimitive.Viewport` that measures its own height (including top margin) and reports it to the viewport context. The viewport uses this measurement in scroll calculations — for example, as the minimum height for `ViewportSlack` — so that the scroll-to-bottom behaviour accounts for any sticky footer overlapping the message list.

Multiple `ViewportFooter` components may be used; their heights are summed.

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

```tsx
<ThreadPrimitive.Viewport>
  <ThreadPrimitive.Messages>{...}</ThreadPrimitive.Messages>
  <ThreadPrimitive.ViewportFooter className="sticky bottom-0">
    <Composer />
  </ThreadPrimitive.ViewportFooter>
</ThreadPrimitive.Viewport>
```

<ParametersTable
  type="ThreadPrimitiveViewportFooterProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

Messages \[#messages]

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

<ParametersTable
  type="ThreadPrimitiveMessagesProps"
  parameters="[
{
name: &#x22;components&#x22;,
type: &#x22;MessageComponents&#x22;,
description: &#x22;The component to render for each message.&#x22;,
children: [
{
type: &#x22;MessageComponents&#x22;,
parameters: [
{
name: &#x22;Message&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for each message.&#x22;,
},
{
name: &#x22;UserMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for user messages.&#x22;,
},
{
name: &#x22;AssistantMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for assistant messages.&#x22;,
},
{
name: &#x22;SystemMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for system messages.&#x22;,
},
{
name: &#x22;EditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when any message type is being edited. Used as a fallback when a role-specific edit composer is not provided.&#x22;,
},
{
name: &#x22;UserEditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when a user message is being edited. Takes precedence over EditComposer for user messages.&#x22;,
},
{
name: &#x22;AssistantEditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when an assistant message is being edited. Takes precedence over EditComposer for assistant messages.&#x22;,
},
{
name: &#x22;SystemEditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when a system message is being edited. Takes precedence over EditComposer for system messages.&#x22;,
},
],
},
],
},
]"
/>

MessageByIndex \[#messagebyindex]

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

```tsx
<ThreadPrimitive.MessageByIndex index={0}>
  {({ message }) => message.role === "user" ? <MyUserMessage /> : <MyAssistantMessage />}
</ThreadPrimitive.MessageByIndex>
```

<ParametersTable
  type="ThreadPrimitive.MessageByIndex.Props"
  parameters="[
{
name: &#x22;index&#x22;,
type: &#x22;number&#x22;,
required: true,
description: &#x22;The index of the message to render.&#x22;,
},
{
name: &#x22;components&#x22;,
type: &#x22;MessageComponents&#x22;,
description: &#x22;The component configuration for rendering the message.&#x22;,
children: [
{
type: &#x22;MessageComponents&#x22;,
parameters: [
{
name: &#x22;Message&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for each message.&#x22;,
},
{
name: &#x22;UserMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for user messages.&#x22;,
},
{
name: &#x22;AssistantMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for assistant messages.&#x22;,
},
{
name: &#x22;SystemMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for system messages.&#x22;,
},
{
name: &#x22;EditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when any message type is being edited. Used as a fallback when a role-specific edit composer is not provided.&#x22;,
},
{
name: &#x22;UserEditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when a user message is being edited. Takes precedence over EditComposer for user messages.&#x22;,
},
{
name: &#x22;AssistantEditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when an assistant message is being edited. Takes precedence over EditComposer for assistant messages.&#x22;,
},
{
name: &#x22;SystemEditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render when a system message is being edited. Takes precedence over EditComposer for system messages.&#x22;,
},
],
},
],
},
]"
/>

Empty \[#empty]

<Callout type="warn">
  **Deprecated.** Use `<AuiIf condition={(s) => s.thread.isEmpty}>` instead.
</Callout>

Renders children only when there are no messages.

ScrollToBottom \[#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.

<ParametersTable
  type="ThreadPrimitiveScrollToBottomProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
{
name: &#x22;behavior&#x22;,
type: '&#x22;auto&#x22; | &#x22;instant&#x22; | &#x22;smooth&#x22;',
description:
&#x22;The scroll behavior to use when scrolling to the bottom. Passed to the browser's scrollIntoView API.&#x22;,
},
]"
/>

Suggestion \[#suggestion]

A button that applies a suggestion prompt to the composer. When clicked, it sets the composer text to the given prompt and optionally sends the message immediately.

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

```tsx
<ThreadPrimitive.Suggestion prompt="Tell me a joke" send>
  Tell me a joke
</ThreadPrimitive.Suggestion>
```

<ParametersTable
  type="ThreadPrimitiveSuggestionProps"
  parameters="[
{
name: &#x22;prompt&#x22;,
type: &#x22;string&#x22;,
required: true,
description:
&#x22;The text to place in the composer when this suggestion is activated.&#x22;,
},
{
name: &#x22;send&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description:
&#x22;When true, immediately sends the message instead of only populating the composer.&#x22;,
},
{
name: &#x22;clearComposer&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;When send is false, determines whether the composer text is replaced by the prompt (true) or appended to it (false).&#x22;,
},
{
name: &#x22;asChild&#x22;,
},
]"
/>

`ThreadPrimitive.Suggestions` \[#threadprimitivesuggestions]

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

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

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

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

<ParametersTable
  type="ThreadPrimitiveSuggestionsProps"
  parameters="[
{
name: &#x22;components&#x22;,
type: &#x22;{ Suggestion: ComponentType }&#x22;,
description: &#x22;Custom component to render each suggestion.&#x22;,
},
]"
/>

<Callout type="info">
  Configure suggestions using the `Suggestions()` API in your runtime provider. See the [Suggestions guide](/docs/guides/suggestions) for details.
</Callout>