ComponentsTool Call

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_web
read_file
send_email

Installation

  1. 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

StatusIconCard
pendingHollow circleQueued, no duration
runningSpinning arcTitle shimmers, duration ticks live
awaiting-approvalRing with pulsing dotHighlighted, breathing border, Deny / Approve
successCircle fills, check draws inDuration freezes
errorX draws inCard shakes once, error banner with Retry
cancelledDashed circle with a dashMuted

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

PropTypeDefaultDescription
name*string—Machine name, e.g. "search_web". Shown in mono.
titleReactNodenameHuman label, e.g. "Searching the web".
iconLucideIcon—Icon before the title.
status
"pending""awaiting-approval""running""success""error""cancelled"
"pending"Lifecycle.
inputunknown—Arguments, shown in a collapsible JSON viewer.
outputunknown—Result, shown in the JSON viewer or renderOutput.
errorstring—Message shown for status "error".
startedAt / endedAtnumber | Date—Duration ticks live while running, then freezes.

ToolCallGroup

PropTypeDefaultDescription
label(count: number) => ReactNode—Override the "Used 3 tools" header.
defaultCollapsedbooleanfalseStart collapsed.

JsonViewer

PropTypeDefaultDescription
value*unknown—Any JSON-serialisable value.
labelstring—Section label, e.g. "Input".
defaultOpenDepthnumber2Levels expanded by default.
maxLinesnumber12Lines before "Show more".

Accessibility

  • The card header is a button with aria-expanded; collapsed content is inert.
  • 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.