Components/Tool Call Card

Tool Call Card

A status card for a single tool call.

VerifiedSince 0.3.9

Usage

Basic

The host advances toolCall.status; the expanded body switches content with it.

Loading demo...

Best Practices

  • Put structured results (a table, a chart, a widget) in the result slot and keep output as the plain-text fallback.
  • On retry, set status back to running right away so users don't click repeatedly.
  • Append logs line by line instead of replacing the block, so tail-following stays smooth.
  • On non-English surfaces, override the label props (including linesToggleFormatter) together to avoid a mixed-language card.
  • Write summary as what the call did, not the tool name again; the collapsed row is all users scan.

API Reference

Props

NameTypeDefaultDescription
toolCallAiToolCallPart—The call to render. Required.
defaultExpandedbooleanfalseInitial expanded state; read once, on mount.
userOpenboolean—Host-held expanded state; wins over the reader's click and auto-expansion. Omit it to let the card own the state.
retryLabelstring'Retry'Label of the retry button.
pendingLabelstring'Queued'Label for pending.
runningLabelstring'Running'Label for running.
doneLabelstring'Done'Label for done and any unmatched status.
errorLabelstring'Failed'Label for error.
inputLabelstring'Input'Accessible name of the input section; not drawn as a heading.
emptyResultLabelstring'No output'Shown in the result area when a done call has no output and no input, and no result slot is given.
showRetryboolean—Shows the retry button; when unset, the button appears only if a retry listener is bound.
linesToggleFormatter(hiddenCount: number, expanded: boolean) => string'N more lines' / 'Show less'Label of the toggle when the input runs past four lines.

AiToolCallPart is { type, id, name, status, summary?, input?, output?, error?, logs?, durationMs? }, where status is 'pending' | 'running' | 'done' | 'error'.

Events

NamePayloadDescription
retry(id: string)Fires when retry is clicked, with toolCall.id.
toggle(expanded: boolean)Fires when the header is clicked, with the new expanded state.

Slots

NameScopeDescription
summary{ toolCall }Replaces the arguments text in the header (defaults to summary, then the first input line).
result{ toolCall }Result surface for the host's own rendering; replaces output when provided.
icon{ status }Replaces the status icon.

CSS Variables

VariableDefaultDescription
--tx-tool-call-card-log-color#d6e2f0Text colour of the log area.

Overview

  • The body follows status: running shows logs, done shows the result slot (falling back to output), and error shows error; input shows whenever it is set.
  • The header reads: elapsed time while in flight ((1.0)), the name (shimmering while in flight), the arguments (summary, else the first input line), then the duration once durationMs is set.
  • pending and running auto-expand; once settled the card collapses and keeps the last two lines of output as a preview. Logs, output and the preview stay pinned to their bottom, and every change to logs scrolls the log region down.
  • Input longer than four lines shows its first four and a toggle built by linesToggleFormatter; the footer shows the status.
  • The retry button appears only in the error state: showRetry true shows it, false hides it, and when unset it shows only if a retry listener is bound.
  • status is mirrored onto the root's data-status for styling.

Technologies

  • AiToolCallPart is defined and exported by ai-elements.
  • Source: packages/tuffex/packages/components/src/tool-call-card/.