- 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
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. The header shows the task title and a status icon. The body lists each step with its own status. Every step updates in place as the task advances.
Task is a composition, not a primitive. It composes Trace and drives its own step state through a chat transport.
Installation
$ 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
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
Copy the demo into your project:
"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>
);
}Update the import paths to match your project setup.
Usage
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";<TraceCollapsible open={open} onOpenChange={setOpen}>
<TraceCollapsibleTrigger>
<TraceLine status={status}>
<TraceIcon>
<StatusIcon status={status} />
</TraceIcon>
<TraceTitle>{task.title}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
{steps.map((step) => (
<TraceLine key={step.title} status={step.status}>
<TraceTitle>{step.title}</TraceTitle>
</TraceLine>
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>Anatomy
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon />
<TraceTitle />
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
<TraceLine>
<TraceTitle />
</TraceLine>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>- TraceCollapsible — the task run, one per task
- TraceCollapsibleTrigger — header with status icon and task title
- TraceCollapsibleContent — nested
Tracewith one step row per action - TraceLine — a single step,
statusdrives the color
Step status
Each step is done, running, or error. The parent task status derives from its steps: any error makes the task error, any running makes it running, otherwise it is done.
const status = steps.some((step) => step.status === "error")
? "error"
: steps.some((step) => step.status === "running")
? "running"
: undefinedControlled open
The demo keeps the task open while it is running and collapses it once it finishes. Pass open and onOpenChange when the parent wants to control visibility, or use defaultOpen for a fixed block that starts expanded.
Accessibility
- The status icon is decorative. The
TraceTitlecarries the state. - While running,
aria-live="polite"on the content region announces step changes. - Each step row is text, not an icon. Color is a secondary signal.
prefers-reduced-motiondisables the spinner and collapse animation.
Best Practices
- One task per collapsible. Do not merge unrelated work into one block.
- Keep step titles verb-first. "Reading app/layout.tsx", not "app/layout.tsx".
- Open while running, collapse when done. A live task signals progress.
- Pair with a plain-text summary. The task is evidence, not the answer.