assistant-ui Primitives

Always consult assistant-ui.com/llms.txt for the latest API.

Composable, unstyled components following Radix UI patterns.

References

• ./references/thread.md -- ThreadPrimitive deep dive
• ./references/composer.md -- ComposerPrimitive deep dive
• ./references/message.md -- MessagePrimitive deep dive
• ./references/action-bar.md -- ActionBarPrimitive deep dive
• ./references/part-grouping.md -- Part grouping and chain-of-thought UI
• ./references/mentions.md -- Composer mentions and slash commands

Import

import {
  AuiIf,
  ThreadPrimitive,
  ComposerPrimitive,
  MessagePrimitive,
  ActionBarPrimitive,
  BranchPickerPrimitive,
  AttachmentPrimitive,
  ThreadListPrimitive,
  ThreadListItemPrimitive,
} from "@assistant-ui/react";

Primitive Parts

Primitive	Key Parts
ThreadPrimitive	.Root, .Viewport, .ViewportFooter, .Messages, .Empty, .ScrollToBottom, .Suggestions, .Suggestion
ComposerPrimitive	.Root, .Input, .Send, .Cancel, .Attachments, .AddAttachment, .AttachmentDropzone, .Quote, .QuoteText, .QuoteDismiss, .Dictate, .StopDictation, .DictationTranscript, .Queue
MessagePrimitive	.Root, .Parts (.Content is a deprecated alias), .GroupedParts, .Attachments, .Quote, .GenerativeUI, .Error
ActionBarPrimitive	.Root, .Copy, .Edit, .Reload, .Speak, .StopSpeaking, .FeedbackPositive, .FeedbackNegative, .ExportMarkdown
BranchPickerPrimitive	.Root, .Previous, .Next, .Number, .Count
ThreadListPrimitive	.Root, .New, .Items, .LoadMore
ThreadListItemPrimitive	.Root, .Trigger, .Title, .Archive, .Unarchive, .Delete
AttachmentPrimitive	.Root, .Name, .Remove, .unstable_Thumb

Also exported, each covered by its own reference or skill: ChainOfThoughtPrimitive, SelectionToolbarPrimitive, SuggestionPrimitive, QueueItemPrimitive, ErrorPrimitive, MessagePartPrimitive, AssistantModalPrimitive, ActionBarMorePrimitive, ThreadListItemMorePrimitive.

Custom Thread Example

function CustomThread() {
  return (
    <ThreadPrimitive.Root className="flex flex-col h-full">
      <ThreadPrimitive.Empty>
        <div className="flex-1 flex items-center justify-center">
          Start a conversation
        </div>
      </ThreadPrimitive.Empty>

      <ThreadPrimitive.Viewport className="flex-1 overflow-y-auto p-4">
        <ThreadPrimitive.Messages>
          {({ message }) =>
            message.role === "user" ? (
              <CustomUserMessage />
            ) : (
              <CustomAssistantMessage />
            )
          }
        </ThreadPrimitive.Messages>
      </ThreadPrimitive.Viewport>

      <ComposerPrimitive.Root className="border-t p-4 flex gap-2">
        <ComposerPrimitive.Input className="flex-1 rounded-lg border px-4 py-2" />
        <ComposerPrimitive.Send className="bg-blue-500 text-white px-4 py-2 rounded-lg">
          Send
        </ComposerPrimitive.Send>
      </ComposerPrimitive.Root>
    </ThreadPrimitive.Root>
  );
}

Conditional Rendering

Prefer AuiIf for new code. Primitive .If components still exist but are deprecated.

<AuiIf condition={({ message }) => message.role === "user"}>
  User only
</AuiIf>
<AuiIf condition={({ thread }) => thread.isRunning}>
  Generating...
</AuiIf>
<AuiIf condition={({ message }) => message.branchCount > 1}>
  Has edit history
</AuiIf>

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

<AuiIf condition={({ thread }) => thread.isEmpty}>No messages</AuiIf>

Message Parts (children render function)

As of 0.14, primitives that render lists (ThreadPrimitive.Messages, MessagePrimitive.Parts, ThreadPrimitive.Suggestions, ThreadListPrimitive.Items, ComposerPrimitive.Attachments) take a children render function instead of a components prop. The components prop still works but is deprecated.

MessagePrimitive.Parts is the canonical name (MessagePrimitive.Content is a deprecated alias).

<MessagePrimitive.Parts>
  {({ part }) => {
    switch (part.type) {
      case "text":
        return <p>{part.text}</p>;
      case "image":
        return <img src={part.image} alt="" />;
      case "reasoning":
        return (
          <details>
            <summary>Thinking</summary>
            {part.text}
          </details>
        );
      case "tool-call":
        return part.toolUI ?? <div>Tool: {part.toolName}</div>;
      default:
        return null; // registered tool/data UIs still render
    }
  }}
</MessagePrimitive.Parts>

Returning null from the render function lets registered tool and data UIs render via the registry; return <></> to explicitly render nothing.

Branch Picker

<AuiIf condition={({ message }) => message.branchCount > 1}>
  <BranchPickerPrimitive.Root className="flex items-center gap-1">
    <BranchPickerPrimitive.Previous>←</BranchPickerPrimitive.Previous>
    <span><BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count /></span>
    <BranchPickerPrimitive.Next>→</BranchPickerPrimitive.Next>
  </BranchPickerPrimitive.Root>
</AuiIf>

Common Gotchas

Primitives not rendering

• Wrap in AssistantRuntimeProvider
• Ensure parent primitive provides context

Styles not applying

• Primitives are unstyled by default
• Add className and style with your app's Tailwind/CSS system