Assistant UI Primitives
Customize chat UI components using composable ThreadPrimitive, ComposerPrimitive, and MessagePrimitive.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/assistant-ui-primitives-compozy/— the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
.agents/skills/assistant-ui/assistant-ui-primitives, fromgithub.com/compozy/compozy(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/assistant-ui-primitives-compozy/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Guide for assistant-ui UI primitives - ThreadPrimitive, ComposerPrimitive, MessagePrimitive. Use when customizing chat UI components.
What this skill does
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
import {
AuiIf,
ThreadPrimitive,
ComposerPrimitive,
MessagePrimitive,
ActionBarPrimitive,
BranchPickerPrimitive,
AttachmentPrimitive,
ThreadListPrimitive,
ThreadListItemPrimitive,
} from "@assistant-ui/react";
Primitive Parts
| Primitive | Key Parts |
|---|---|
ThreadPrimitive | .Root, .Viewport, .Messages, .Empty, .ScrollToBottom |
ComposerPrimitive | .Root, .Input, .Send, .Cancel, .Attachments |
MessagePrimitive | .Root, .Parts/.Content, .If, .Error |
ActionBarPrimitive | .Copy, .Edit, .Reload, .Speak, .FeedbackPositive, .FeedbackNegative, .ExportMarkdown |
BranchPickerPrimitive | .Previous, .Next, .Number, .Count |
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 components={{
UserMessage: CustomUserMessage,
AssistantMessage: CustomAssistantMessage,
}} />
</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>
Content Parts
<MessagePrimitive.Content components={{
Text: ({ part }) => <p>{part.text}</p>,
Image: ({ part }) => <img src={part.image} alt="" />,
ToolCall: ({ part }) => <div>Tool: {part.toolName}</div>,
Reasoning: ({ part }) => <details><summary>Thinking</summary>{part.text}</details>,
}} />
Branch Picker
<MessagePrimitive.If hasBranches>
<BranchPickerPrimitive.Root className="flex items-center gap-1">
<BranchPickerPrimitive.Previous>←</BranchPickerPrimitive.Previous>
<span><BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count /></span>
<BranchPickerPrimitive.Next>→</BranchPickerPrimitive.Next>
</BranchPickerPrimitive.Root>
</MessagePrimitive.If>
Common Gotchas
Primitives not rendering
- Wrap in
AssistantRuntimeProvider - Ensure parent primitive provides context
Styles not applying
- Primitives are unstyled by default
- Add
classNameand style with your app's Tailwind/CSS system
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
UI/UX Pro Max
anthropics
Build production-grade web components and interfaces with distinctive, polished design.
Artifact Theme Toolkit
anthropics
Apply professional color and font themes to slides, docs, and web pages.
Multi-Component Web Artifacts
anthropics
Build complex React artifacts with Tailwind CSS and shadcn/ui components.