- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
This release adds eleven AI element tutorials — Plan and Prompt Input — plus a monochrome token pass that fixes disabled states across buttons, input groups, OTP inputs, and native selects.
- Plan: Stream an agent plan with step status.
- Prompt Input: Composer with attachments, model, and effort pickers.
- Queue: Grouped todo list with pending and completed sections.
- Reasoning: Streaming thinking block with collapsible trace.
- Sources: Collapsible list of agent source citations.
- Stack Trace: Failed command with parsed stack frames.
- Subagent: Live trace of a delegated task with nested tool calls.
- Suggestion: Starter prompts above the composer.
- Task: Multi-step agent task with running, done, and error states.
- Test Results: Grouped trace of suites, tests, and failures.
- Tool: Tool call with running, done, error, denied, and approval states.
- Disabled state: Muted background replaces reduced opacity.
- Tokens:
--subtle-foregroundand higher contrast for--inputand--border.
Plan
Migrated Dialog and AlertDialog. The type checker passes.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import {
CircleCheckIcon,
CircleDotIcon,
CircleIcon,
RouteIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type ChatMessage = UIMessage<
unknown,
{
plan: {
title: string;
steps: { title: string; status: "done" | "running" | "pending" }[];
};
}
>;
type PlanPart = Extract<ChatMessage["parts"][number], { type: "data-plan" }>;
const STEPS = [
"Install @base-ui/react",
"Replace the Radix imports",
"Rename asChild to render",
"Run the type checker",
];
function planAt(current: number) {
return {
steps: STEPS.map((title, index) => ({
status:
index < current ? "done" : index === current ? "running" : "pending",
title,
})),
title: "Plan: migrate to Base UI",
} satisfies PlanPart["data"];
}
const chat = createChat<ChatMessage>()
.user("Migrate the dialog components to Base UI.")
.assistant(({ writer }) => {
STEPS.forEach((_, index) => {
writer
.data({ data: planAt(index), id: "plan", type: "data-plan" })
.sleep(1200);
});
writer.data({ data: planAt(STEPS.length), id: "plan", type: "data-plan" });
writer.text("Migrated Dialog and AlertDialog. The type checker passes.");
});
const transcript = chat.get();
const question = chat.get(0)[0];
const transport = chat.transport({ delayMs: 20 });
function PlanRow({
plan,
streaming,
}: {
plan: PlanPart["data"];
streaming: boolean;
}) {
const done = plan.steps.filter((step) => step.status === "done").length;
const running = streaming && done < plan.steps.length;
return (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status={running ? "running" : undefined}>
<TraceIcon>
<RouteIcon />
</TraceIcon>
<TraceTitle>{plan.title}</TraceTitle>
<TraceDescription>
{done} of {plan.steps.length} done
</TraceDescription>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{plan.steps.map((step) => (
<TraceLine
key={step.title}
status={
step.status === "pending"
? "pending"
: streaming && step.status === "running"
? "running"
: undefined
}
>
<TraceIcon>
{step.status === "done" ? (
<CircleCheckIcon />
) : step.status === "running" ? (
<CircleDotIcon />
) : (
<CircleIcon />
)}
</TraceIcon>
<TraceTitle>{step.title}</TraceTitle>
</TraceLine>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function PlanDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const plan = message.parts.find((part) => part.type === "data-plan");
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{plan && (
<Trace>
<PlanRow plan={plan.data} streaming={streaming} />
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && (
<Button
className="mt-auto self-start"
onClick={() => {
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Plan renders an agent plan as a collapsible list of steps. Each step is done, running, or pending. The header shows progress and the whole block collapses. It is a composition over Trace.
Installation
Install the primitives
$ bunx --bun frakment add trace message bubble button$ npx frakment add trace message bubble button$ pnpm dlx frakment add trace message bubble button$ yarn dlx frakment add trace message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<Trace>
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="running">
<TraceIcon><RouteIcon /></TraceIcon>
<TraceTitle>{"Plan: migrate to Base UI"}</TraceTitle>
<TraceDescription>{"1 of 4 done"}</TraceDescription>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>{/* steps */}</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>See the Plan docs for the full composition.
Prompt Input
"use client";
import {
ArrowUpIcon,
ChevronDownIcon,
FileTextIcon,
PlusIcon,
XIcon,
} from "lucide-react";
import * as React from "react";
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuGroup,
DropdownMenuLabel,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import {
InputGroup,
InputGroupAddon,
InputGroupButton,
InputGroupTextarea,
} from "@/components/ui/input-group";
interface AttachmentFile {
id: string;
name: string;
}
const providers = [
{
models: [
{ id: "gpt-5", name: "GPT-5" },
{ id: "gpt-5-mini", name: "GPT-5 mini" },
],
name: "OpenAI",
},
{
models: [
{ id: "claude-sonnet-4-5", name: "Claude Sonnet 4.5" },
{ id: "claude-haiku-4-5", name: "Claude Haiku 4.5" },
],
name: "Anthropic",
},
];
const models = providers.flatMap((provider) => provider.models);
const efforts = [
{ id: "low", name: "Low" },
{ id: "medium", name: "Medium" },
{ id: "high", name: "High" },
];
export function PromptInputDemo() {
const [text, setText] = React.useState("");
const [files, setFiles] = React.useState<AttachmentFile[]>([]);
const [model, setModel] = React.useState(models[0].id);
const [effort, setEffort] = React.useState(efforts[1].id);
const formRef = React.useRef<HTMLFormElement>(null);
const inputRef = React.useRef<HTMLInputElement>(null);
const currentModel = models.find((item) => item.id === model) ?? models[0];
const currentEffort =
efforts.find((item) => item.id === effort) ?? efforts[1];
const canSend = text.trim().length > 0;
function onSubmit(event: React.FormEvent<HTMLFormElement>) {
event.preventDefault();
if (!canSend) {
return;
}
setText("");
setFiles([]);
}
function onAttach(event: React.ChangeEvent<HTMLInputElement>) {
const selected = event.target.files;
if (!selected) {
return;
}
setFiles((current) => [
...current,
...Array.from(selected, (file) => ({
id: crypto.randomUUID(),
name: file.name,
})),
]);
event.target.value = "";
}
return (
<div className="mx-auto w-full max-w-lg py-6">
<form onSubmit={onSubmit} ref={formRef}>
<input
className="sr-only"
multiple
onChange={onAttach}
ref={inputRef}
tabIndex={-1}
type="file"
/>
<InputGroup>
{files.length > 0 && (
<InputGroupAddon align="block-start" className="flex-wrap">
{files.map((file) => (
<Attachment key={file.id} size="sm">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>{file.name}</AttachmentTitle>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction
aria-label={`Remove ${file.name}`}
onClick={() =>
setFiles((current) =>
current.filter((item) => item.id !== file.id)
)
}
>
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
))}
</InputGroupAddon>
)}
<InputGroupTextarea
className="p-3"
onChange={(event) => setText(event.target.value)}
onKeyDown={(event) => {
if (event.key === "Enter" && !event.shiftKey) {
event.preventDefault();
formRef.current?.requestSubmit();
}
}}
placeholder="Ask the agent to change your code..."
value={text}
/>
<InputGroupAddon align="block-end">
<InputGroupButton
aria-label="Attach files"
onClick={() => inputRef.current?.click()}
size="icon-sm"
variant="outline"
>
<PlusIcon />
</InputGroupButton>
<DropdownMenu>
<DropdownMenuTrigger
aria-label={`Model: ${currentModel.name}`}
as={InputGroupButton}
className="ml-auto"
size="sm"
variant="outline"
>
{currentModel.name}
<ChevronDownIcon />
</DropdownMenuTrigger>
<DropdownMenuContent align="start" className="w-48">
<DropdownMenuRadioGroup onValueChange={setModel} value={model}>
{providers.map((provider, index) => (
<React.Fragment key={provider.name}>
{index > 0 && <DropdownMenuSeparator />}
<DropdownMenuGroup>
<DropdownMenuLabel>{provider.name}</DropdownMenuLabel>
{provider.models.map((item) => (
<DropdownMenuRadioItem key={item.id} value={item.id}>
{item.name}
</DropdownMenuRadioItem>
))}
</DropdownMenuGroup>
</React.Fragment>
))}
</DropdownMenuRadioGroup>
</DropdownMenuContent>
</DropdownMenu>
<DropdownMenu>
<DropdownMenuTrigger
aria-label={`Effort: ${currentEffort.name}`}
as={InputGroupButton}
size="sm"
variant="outline"
>
<span className="text-muted-foreground">Effort</span>
{currentEffort.name}
<ChevronDownIcon />
</DropdownMenuTrigger>
<DropdownMenuContent align="start" className="w-36">
<DropdownMenuGroup>
<DropdownMenuLabel>Effort</DropdownMenuLabel>
<DropdownMenuRadioGroup
onValueChange={setEffort}
value={effort}
>
{efforts.map((item) => (
<DropdownMenuRadioItem key={item.id} value={item.id}>
{item.name}
</DropdownMenuRadioItem>
))}
</DropdownMenuRadioGroup>
</DropdownMenuGroup>
</DropdownMenuContent>
</DropdownMenu>
<InputGroupButton
aria-label="Send"
disabled={!canSend}
size="icon-sm"
type="submit"
variant="default"
>
<ArrowUpIcon />
</InputGroupButton>
</InputGroupAddon>
</InputGroup>
</form>
</div>
);
}Prompt Input is a composer for chat and agent surfaces. Attachment chips sit above a textarea, and a bottom bar holds the attach action, two pickers, and the send button. It is a composition over InputGroup, Attachment, Dropdown Menu, and Button.
Installation
Install the primitives
$ bunx --bun frakment add input-group attachment dropdown-menu button$ npx frakment add input-group attachment dropdown-menu button$ pnpm dlx frakment add input-group attachment dropdown-menu button$ yarn dlx frakment add input-group attachment dropdown-menu button
Use it in your app
import {
InputGroup,
InputGroupAddon,
InputGroupButton,
InputGroupTextarea,
} from "@/components/ui/input-group";Minimal usage
<InputGroup>
<InputGroupAddon align="block-start">{/* attachments */}</InputGroupAddon>
<InputGroupTextarea placeholder="Ask the agent..." />
<InputGroupAddon align="block-end">
<InputGroupButton aria-label="Attach files" size="icon-sm" variant="outline">
<PlusIcon />
</InputGroupButton>
<InputGroupButton type="submit" size="icon-sm" variant="default" aria-label="Send">
<ArrowUpIcon />
</InputGroupButton>
</InputGroupAddon>
</InputGroup>See the Prompt Input docs for the full composition.
Queue
Dark mode is in. The toggle is under Settings, Appearance.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import {
CircleCheckIcon,
CircleDotIcon,
CircleIcon,
ListChecksIcon,
ListTodoIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
writeTodos: {
input: {
todos: {
content: string;
status: "pending" | "in_progress" | "completed";
}[];
};
output: string;
};
}
>;
type Todo = Extract<
ChatMessage["parts"][number],
{ type: "tool-writeTodos"; state: "input-available" }
>["input"]["todos"][number];
const TODOS = [
"Add a dark variant to the theme tokens",
"Read the theme from a cookie",
"Add a toggle to the settings page",
"Check contrast on the charts",
];
function todosAt(current: number) {
return TODOS.map(
(content, index) =>
({
content,
status:
index < current
? "completed"
: index === current
? "in_progress"
: "pending",
}) satisfies Todo
);
}
const chat = createChat<ChatMessage>()
.user("Add dark mode to the settings page.")
.assistant(({ writer }) => {
TODOS.forEach((_, index) => {
writer
.tool("writeTodos", { input: { todos: todosAt(index) } })
.output("Updated the todo list.");
writer.sleep(1400);
});
writer
.tool("writeTodos", { input: { todos: todosAt(TODOS.length) } })
.output("Updated the todo list.");
writer.text("Dark mode is in. The toggle is under Settings, Appearance.");
});
const transcript = chat.get();
const question = chat.get(1)[0];
const transport = chat.transport({ delayMs: 20 });
function TodoLine({ todo, streaming }: { todo: Todo; streaming: boolean }) {
return (
<TraceLine
status={
streaming && todo.status === "in_progress" ? "running" : undefined
}
>
<TraceIcon>
{todo.status === "completed" ? (
<CircleCheckIcon />
) : todo.status === "in_progress" ? (
<CircleDotIcon />
) : (
<CircleIcon />
)}
</TraceIcon>
<TraceTitle>{todo.content}</TraceTitle>
</TraceLine>
);
}
function TodoQueue({
todos,
streaming,
}: {
todos: Todo[];
streaming: boolean;
}) {
const pending = todos.filter((todo) => todo.status !== "completed");
const completed = todos.filter((todo) => todo.status === "completed");
return (
<Trace>
{pending.length > 0 && (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<ListTodoIcon />
</TraceIcon>
<TraceTitle>{pending.length} to do</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{pending.map((todo) => (
<TodoLine
key={todo.content}
streaming={streaming}
todo={todo}
/>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
)}
{completed.length > 0 && (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<ListChecksIcon />
</TraceIcon>
<TraceTitle>{completed.length} completed</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{completed.map((todo) => (
<TodoLine
key={todo.content}
streaming={streaming}
todo={todo}
/>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
)}
</Trace>
);
}
export function QueueDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const todos = message.parts
.filter((part) => part.type === "tool-writeTodos")
.filter((part) => part.state !== "input-streaming")
.at(-1)?.input?.todos;
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{todos && <TodoQueue streaming={streaming} todos={todos} />}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Queue renders an agent todo list as two grouped trace sections — pending and completed. Each row carries a status glyph and the group headers show counts. It is a composition over Trace.
Installation
Install the primitives
$ bunx --bun frakment add trace message bubble button$ npx frakment add trace message bubble button$ pnpm dlx frakment add trace message bubble button$ yarn dlx frakment add trace message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<Trace>
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon><ListTodoIcon /></TraceIcon>
<TraceTitle>{"3 to do"}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>{/* pending todos */}</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>See the Queue docs for the full composition.
Reasoning
Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash, and the deploy should take under two minutes.
"use client";
import { useChat } from "@ai-sdk/react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
const chat = createChat()
.user("Why is the checkout deploy so slow?")
.assistant(({ writer }) => {
writer.reasoning(
"The deploy log has three phases. Install takes 38s and next build takes 52s, both normal for this repo.\n\nImage optimization takes 3m 50s. It reruns on every deploy because its cache key includes the commit hash, so the cache never hits.",
{ delayMs: 40 }
);
writer.sleep(400);
writer.text(
"Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash, and the deploy should take under two minutes."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function ReasoningRow({
text,
running,
defaultOpen,
}: {
text: string;
running: boolean;
defaultOpen?: boolean;
}) {
const [open, setOpen] = React.useState<boolean | undefined>(defaultOpen);
const line = (
<TraceLine status={running ? "running" : undefined}>
<TraceTitle>{running ? "Thinking" : "Thought for 5s"}</TraceTitle>
</TraceLine>
);
if (text.length === 0) {
return line;
}
return (
<TraceCollapsible onOpenChange={setOpen} open={open ?? running}>
<TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="text-muted-foreground whitespace-pre-wrap">
{text}
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function ReasoningDemo() {
const { messages, sendMessage, setMessages, status } = useChat({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const reasoning = message.parts.filter(
(part) => part.type === "reasoning"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{reasoning.length > 0 && (
<Trace>
{reasoning.map((part, index) => (
<ReasoningRow
defaultOpen={busy ? undefined : true}
key={index}
running={streaming && part.state === "streaming"}
text={part.text}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Reasoning renders an agent thinking block as a collapsible trace. The line shimmers while streaming, stays open until the run finishes, then collapses. It is a composition over Trace.
Installation
Install the primitives
$ bunx --bun frakment add trace message bubble button$ npx frakment add trace message bubble button$ pnpm dlx frakment add trace message bubble button$ yarn dlx frakment add trace message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<Trace>
<TraceCollapsible open={running} onOpenChange={setOpen}>
<TraceCollapsibleTrigger>
<TraceLine status={running ? "running" : undefined}>
<TraceTitle>{running ? "Thinking" : "Thought"}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="whitespace-pre-wrap">
{text}
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>See the Reasoning docs for the full composition.
Sources
Run pnpm create astro@latest and follow the prompts. It scaffolds the project and installs the dependencies.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import { ArrowUpRightIcon, GlobeIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
const chat = createChat()
.user("How do I start an Astro project with pnpm?")
.assistant(({ writer }) => {
writer.text(
"Run pnpm create astro@latest and follow the prompts. It scaffolds the project and installs the dependencies."
);
writer.sourceUrl({
title: "Install Astro | docs.astro.build",
url: "https://docs.astro.build/en/install-and-setup/",
});
writer.sourceUrl({
title: "create-astro | npmjs.com",
url: "https://www.npmjs.com/package/create-astro",
});
writer.sourceUrl({
title: "Install Astro | docs.astro.build",
url: "https://docs.astro.build/en/install-and-setup/",
});
writer.sourceUrl({
title: "pnpm create | pnpm.io",
url: "https://pnpm.io/cli/create",
});
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
type SourcePart = Extract<UIMessage["parts"][number], { type: "source-url" }>;
function Sources({ sources }: { sources: SourcePart[] }) {
return (
<Trace>
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<GlobeIcon />
</TraceIcon>
<TraceTitle>{`Used ${sources.length} sources`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{sources.map((source) => (
<a
className="decoration-muted-foreground block rounded-md underline-offset-4 hover:underline"
href={source.url}
key={source.url}
rel="noreferrer"
target="_blank"
>
<TraceLine>
<TraceTitle>
{source.title ?? new URL(source.url).hostname}
<span className="sr-only"> (opens in a new tab)</span>
</TraceTitle>
<TraceIcon>
<ArrowUpRightIcon />
</TraceIcon>
</TraceLine>
</a>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
);
}
export function SourcesDemo() {
const { messages, sendMessage, setMessages, status } = useChat({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const sources = message.parts
.filter((part) => part.type === "source-url")
.filter(
(part, index, all) =>
all.findIndex((other) => other.url === part.url) === index
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{text && <p>{text}</p>}
{sources.length > 0 && <Sources sources={sources} />}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Sources collects source-url parts from an assistant message and renders them as a collapsible trace list. Duplicates are removed and the header shows the count. It is a composition over Trace.
Installation
Install the primitives
$ bunx --bun frakment add trace message bubble button$ npx frakment add trace message bubble button$ pnpm dlx frakment add trace message bubble button$ yarn dlx frakment add trace message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<Trace>
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon><GlobeIcon /></TraceIcon>
<TraceTitle>{`Used ${sources.length} sources`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{sources.map((source) => (
<a key={source.url} href={source.url} target="_blank" rel="noreferrer" className="block">
<TraceLine>
<TraceTitle>{source.title ?? source.url}</TraceTitle>
<TraceIcon><ArrowUpRightIcon /></TraceIcon>
</TraceLine>
</a>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>See the Sources docs for the full composition.
Stack Trace
Database reset successful
The following migrations have been applied:
migrations/
└─ 20260912_init/
└─ 20260920_add_profiles/TypeError: Cannot read properties of undefined (reading 'email')
- at Module._compile (node:internal/modules/cjs/loader:1554:14)
- at Object.transformer (node_modules/tsx/dist/register.cjs:3:1104)
- at Module.load (node:internal/modules/cjs/loader:1289:32)
- at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
The migrations ran, but the seed failed in seedUsers. One fixture has no profile, so profile.email is undefined.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import { FileCodeIcon, LayersIcon, TerminalIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
runCommand: {
input: { command: string };
output: { stdout: string };
};
}
>;
type ToolPart = Extract<
ChatMessage["parts"][number],
{ type: "tool-runCommand" }
>;
const STACK = `TypeError: Cannot read properties of undefined (reading 'email')
at seedUsers (prisma/seed.ts:27:34)
at main (prisma/seed.ts:51:9)
at Module._compile (node:internal/modules/cjs/loader:1554:14)
at Object.transformer (node_modules/tsx/dist/register.cjs:3:1104)
at Module.load (node:internal/modules/cjs/loader:1289:32)
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)`;
const chat = createChat<ChatMessage>()
.user("Reset the database and seed it.")
.assistant(({ writer }) => {
writer
.tool("runCommand", {
input: { command: "pnpm prisma migrate reset --skip-seed" },
})
.sleep(900)
.output({
stdout: `Database reset successful
The following migrations have been applied:
migrations/
└─ 20260912_init/
└─ 20260920_add_profiles/`,
});
writer
.tool("runCommand", { input: { command: "pnpm prisma db seed" } })
.sleep(1200)
.error(STACK);
writer.text(
"The migrations ran, but the seed failed in seedUsers. One fixture has no profile, so profile.email is undefined."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function parseFrame(line: string) {
const match = line.match(/^at (.+) \((.+):(\d+):(\d+)\)$/);
return {
file: match?.[2],
internal: line.includes("node_modules") || line.includes("node:"),
line,
lineNumber: match?.[3],
name: match?.[1],
};
}
function StackTrace({ stack }: { stack: string }) {
const [error, ...lines] = stack.split("\n").map((line) => line.trim());
const frames = lines.map(parseFrame);
const appFrames = frames.filter((frame) => !frame.internal);
const internalFrames = frames.filter((frame) => frame.internal);
return (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>{`Failed: ${error}`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-col gap-2">
<p className="text-destructive font-mono text-xs">{error}</p>
<Trace>
{appFrames.map((frame) => (
<a
className="decoration-muted-foreground block underline-offset-4 hover:underline"
href={`#${frame.file}:${frame.lineNumber}`}
key={frame.line}
>
<TraceLine>
<TraceIcon>
<FileCodeIcon />
</TraceIcon>
<TraceTitle>
{frame.name} in {frame.file}:{frame.lineNumber}
</TraceTitle>
</TraceLine>
</a>
))}
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<LayersIcon />
</TraceIcon>
<TraceTitle>
{internalFrames.length} framework frames
</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<ol className="bg-muted flex flex-col gap-1 overflow-x-auto rounded-md p-3 font-mono text-xs">
{internalFrames.map((frame) => (
<li className="whitespace-nowrap" key={frame.line}>
{frame.line}
</li>
))}
</ol>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
function CommandRow({
part,
streaming,
}: {
part: ToolPart;
streaming: boolean;
}) {
const command = part.input?.command;
if (part.state === "output-error") {
return <StackTrace stack={part.errorText} />;
}
if (part.state === "output-available") {
return (
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>{`Ran ${command}`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{part.output.stdout}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
return (
<TraceLine status={streaming ? "running" : "error"}>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>
{streaming ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
export function StackTraceDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const tools = message.parts.filter(
(part) => part.type === "tool-runCommand"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{tools.length > 0 && (
<Trace>
{tools.map((part) => (
<CommandRow
key={part.toolCallId}
part={part}
streaming={streaming}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Stack Trace renders a failed command as a collapsible trace. App frames are links, framework frames collapse into a monospace list. It is a composition over Trace and Code Block.
Installation
Install the primitives
$ bunx --bun frakment add trace code-block message bubble button$ npx frakment add trace code-block message bubble button$ pnpm dlx frakment add trace code-block message bubble button$ yarn dlx frakment add trace code-block message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceIcon><TerminalIcon /></TraceIcon>
<TraceTitle>{`Failed: ${error}`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<p className="text-destructive font-mono text-xs">{error}</p>
<Trace>{/* frames */}</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>See the Stack Trace docs for the full composition.
Subagent
scripts/optimize-images.ts:14: const cacheKey = process.env.COMMIT_SHAconst cacheDir = ".next/cache/images"
const cacheKey = process.env.COMMIT_SHA
const cached = await restoreCache(cacheDir, cacheKey)1240The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again.
Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import {
CircleAlertIcon,
CircleCheckIcon,
LoaderCircleIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type SubagentMessage = UIMessage<
unknown,
UIDataTypes,
{
runCommand: {
input: { command: string };
output: { stdout: string };
};
}
>;
type SubagentPart = SubagentMessage["parts"][number];
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
researchAgent: {
input: { task: string };
output: SubagentMessage;
};
}
>;
type Part = ChatMessage["parts"][number];
const steps = [
{
command: "grep -rn cacheKey scripts",
stdout:
"scripts/optimize-images.ts:14: const cacheKey = process.env.COMMIT_SHA",
},
{
command: "sed -n 13,15p scripts/optimize-images.ts",
stdout:
'const cacheDir = ".next/cache/images"\nconst cacheKey = process.env.COMMIT_SHA\nconst cached = await restoreCache(cacheDir, cacheKey)',
},
{
command: "ls public/images | wc -l",
stdout: "1240",
},
];
function getSubagentMessage(done: number, report?: string): SubagentMessage {
const parts = steps.slice(0, done).map(
(step, index): SubagentPart => ({
input: { command: step.command },
output: { stdout: step.stdout },
state: "output-available",
toolCallId: `step-${index}`,
type: "tool-runCommand",
})
);
if (done < steps.length) {
parts.push({
input: { command: steps[done].command },
state: "input-available",
toolCallId: `step-${done}`,
type: "tool-runCommand",
});
}
if (report) {
parts.push({ text: report, type: "text" });
}
return { id: "research-agent", parts, role: "assistant" };
}
const chat = createChat<ChatMessage>()
.user("Why does image optimization rerun on every deploy?")
.assistant(({ writer }) => {
const subagent = writer.tool("researchAgent", {
input: {
task: "Find out why image optimization reruns on every deploy.",
},
});
writer.sleep(600);
steps.forEach((_, index) => {
subagent.output(getSubagentMessage(index), { preliminary: true });
writer.sleep(1000);
});
subagent.output(
getSubagentMessage(
steps.length,
"The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again."
)
);
writer.sleep(400);
writer.text(
"Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function StepRow({
part,
running,
}: {
part: Extract<SubagentPart, { type: "tool-runCommand" }>;
running: boolean;
}) {
const command = part.input?.command;
if (part.state === "output-available") {
return (
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>{`Ran ${command}`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{part.output.stdout}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
return (
<TraceLine status={running ? "running" : "error"}>
<TraceIcon>
{running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleAlertIcon />
)}
</TraceIcon>
<TraceTitle>
{running ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
function SubagentRow({
part,
streaming,
}: {
part: Extract<Part, { type: "tool-researchAgent" }>;
streaming: boolean;
}) {
const done = part.state === "output-available" && !part.preliminary;
const running = !done && part.state !== "output-error" && streaming;
const parts = part.state === "output-available" ? part.output.parts : [];
const report = parts
.map((agentPart) => (agentPart.type === "text" ? agentPart.text : ""))
.join("");
const line = (
<TraceLine status={done ? undefined : running ? "running" : "error"}>
<TraceIcon>
{done ? (
<CircleCheckIcon />
) : running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleAlertIcon />
)}
</TraceIcon>
<TraceTitle>
{done ? "Ran" : running ? "Running" : "Failed to run"} the research
subagent
</TraceTitle>
</TraceLine>
);
if (parts.length === 0) {
return line;
}
return (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-col gap-3" keepMounted>
<Trace>
{parts.map((agentPart) =>
agentPart.type === "tool-runCommand" ? (
<StepRow
key={agentPart.toolCallId}
part={agentPart}
running={running}
/>
) : null
)}
</Trace>
{report && <p>{report}</p>}
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function SubagentDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const agents = message.parts.filter(
(part) => part.type === "tool-researchAgent"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{agents.length > 0 && (
<Trace>
{agents.map((part) => (
<SubagentRow
key={part.toolCallId}
part={part}
streaming={streaming}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Subagent renders a delegated task as a live trace. The subagent streams its own tool calls as partial output and lands the final report at the bottom. It is a composition over Trace and Code Block.
Installation
Install the primitives
$ bunx --bun frakment add trace code-block message bubble button$ npx frakment add trace code-block message bubble button$ pnpm dlx frakment add trace code-block message bubble button$ yarn dlx frakment add trace code-block message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
const subagent = writer.tool("researchAgent", { input: { task } })
steps.forEach((_, index) => {
subagent.output(getSubagentMessage(index), { preliminary: true })
writer.sleep(1000)
})
subagent.output(getSubagentMessage(steps.length, report))See the Subagent docs for the full composition.
Suggestion
"use client";
import { ArrowUpIcon, PlusIcon } from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
InputGroup,
InputGroupAddon,
InputGroupButton,
InputGroupTextarea,
} from "@/components/ui/input-group";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
const suggestions = [
"Add a dark mode toggle",
"Fix the failing build",
"Write tests for the form",
"Upgrade to Next.js 16",
"Add a loading state",
"Find unused dependencies",
];
const replies: Record<string, string> = {
"Add a dark mode toggle":
"Added a ModeToggle to the site header. It calls setTheme from next-themes.",
"Add a loading state":
"Added a loading.tsx to the dashboard route. It shows skeletons while the data loads.",
"Find unused dependencies":
"Three packages are not imported anywhere: lodash, moment and classnames. Should I remove them?",
"Fix the failing build":
"The build failed on a missing import in app/page.tsx. I added it and the build passes.",
"Upgrade to Next.js 16":
"Ran the codemod and bumped next to 16. Two routes needed async params, so I updated them.",
"Write tests for the form":
"Added four tests in signup-form.test.tsx. They cover the empty, invalid and valid states.",
};
export function SuggestionDemo() {
const [text, setText] = React.useState("");
const [turn, setTurn] = React.useState<{
prompt: string;
reply: string;
} | null>(null);
const formRef = React.useRef<HTMLFormElement>(null);
const canSend = text.trim().length > 0;
function send(prompt: string) {
setTurn({
prompt,
reply:
replies[prompt] ?? "This demo only knows the suggestions. Pick one.",
});
setText("");
}
function onSubmit(event: React.FormEvent<HTMLFormElement>) {
event.preventDefault();
if (!canSend) {
return;
}
send(text.trim());
}
return (
<div className="mx-auto flex w-full max-w-lg flex-col gap-6 py-6 text-sm">
{turn && (
<div className="flex flex-col gap-4">
<Message align="end">
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{turn.prompt}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
<Message>
<MessageContent>
<p>{turn.reply}</p>
</MessageContent>
</Message>
</div>
)}
<div className="flex flex-col gap-2">
<div className="scroll-fade-x no-scrollbar flex gap-2 overflow-x-auto overscroll-x-contain">
{suggestions.map((suggestion) => (
<Button
className="shrink-0 rounded-full"
key={suggestion}
onClick={() => send(suggestion)}
size="sm"
variant="outline"
>
{suggestion}
</Button>
))}
</div>
<form onSubmit={onSubmit} ref={formRef}>
<InputGroup>
<InputGroupTextarea
className="p-3"
onChange={(event) => setText(event.target.value)}
onKeyDown={(event) => {
if (event.key === "Enter" && !event.shiftKey) {
event.preventDefault();
formRef.current?.requestSubmit();
}
}}
placeholder="Ask the agent to change your code..."
value={text}
/>
<InputGroupAddon align="block-end">
<InputGroupButton
aria-label="Attach files"
size="icon-sm"
variant="outline"
>
<PlusIcon />
</InputGroupButton>
<InputGroupButton
aria-label="Send"
className="ml-auto"
disabled={!canSend}
size="icon-sm"
type="submit"
variant="default"
>
<ArrowUpIcon />
</InputGroupButton>
</InputGroupAddon>
</InputGroup>
</form>
</div>
</div>
);
}Suggestion renders a horizontal row of starter prompts above the composer. Clicking one sends it immediately. The row scrolls horizontally and fades its edges.
Installation
Install the primitives
$ bunx --bun frakment add input-group bubble message button$ npx frakment add input-group bubble message button$ pnpm dlx frakment add input-group bubble message button$ yarn dlx frakment add input-group bubble message button
Use it in your app
import { Button } from "@/components/ui/button";Minimal usage
<div className="scroll-fade-x no-scrollbar flex gap-2 overflow-x-auto">
{suggestions.map((suggestion) => (
<Button key={suggestion} variant="outline" size="sm" onClick={() => send(suggestion)}>
{suggestion}
</Button>
))}
</div>See the Suggestion docs for the full composition.
Task
Added Open Graph defaults to app/layout.tsx and a title, description and image for the home page in app/page.tsx.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import {
CircleAlertIcon,
CircleCheckIcon,
LoaderCircleIcon,
} from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type ChatMessage = UIMessage<
unknown,
{
task: {
title: string;
steps: { title: string; status: "done" | "running" | "error" }[];
};
}
>;
type TaskPart = Extract<ChatMessage["parts"][number], { type: "data-task" }>;
type Status = "running" | "error" | undefined;
const TASKS = [
{
id: "find",
steps: [
["Searching for generateMetadata", "Searched for generateMetadata"],
["Reading app/layout.tsx", "Read app/layout.tsx"],
["Reading app/page.tsx", "Read app/page.tsx"],
],
title: ["Finding the project files", "Found the project files"],
},
{
id: "update",
steps: [
["Editing app/layout.tsx", "Edited app/layout.tsx"],
["Editing app/page.tsx", "Edited app/page.tsx"],
],
title: ["Updating the page metadata", "Updated the page metadata"],
},
];
function taskAt(task: (typeof TASKS)[number], done: number) {
return {
steps: task.steps.slice(0, done + 1).map(([running, finished], index) => ({
status: index < done ? "done" : "running",
title: index < done ? finished : running,
})),
title: task.title[done < task.steps.length ? 0 : 1],
} satisfies TaskPart["data"];
}
const chat = createChat<ChatMessage>()
.user("Add Open Graph metadata to the home page.")
.assistant(({ writer }) => {
TASKS.forEach((task) => {
for (let done = 0; done <= task.steps.length; done++) {
writer
.data({ data: taskAt(task, done), id: task.id, type: "data-task" })
.sleep(900);
}
});
writer.text(
"Added Open Graph defaults to app/layout.tsx and a title, description and image for the home page in app/page.tsx."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function getStepStatus(
status: TaskPart["data"]["steps"][number]["status"],
streaming: boolean
): Status {
if (status === "done") {
return undefined;
}
return status === "running" && streaming ? "running" : "error";
}
function StatusIcon({ status }: { status: Status }) {
if (status === "running") {
return <LoaderCircleIcon className="animate-spin" />;
}
return status === "error" ? <CircleAlertIcon /> : <CircleCheckIcon />;
}
function TaskRow({
task,
streaming,
}: {
task: TaskPart["data"];
streaming: boolean;
}) {
const [open, setOpen] = React.useState<boolean>();
const steps = task.steps.map((step) => ({
status: getStepStatus(step.status, streaming),
title: step.title,
}));
const status = steps.some((step) => step.status === "error")
? "error"
: steps.some((step) => step.status === "running")
? "running"
: undefined;
return (
<TraceCollapsible
onOpenChange={setOpen}
open={open ?? status === "running"}
>
<TraceCollapsibleTrigger>
<TraceLine status={status}>
<TraceIcon>
<StatusIcon status={status} />
</TraceIcon>
<TraceTitle>{task.title}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
{steps.map((step) => (
<TraceLine key={step.title} status={step.status}>
<TraceTitle>{step.title}</TraceTitle>
</TraceLine>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function TaskDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const tasks = message.parts.filter((part) => part.type === "data-task");
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{tasks.length > 0 && (
<Trace>
{tasks.map((part) => (
<TaskRow
key={part.id}
streaming={streaming}
task={part.data}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Task renders a multi-step agent operation as a collapsible trace. Each step updates in place as the task advances.
Installation
Install the primitives
$ bunx --bun frakment add trace message bubble button$ npx frakment add trace message bubble button$ pnpm dlx frakment add trace message bubble button$ yarn dlx frakment add trace message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status={status}>
<TraceIcon><StatusIcon status={status} /></TraceIcon>
<TraceTitle>{task.title}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>{/* steps */}</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>See the Task docs for the full composition.
Test Results
Expected 2 charge attempts, received 1
at Object.<anonymous> (src/payment.test.ts:58:22)One test failed. The payment client does not retry a declined card, so the second charge attempt never happens.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import {
CheckIcon,
CircleDashedIcon,
FileCodeIcon,
FlaskConicalIcon,
XIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
interface Test {
error?: string;
name: string;
status: "passed" | "failed" | "skipped";
}
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
runTests: {
input: { command: string };
output: { suites: { name: string; tests: Test[] }[] };
};
}
>;
type ToolPart = Extract<
ChatMessage["parts"][number],
{ type: "tool-runTests" }
>;
const chat = createChat<ChatMessage>()
.user("Run the checkout tests.")
.assistant(({ writer }) => {
writer
.tool("runTests", { input: { command: "pnpm test checkout" } })
.sleep(1500)
.output({
suites: [
{
name: "cart.test.ts",
tests: [
{ name: "adds an item", status: "passed" },
{ name: "removes an item", status: "passed" },
{ name: "applies a discount code", status: "passed" },
],
},
{
name: "payment.test.ts",
tests: [
{ name: "charges the saved card", status: "passed" },
{
error: `Expected 2 charge attempts, received 1
at Object.<anonymous> (src/payment.test.ts:58:22)`,
name: "retries a declined card",
status: "failed",
},
],
},
],
});
writer.text(
"One test failed. The payment client does not retry a declined card, so the second charge attempt never happens."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function countTests(tests: Test[]) {
return {
failed: tests.filter((test) => test.status === "failed").length,
skipped: tests.filter((test) => test.status === "skipped").length,
total: tests.length,
};
}
function formatCounts({
total,
failed,
skipped,
}: ReturnType<typeof countTests>) {
return [
`${total} tests`,
failed > 0 && `${failed} failed`,
skipped > 0 && `${skipped} skipped`,
]
.filter(Boolean)
.join(", ");
}
function TestRow({ test }: { test: Test }) {
if (test.status === "failed") {
return (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceIcon>
<XIcon />
</TraceIcon>
<TraceTitle>{test.name}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{test.error}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
return (
<TraceLine>
<TraceIcon>
{test.status === "skipped" ? <CircleDashedIcon /> : <CheckIcon />}
</TraceIcon>
<TraceTitle>
{test.status === "skipped" ? `Skipped ${test.name}` : test.name}
</TraceTitle>
</TraceLine>
);
}
function TestResultsRow({
part,
streaming,
}: {
part: ToolPart;
streaming: boolean;
}) {
const command = part.input?.command;
if (part.state !== "output-available") {
const running = streaming && part.state !== "output-error";
return (
<TraceLine status={running ? "running" : "error"}>
<TraceIcon>
<FlaskConicalIcon />
</TraceIcon>
<TraceTitle>
{running ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
const { suites } = part.output;
const summary = countTests(suites.flatMap((suite) => suite.tests));
return (
<TraceCollapsible defaultOpen={summary.failed > 0}>
<TraceCollapsibleTrigger>
<TraceLine status={summary.failed > 0 ? "error" : undefined}>
<TraceIcon>
<FlaskConicalIcon />
</TraceIcon>
<TraceTitle>Ran {formatCounts(summary)}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
{suites.map((suite) => {
const counts = countTests(suite.tests);
return (
<TraceCollapsible
defaultOpen={counts.failed > 0}
key={suite.name}
>
<TraceCollapsibleTrigger>
<TraceLine status={counts.failed > 0 ? "error" : undefined}>
<TraceIcon>
<FileCodeIcon />
</TraceIcon>
<TraceTitle>
{suite.name}, {formatCounts(counts)}
</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
{suite.tests.map((test) => (
<TestRow key={test.name} test={test} />
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
);
})}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function TestResultsDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const tools = message.parts.filter(
(part) => part.type === "tool-runTests"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{tools.length > 0 && (
<Trace>
{tools.map((part) => (
<TestResultsRow
key={part.toolCallId}
part={part}
streaming={streaming}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Test Results renders a test run as a nested trace. The header shows counts, each suite collapses into its tests, and failures expand into the assertion output.
Installation
Install the primitives
$ bunx --bun frakment add trace code-block message bubble button$ npx frakment add trace code-block message bubble button$ pnpm dlx frakment add trace code-block message bubble button$ yarn dlx frakment add trace code-block message bubble button
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status={summary.failed > 0 ? "error" : undefined}>
<TraceIcon><FlaskConicalIcon /></TraceIcon>
<TraceTitle>Ran {formatCounts(summary)}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>{/* suites */}</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>See the Test Results docs for the full composition.
Tool
v24.18.011.6.2command not found: pnpmNode 24 and npm 11 are installed. pnpm is not.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import { TerminalIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
runCommand: {
input: { command: string };
output: { stdout: string };
};
}
>;
type ToolPart = Extract<
ChatMessage["parts"][number],
{ type: "tool-runCommand" }
>;
const chat = createChat<ChatMessage>()
.user("Which package managers are installed?")
.assistant(({ writer }) => {
writer
.tool("runCommand", { input: { command: "node --version" } })
.sleep(900)
.output({ stdout: "v24.18.0" });
writer
.tool("runCommand", { input: { command: "npm --version" } })
.sleep(900)
.output({ stdout: "11.6.2" });
writer
.tool("runCommand", { input: { command: "pnpm --version" } })
.sleep(900)
.error("command not found: pnpm");
writer.text("Node 24 and npm 11 are installed. pnpm is not.");
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function ToolRow({
part,
streaming,
defaultOpen,
}: {
part: ToolPart;
streaming: boolean;
defaultOpen?: boolean;
}) {
const command = part.input?.command;
if (part.state === "output-available" || part.state === "output-error") {
const failed = part.state === "output-error";
return (
<TraceCollapsible defaultOpen={defaultOpen}>
<TraceCollapsibleTrigger>
<TraceLine status={failed ? "error" : undefined}>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>
{failed ? "Failed to run" : "Ran"} {command}
</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{failed ? part.errorText : part.output.stdout}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
return (
<TraceLine status={streaming ? "running" : "error"}>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>
{streaming ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
export function ToolDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const tools = message.parts.filter(
(part) => part.type === "tool-runCommand"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{tools.length > 0 && (
<Trace>
{tools.map((part) => (
<ToolRow
defaultOpen={
busy ? undefined : part.state === "output-error"
}
key={part.toolCallId}
part={part}
streaming={streaming}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Tool renders a tool call as a trace row with running, done, error, denied, and approval states. Failing calls auto-expand their output.
Installation
Install the primitives
$ bunx --bun frakment add trace code-block message bubble button item$ npx frakment add trace code-block message bubble button item$ pnpm dlx frakment add trace code-block message bubble button item$ yarn dlx frakment add trace code-block message bubble button item
Use it in your app
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";Minimal usage
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status={failed ? "error" : undefined}>
<TraceIcon><TerminalIcon /></TraceIcon>
<TraceTitle>{failed ? "Failed to run" : "Ran"} {command}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock><CodeBlockContent wrap>{output}</CodeBlockContent></CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>See the Tool docs for the full composition.
Engine packages now on npm
@frakment/ai and @frakment/react are now published npm packages. AI and message scroller engines install with npm install, matching the shadcn pattern where logic lives in a package and styling lives in the registry.
$ bun add @frakment/ai @frakment/react$ npm install @frakment/ai @frakment/react$ pnpm add @frakment/ai @frakment/react$ yarn add @frakment/ai @frakment/react
message-scroller now depends on @frakment/react, and message-animated depends on @frakment/ai. Running npx frakment add message-scroller or message-animated installs the engine package automatically.
Migration
If you previously installed the ai registry item, delete the lib/ai/ folder — it is no longer used. Import the engine from @frakment/ai instead:
- import { createChat } from "@/lib/ai"
+ import { createChat } from "@frakment/ai"See the AI engine docs and React engine docs for the full API.
Disabled state
Disabled buttons now use a solid muted background instead of reduced opacity. Icons and labels stay readable while the control reads as inactive.
InputGroup, InputOTP, and NativeSelect no longer fade their entire container when a single child is disabled.
See the Button docs and Input Group docs for the updated variants.
Tokens
--subtle-foreground is available for interactive values inside muted surfaces, sitting between --foreground and --muted-foreground. --input and --border are lifted in both light and dark mode so form borders read against the surface. --sidebar-primary is monochrome in both modes. <body> now applies bg-background by default.
See the Theming guide for the full token reference.
On This Page
PlanInstallationMinimal usagePrompt InputInstallationMinimal usageQueueInstallationMinimal usageReasoningInstallationMinimal usageSourcesInstallationMinimal usageStack TraceInstallationMinimal usageSubagentInstallationMinimal usageSuggestionInstallationMinimal usageTaskInstallationMinimal usageTest ResultsInstallationMinimal usageToolInstallationMinimal usageEngine packages now on npmMigrationDisabled stateTokens