# Thread
URL: /docs/ui/thread

The main chat container with messages, composer, and auto-scroll.

A complete chat interface that combines message rendering, auto-scrolling, composer input,
attachments, and conditional UI states. Fully customizable and composable.

<ThreadSample />

Anatomy \[#anatomy]

The `Thread` component is built with the following primitives:

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

<ThreadPrimitive.Root>
  <ThreadPrimitive.Viewport>
    <AuiIf condition={(s) => s.thread.isEmpty}>
      <ThreadWelcome />
      {/* ThreadWelcome includes ThreadPrimitive.Suggestions */}
    </AuiIf>

    <ThreadPrimitive.Messages>
      {({ message }) => {
        if (message.role === "user") return <UserMessage />;
        return <AssistantMessage />;
      }}
    </ThreadPrimitive.Messages>

    <ThreadPrimitive.ViewportFooter>
      <ThreadPrimitive.ScrollToBottom />
      <Composer />
    </ThreadPrimitive.ViewportFooter>
  </ThreadPrimitive.Viewport>
</ThreadPrimitive.Root>
```

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add the component \[#add-the-component]

    <InstallCommand shadcn="[&#x22;thread&#x22;]" />

    This adds a `/components/assistant-ui/thread.tsx` file to your project, which you can adjust as needed.
  </Step>

  <Step>
    Use in your application \[#use-in-your-application]

    ```tsx title="/app/page.tsx" {1,6}
    import { Thread } from "@/components/assistant-ui/thread";

    export default function Chat() {
      return (
        <div className="h-full">
          <Thread />
        </div>
      );
    }
    ```
  </Step>
</Steps>

Examples \[#examples]

Welcome Screen \[#welcome-screen]

```tsx
<AuiIf condition={(s) => s.thread.isEmpty}>
  <ThreadWelcome />
</AuiIf>
```

Viewport Spacer \[#viewport-spacer]

```tsx
<AuiIf condition={(s) => !s.thread.isEmpty}>
  <div className="min-h-8 grow" />
</AuiIf>
```

Conditional Send/Cancel Button \[#conditional-sendcancel-button]

```tsx
<AuiIf condition={(s) => !s.thread.isRunning}>
  <ComposerPrimitive.Send>
    Send
  </ComposerPrimitive.Send>
</AuiIf>

<AuiIf condition={(s) => s.thread.isRunning}>
  <ComposerPrimitive.Cancel>
    Cancel
  </ComposerPrimitive.Cancel>
</AuiIf>
```

Suggestions \[#suggestions]

Display suggested prompts using the Suggestions API. See the [Suggestions guide](/docs/guides/suggestions) for detailed configuration.

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

// Configure suggestions in your runtime provider
const aui = useAui({
  suggestions: Suggestions(["What's the weather?", "Tell me a joke"]),
});

// Display suggestions in your thread component
<ThreadPrimitive.Suggestions>
  {() => <SuggestionItem />}
</ThreadPrimitive.Suggestions>

// Custom suggestion item
const SuggestionItem = () => (
  <SuggestionPrimitive.Trigger send asChild>
    <button>
      <SuggestionPrimitive.Title />
    </button>
  </SuggestionPrimitive.Trigger>
);
```

API Reference \[#api-reference]

The following primitives are used within the Thread component and can be customized in your `/components/assistant-ui/thread.tsx` file.

Root \[#root]

Contains all parts of the thread.

<ParametersTable
  type="ThreadPrimitiveRootProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description: &#x22;Merge props with child element instead of rendering a wrapper div.&#x22;,
},
{
name: &#x22;className&#x22;,
type: &#x22;string&#x22;,
description: &#x22;CSS class name.&#x22;,
},
]"
/>

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

Viewport \[#viewport]

The scrollable area containing all messages. Automatically scrolls to the bottom as new messages are added.

<ParametersTable
  type="ThreadPrimitiveViewportProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description: &#x22;Merge props with child element instead of rendering a wrapper div.&#x22;,
},
{
name: &#x22;autoScroll&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to automatically scroll to the bottom when new messages are added while the viewport was previously scrolled to the bottom.&#x22;,
},
{
name: &#x22;className&#x22;,
type: &#x22;string&#x22;,
description: &#x22;CSS class name.&#x22;,
},
]"
/>

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

