assistant-ui Primitives

Always consult assistant-ui.com/llms.txt for 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

Import

tsx
1import {
2  ThreadPrimitive,
3  ComposerPrimitive,
4  MessagePrimitive,
5  ActionBarPrimitive,
6  BranchPickerPrimitive,
7  AttachmentPrimitive,
8  ThreadListPrimitive,
9  ThreadListItemPrimitive,
10} from "@assistant-ui/react";

Primitive Parts

Custom Thread Example

tsx
1function CustomThread() {
2  return (
3    <ThreadPrimitive.Root className="flex flex-col h-full">
4      <ThreadPrimitive.Empty>
5        <div className="flex-1 flex items-center justify-center">
6          Start a conversation
7        </div>
8      </ThreadPrimitive.Empty>
9
10      <ThreadPrimitive.Viewport className="flex-1 overflow-y-auto p-4">
11        <ThreadPrimitive.Messages components={{
12          UserMessage: CustomUserMessage,
13          AssistantMessage: CustomAssistantMessage,
14        }} />
15      </ThreadPrimitive.Viewport>
16
17      <ComposerPrimitive.Root className="border-t p-4 flex gap-2">
18        <ComposerPrimitive.Input className="flex-1 rounded-lg border px-4 py-2" />
19        <ComposerPrimitive.Send className="bg-blue-500 text-white px-4 py-2 rounded-lg">
20          Send
21        </ComposerPrimitive.Send>
22      </ComposerPrimitive.Root>
23    </ThreadPrimitive.Root>
24  );
25}

Conditional Rendering

tsx
1<MessagePrimitive.If user>User only</MessagePrimitive.If>
2<MessagePrimitive.If assistant>Assistant only</MessagePrimitive.If>
3<MessagePrimitive.If running>Generating...</MessagePrimitive.If>
4<MessagePrimitive.If hasBranches>Has edit history</MessagePrimitive.If>
5
6<ComposerPrimitive.If submitting>
7  <ComposerPrimitive.Cancel>Stop</ComposerPrimitive.Cancel>
8</ComposerPrimitive.If>
9
10<ThreadPrimitive.If empty>No messages</ThreadPrimitive.If>

Content Parts

tsx
1<MessagePrimitive.Content components={{
2  Text: ({ part }) => <p>{part.text}</p>,
3  Image: ({ part }) => <img src={part.image} alt="" />,
4  ToolCall: ({ part }) => <div>Tool: {part.toolName}</div>,
5  Reasoning: ({ part }) => <details><summary>Thinking</summary>{part.text}</details>,
6}} />

Branch Picker

tsx
1<MessagePrimitive.If hasBranches>
2  <BranchPickerPrimitive.Root className="flex items-center gap-1">
3    <BranchPickerPrimitive.Previous>←</BranchPickerPrimitive.Previous>
4    <span><BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count /></span>
5    <BranchPickerPrimitive.Next>→</BranchPickerPrimitive.Next>
6  </BranchPickerPrimitive.Root>
7</MessagePrimitive.If>

Common Gotchas

Primitives not rendering

• Wrap in AssistantRuntimeProvider
• Ensure parent primitive provides context

Styles not applying

• Primitives are unstyled by default
• Add className or use @assistant-ui/styles