- 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
Tool
Render a tool call as a trace row with running, done, error, denied, and approval states.
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. The row shows the command, a status glyph, and the output in a code block. Failing calls expand by default. Approvals render as a prompt outside the trace.
Tool is a composition, not a primitive. It composes Trace and Code Block.
Installation
$ 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
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
Copy the demo into your project:
"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>
);
}Update the import paths to match your project setup.
Usage
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import { TerminalIcon } from "lucide-react";Anatomy
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon />
<TraceTitle />
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock>
<CodeBlockContent />
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>- TraceCollapsible — one per call, header has the command and status
- TraceLine — a single row,
statusdrives icon and color - Code Block — the tool output (stdout or error text)
States
A call can be running, done, error, denied, or pending approval. Each maps to a different row.
M app/api/chat/route.ts
M components/chat.tsxCommand timed out after 120 seconds.import { TerminalIcon } from "lucide-react";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function ToolStates() {
return (
<Trace className="max-w-sm">
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Ran git status --short</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{` M app/api/chat/route.ts
M components/chat.tsx`}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine status="error">
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Failed to run pnpm dev</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
Command timed out after 120 seconds.
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
<TraceLine>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Denied rm -rf dist</TraceTitle>
</TraceLine>
<TraceLine status="running">
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>Running pnpm test</TraceTitle>
</TraceLine>
</Trace>
);
}Output in a sheet
For file reads or long outputs, open the result in a Sheet instead of expanding inline. The row becomes a trigger and the sheet shows the full content.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import { ChevronRightIcon, FileTextIcon } 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 {
Sheet,
SheetContent,
SheetDescription,
SheetHeader,
SheetTitle,
SheetTrigger,
} from "@/components/ui/sheet";
import { Trace, TraceIcon, TraceLine, TraceTitle } from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
readFile: {
input: { path: string };
output: { path: string; content: string };
};
}
>;
const PACKAGE_JSON = `{
"name": "acme-chat",
"private": true,
"dependencies": {
"@ai-sdk/react": "^4.0.0",
"ai": "^7.0.0",
"next": "^16.3.0"
}
}`;
const chat = createChat<ChatMessage>()
.user("Which AI SDK version does this app use?")
.assistant(({ writer }) => {
writer
.tool("readFile", { input: { path: "package.json" } })
.sleep(900)
.output({ content: PACKAGE_JSON, path: "package.json" });
writer.text("It uses ai 7 with @ai-sdk/react 4.");
});
const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });
export function ToolSheet() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: initialMessages,
transport,
});
const nextMessage = chat.next(messages);
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);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{message.parts.map((part, index) => {
if (part.type === "text") {
return <p key={index}>{part.text}</p>;
}
if (part.type !== "tool-readFile") {
return null;
}
if (part.state !== "output-available") {
const running =
streaming &&
(part.state === "input-streaming" ||
part.state === "input-available");
return (
<Trace key={part.toolCallId}>
<TraceLine status={running ? "running" : "error"}>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>
{running ? "Reading" : "Failed to read"}
{part.input?.path}
</TraceTitle>
</TraceLine>
</Trace>
);
}
return (
<Trace key={part.toolCallId}>
<Sheet>
<SheetTrigger>
<TraceLine>
<TraceIcon>
<FileTextIcon />
</TraceIcon>
<TraceTitle>Read {part.output.path}</TraceTitle>
<TraceIcon>
<ChevronRightIcon />
</TraceIcon>
</TraceLine>
</SheetTrigger>
<SheetContent>
<SheetHeader>
<SheetTitle className="font-mono">
{part.output.path}
</SheetTitle>
<SheetDescription>
{part.output.content.split("\\n").length} lines
</SheetDescription>
</SheetHeader>
<CodeBlock className="mx-6 mb-6 w-auto">
<CodeBlockContent lineNumbers>
{part.output.content}
</CodeBlockContent>
</CodeBlock>
</SheetContent>
</Sheet>
</Trace>
);
})}
</MessageContent>
</Message>
);
})}
{!busy && (
<Button
className="mt-auto self-start"
onClick={() =>
nextMessage
? sendMessage(nextMessage)
: setMessages(initialMessages)
}
size="sm"
variant="outline"
>
{nextMessage ? "Send message" : "Reset"}
</Button>
)}
</div>
);
}Approval
Mark a tool with needsApproval: true and the call pauses with state: "approval-requested". Render it as an Item outside the trace, with Deny and Approve buttons. addToolApprovalResponse from useChat sends the decision, and sendAutomaticallyWhen resumes the assistant turn.
writer.tool("runCommand", {
input: { command: "rm -rf dist" },
needsApproval: true,
output: { stdout: "" },
})"use client";
import { useChat } from "@ai-sdk/react";
import {
lastAssistantMessageIsCompleteWithApprovalResponses,
type UIDataTypes,
type UIMessage,
} from "ai";
import { CircleCheckIcon, LoaderCircleIcon, TerminalIcon } from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
import {
Item,
ItemActions,
ItemContent,
ItemDescription,
ItemMedia,
ItemTitle,
} from "@/components/ui/item";
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 };
};
}
>;
const chat = createChat<ChatMessage>()
.user("Clean up the build folder.")
.sleep(600)
.assistant(({ writer }) => {
writer.reasoning(
"The build output lives in dist. Deleting it cannot be undone, so I should ask before I run the command."
);
writer.sleep(400);
writer.tool("runCommand", {
input: { command: "rm -rf dist" },
needsApproval: true,
output: { stdout: "" },
});
})
.assistant(({ writer, toolCall }) => {
writer.sleep(600);
writer.text(
toolCall?.approved
? "Removed the dist folder."
: "Okay, I left the dist folder in place."
);
});
const initialMessages = chat.get(0);
const transport = chat.transport({ delayMs: 20 });
export function ToolApproval() {
const {
messages,
sendMessage,
setMessages,
status,
addToolApprovalResponse,
} = useChat<ChatMessage>({
messages: initialMessages,
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
transport,
});
const nextMessage = chat.next(messages);
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>
);
}
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{message.parts.map((part, index) => {
if (part.type === "text") {
return <p key={index}>{part.text}</p>;
}
if (part.type === "reasoning") {
return (
<Trace key={index}>
<ReasoningLine
running={part.state === "streaming"}
text={part.text}
/>
</Trace>
);
}
if (part.type !== "tool-runCommand") {
return null;
}
if (part.state === "approval-requested") {
return (
<Item key={part.toolCallId} variant="outline">
<ItemMedia>
<TerminalIcon />
</ItemMedia>
<ItemContent>
<ItemTitle>Run {part.input.command}?</ItemTitle>
<ItemDescription>
The command runs in this project.
</ItemDescription>
</ItemContent>
<ItemActions>
<Button
onClick={() =>
addToolApprovalResponse({
approved: false,
id: part.approval.id,
})
}
size="sm"
variant="outline"
>
Deny
</Button>
<Button
onClick={() =>
addToolApprovalResponse({
approved: true,
id: part.approval.id,
})
}
size="sm"
>
Approve
</Button>
</ItemActions>
</Item>
);
}
const denied =
part.state === "output-denied" ||
(part.state === "approval-responded" &&
!part.approval.approved);
return (
<Trace key={part.toolCallId}>
<TraceLine
status={
!denied && part.state !== "output-available"
? "running"
: undefined
}
>
<TraceIcon>
<TerminalIcon />
</TraceIcon>
<TraceTitle>
{denied
? "Denied"
: part.state === "output-available"
? "Ran"
: "Running"}
{part.input?.command}
</TraceTitle>
</TraceLine>
</Trace>
);
})}
</MessageContent>
</Message>
);
})}
{!busy && (
<Button
className="mt-auto self-start"
onClick={() =>
nextMessage
? sendMessage(nextMessage)
: setMessages(initialMessages)
}
size="sm"
variant="outline"
>
{nextMessage ? "Send message" : "Reset"}
</Button>
)}
</div>
);
}
function ReasoningLine({ text, running }: { text: string; running: boolean }) {
const [open, setOpen] = React.useState<boolean>();
return (
<TraceCollapsible onOpenChange={setOpen} open={open ?? running}>
<TraceCollapsibleTrigger>
<TraceLine status={running ? "running" : undefined}>
<TraceIcon>
{running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleCheckIcon />
)}
</TraceIcon>
<TraceTitle>{running ? "Thinking" : "Thought"}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="text-muted-foreground whitespace-pre-wrap">
{text}
</TraceCollapsibleContent>
</TraceCollapsible>
);
}Accessibility
- The status icon is decorative. The
TraceTitlecarries the state. - Approval prompts use
Itemwith two buttons. Each button is a real<button>with a clear label. - Failed calls auto-expand their output. Screen readers announce the open state via the trigger.
prefers-reduced-motiondisables the spinner and collapse animation.
Best Practices
- Show the command, not the tool name. Users care what runs, not what it is called.
- Auto-expand failures. A failing tool needs its output visible.
- Ask before destructive commands.
needsApprovalfor anything that writes or deletes. - Pair with a plain-text summary. The tool row is evidence, not the answer.