Tool Call
Shows an agent calling a tool — morphing status icon, live duration, expandable JSON input and output, and an approval mode for risky actions.
Preview
Find how to cache /products, check our page file, then email the team.
Searching the web is queued
Input
"query": "next.js fetch cache revalidate tags",
"max_results": 3,
"recency": "year"
}
Reading app/products/page.tsx is queued
Send summary to the team is queued
Manual status
search_webread_filesend_emailInstallation
- 1
Run the following command
npx shadcn@latest add https://localhostui.com/r/tool-call.json
Also copy json-viewer.tsx from the same folder and shimmer-text/shimmer-text.tsx (the CLI installs both).
Status reference
| Status | Icon | Card |
|---|---|---|
pending | Hollow circle | Queued, no duration |
running | Spinning arc | Title shimmers, duration ticks live |
awaiting-approval | Ring with pulsing dot | Highlighted, breathing border, Deny / Approve |
success | Circle fills, check draws in | Duration freezes |
error | X draws in | Card shakes once, error banner with Retry |
cancelled | Dashed circle with a dash | Muted |
Examples
Approval flow
<ToolCall
name="send_email"
title="Send summary to the team"
status={status}
input={args}
approvalDescription="Sends one email to team@example.com. This can't be undone."
onApprove={async () => {
setStatus("running");
await runTool(args);
setStatus("success");
}}
onDeny={() => setStatus("cancelled")}
/>When the card is focused, Enter approves and Esc denies.
Custom output renderer
<ToolCall
name="search_web"
status="success"
output={{ results }}
renderOutput={(output) => (
<ul>
{(output as { results: Result[] }).results.map((r) => (
<li key={r.url}>{r.title}</li>
))}
</ul>
)}
/>With the Vercel AI SDK
Map tool parts to cards. Approval maps onto tools that return needsApproval, or onto your own confirmation step before you call addToolResult.
const STATE: Record<string, ToolCallStatus> = {
"input-streaming": "pending",
"input-available": "running",
"output-available": "success",
"output-error": "error",
};
<ToolCallGroup>
{message.parts
.filter((p) => p.type.startsWith("tool-"))
.map((p) => (
<ToolCall
key={p.toolCallId}
name={p.type.replace("tool-", "")}
status={STATE[p.state] ?? "pending"}
input={p.input}
output={p.output}
error={p.errorText}
/>
))}
</ToolCallGroup>Props
ToolCall
| Prop | Type | Default | Description |
|---|---|---|---|
name* | string | — | Machine name, e.g. "search_web". Shown in mono. |
title | ReactNode | name | Human label, e.g. "Searching the web". |
icon | LucideIcon | — | Icon before the title. |
status | "pending""awaiting-approval""running""success""error""cancelled" | "pending" | Lifecycle. |
input | unknown | — | Arguments, shown in a collapsible JSON viewer. |
output | unknown | — | Result, shown in the JSON viewer or renderOutput. |
error | string | — | Message shown for status "error". |
startedAt / endedAt | number | Date | — | Duration ticks live while running, then freezes. |
ToolCallGroup
| Prop | Type | Default | Description |
|---|---|---|---|
label | (count: number) => ReactNode | — | Override the "Used 3 tools" header. |
defaultCollapsed | boolean | false | Start collapsed. |
JsonViewer
| Prop | Type | Default | Description |
|---|---|---|---|
value* | unknown | — | Any JSON-serialisable value. |
label | string | — | Section label, e.g. "Input". |
defaultOpenDepth | number | 2 | Levels expanded by default. |
maxLines | number | 12 | Lines before "Show more". |
Accessibility
- The card header is a button with
aria-expanded; collapsed content isinert. - Status changes are announced politely, e.g. “search_web succeeded in 1.4 seconds”.
- Approve / Deny buttons include the tool name in their labels.
- With reduced motion the spinner becomes a pulsing opacity and the error shake is skipped.