- 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
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, the group headers show counts, and both groups collapse independently.
Queue is a composition, not a primitive. It composes Trace lines inside collapsibles and drives streaming status 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 { 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>
);
}Update the import paths to match your project setup.
Usage
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import {
CircleCheckIcon,
CircleDotIcon,
CircleIcon,
ListChecksIcon,
ListTodoIcon,
} from "lucide-react";<Trace>
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<ListTodoIcon />
</TraceIcon>
<TraceTitle>3 to do</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
<TraceLine status="running">
<TraceIcon>
<CircleDotIcon />
</TraceIcon>
<TraceTitle>Add a toggle to the settings page</TraceTitle>
</TraceLine>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>Anatomy
<Trace>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon />
<TraceTitle />
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
<TraceLine>
<TraceIcon />
<TraceTitle />
</TraceLine>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>- Trace — outer wrapper, flex column
- TraceCollapsible — one per group (pending, completed)
- TraceCollapsibleTrigger — header row with group icon and count
- TraceCollapsibleContent — the todo list rows
- TraceLine — individual todo row, accepts
status - TraceTitle — todo content
Todo status
Each todo carries one of three states. The glyph and shimmer reflect the current one.
| Status | Icon | Effect |
|---|---|---|
pending | circle | muted, no shimmer |
in_progress | circle-dot | running, shimmer on title |
completed | circle-check | muted, no shimmer |
Grouped queue
Split the todo list by status. Pending rows and completed rows collapse independently so a long run stays scannable. The header count updates as items move between groups.
Descriptions
Each todo may carry a description that expands on demand. Wrap the todo row in a nested TraceCollapsible and pass the description as its content.
import {
CircleCheckIcon,
CircleIcon,
ListChecksIcon,
ListTodoIcon,
} from "lucide-react";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
const todos: { title: string; description?: string; done: boolean }[] = [
{
description: "Cover the renamed props and the new data attributes.",
done: true,
title: "Write the migration guide",
},
{ done: true, title: "Add a changeset" },
{
description: "It is clipped by overflow-hidden on the field.",
done: false,
title: "Fix the focus ring on the select trigger",
},
{ done: false, title: "Update the registry snapshots" },
{
description: "Typing, clearing and keyboard selection.",
done: false,
title: "Add tests for the combobox",
},
];
function TodoRow({ todo }: { todo: (typeof todos)[number] }) {
const line = (
<TraceLine>
<TraceIcon>{todo.done ? <CircleCheckIcon /> : <CircleIcon />}</TraceIcon>
<TraceTitle>{todo.title}</TraceTitle>
</TraceLine>
);
if (!todo.description) {
return line;
}
return (
<TraceCollapsible>
<TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
<TraceCollapsibleContent>{todo.description}</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function QueueDescriptions() {
const pending = todos.filter((todo) => !todo.done);
const completed = todos.filter((todo) => todo.done);
return (
<Trace className="max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<ListTodoIcon />
</TraceIcon>
<TraceTitle>{pending.length} to do</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
{pending.map((todo) => (
<TodoRow key={todo.title} todo={todo} />
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<ListChecksIcon />
</TraceIcon>
<TraceTitle>{completed.length} completed</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
{completed.map((todo) => (
<TodoRow key={todo.title} todo={todo} />
))}
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
);
}Streaming
The demo streams writeTodos tool calls through a chat transport. Each tick replaces the todo list with a new snapshot where one more item moves to completed and the next becomes in_progress. The header counts and icons update without a full re-render of the chat.
Accessibility
- Use
TraceTitleas the accessible name. Write it as the todo content, not a status word. - Status is conveyed by icon glyph and color. Do not rely on color alone.
- Each collapsible trigger is keyboard-focusable and toggles with Enter or Space.
prefers-reduced-motiondisables shimmer and collapse animation.
Best Practices
- Group by status, not by index. Pending and completed read as two lists, not one list with gaps.
- Keep todo titles short. One sentence, imperative mood — "Add a toggle", not "Toggle should be added".
- Let the counts speak. The header shows how many are left. Do not repeat that in the intro.
- Collapse the completed group by default for long runs. Users scan the pending rows first.