Messages \[#messages]

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

```tsx
<ThreadPrimitive.Messages>
  {({ message }) => {
    if (message.role === "user") return <UserMessage />;
    return <AssistantMessage />;
  }}
</ThreadPrimitive.Messages>
```

<ParametersTable
  type="ThreadPrimitiveMessagesProps"
  parameters="[
{
name: &#x22;components&#x22;,
type: &#x22;MessageComponents&#x22;,
required: true,
description: &#x22;Components to render for different message types.&#x22;,
children: [
{
type: &#x22;MessageComponents&#x22;,
parameters: [
{
name: &#x22;Message&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Default component for all messages.&#x22;,
},
{
name: &#x22;UserMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Component for user messages.&#x22;,
},
{
name: &#x22;EditComposer&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;Component for user messages being edited.&#x22;,
},
{
name: &#x22;AssistantMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Component for assistant messages.&#x22;,
},
{
name: &#x22;SystemMessage&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Component for system messages.&#x22;,
},
],
},
],
},
]"
/>

MessageByIndex \[#messagebyindex]

Renders a single message at the specified index.

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

<ParametersTable
  type="ThreadPrimitiveMessageByIndexProps"
  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;Components to render for different message types.&#x22;,
},
]"
/>

Empty \[#empty]

Renders children only when there are no messages in the thread.

<ParametersTable
  type="ThreadPrimitiveEmptyProps"
  parameters="[
{
name: &#x22;children&#x22;,
type: &#x22;ReactNode&#x22;,
description: &#x22;Content to display when the thread is empty.&#x22;,
},
]"
/>

ScrollToBottom \[#scrolltobottom]

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

<ParametersTable
  type="ThreadPrimitiveScrollToBottomProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description: &#x22;Merge props with child element instead of rendering a wrapper button.&#x22;,
},
{
name: &#x22;className&#x22;,
type: &#x22;string&#x22;,
description: &#x22;CSS class name.&#x22;,
},
]"
/>

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

Suggestions \[#suggestions-1]

Renders all configured suggestions. Configure suggestions using the `Suggestions()` API in your runtime provider.

```tsx
<ThreadPrimitive.Suggestions>
  {() => <CustomSuggestionComponent />}
</ThreadPrimitive.Suggestions>
```

<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">
  See the [Suggestions guide](/docs/guides/suggestions) for detailed information on configuring and customizing suggestions.
</Callout>

AuiIf \[#auiif]

Conditionally renders children based on assistant state. This is a generic component that can access thread, message, composer, and other state.

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

<AuiIf condition={(s) => s.thread.isEmpty}>
  <WelcomeScreen />
</AuiIf>

<AuiIf condition={(s) => s.thread.isRunning}>
  <LoadingIndicator />
</AuiIf>

<AuiIf condition={(s) => s.message.role === "assistant"}>
  <AssistantAvatar />
</AuiIf>
```

<ParametersTable
  type="AuiIfProps"
  parameters="[
{
name: &#x22;condition&#x22;,
type: &#x22;(state: AssistantState) => boolean&#x22;,
required: true,
description: &#x22;A function that receives the assistant state and returns whether to render children.&#x22;,
},
]"
/>

<Callout type="info">
  The condition function receives an `AssistantState` object with access to `thread`, `message`, `composer`, `part`, and `attachment` state depending on context.
</Callout>

Related Components \[#related-components]

* [ThreadList](/docs/ui/thread-list) - List of threads, with or without sidebar
* [Quoting guide](/docs/guides/quoting) - Quote selected text from messages
* [SelectionToolbarPrimitive](/docs/api-reference/primitives/selection-toolbar) - Floating toolbar API reference