Skip to content
Browse documentation
whisk/ui

ToolCall

Show an application-owned tool invocation and its result.

Overview

ToolCall presents an application-owned tool invocation as an expandable status, request, and optional result or error. It does not execute a tool, parse payloads, authorize data, or retain the conversation history.

Use when

A user needs to inspect the status, request, and result of an application-owned tool call.

Use instead

Use Alert for a simple status message without expandable request or result details.

Usage

import { useState } from "react";
import { ToolCall } from "@smoothie-framework/whisk-react";

const [open, setOpen] = useState(false);

<ToolCall
  label="Search documentation"
  request="query: deployment guide"
  result="Found 3 matching pages."
  state="completed"
  open={open}
  onOpenChange={setOpen}
/>

Examples

Show live work

Map application state to the ToolCall lifecycle. activeLabel replaces the operation label only while state is running; ToolCall does not start, poll, cancel, or retry the operation.

query: deployment guide
import { useState } from "react";
import { ToolCall } from "@smoothie-framework/whisk-react";

const [open, setOpen] = useState(true);

<ToolCall
  label="Search documentation"
  activeLabel="Searching documentation"
  request="query: deployment guide"
  state="running"
  open={open}
  onOpenChange={setOpen}
/>

Explain a failure

Supply a concise, audience-safe error. ToolCall chooses error presentation only when state is failed; your application decides what error data can be shown and how a retry works.

query: deployment guide
Search could not finish. Try again.
import { useState } from "react";
import { ToolCall } from "@smoothie-framework/whisk-react";

const [open, setOpen] = useState(true);

<ToolCall
  label="Search documentation"
  request="query: deployment guide"
  error="Search could not finish. Try again."
  state="failed"
  open={open}
  onOpenChange={setOpen}
/>

Compose a custom disclosure

Use named parts when the compact ToolCall does not fit the application-owned presentation. Keep one trigger and one details group inside the same root; request and result content remain ordinary authored nodes.

import { useState } from "react";
import {
  Code,
  ToolCallDetails,
  ToolCallRequest,
  ToolCallResult,
  ToolCallRoot,
  ToolCallStatus,
  ToolCallSummary,
  ToolCallTrigger,
} from "@smoothie-framework/whisk-react";

const [open, setOpen] = useState(false);

<ToolCallRoot state="completed" open={open} onOpenChange={setOpen}>
  <ToolCallTrigger>
    <ToolCallSummary target="workspace.config.ts">
      Read workspace configuration
    </ToolCallSummary>
    <ToolCallStatus />
  </ToolCallTrigger>
  <ToolCallDetails>
    <ToolCallRequest><Code>workspace.config.ts</Code></ToolCallRequest>
    <ToolCallResult>Read 12 settings.</ToolCallResult>
  </ToolCallDetails>
</ToolCallRoot>

Props

Component props

PropTypeDefaultDescription
label | requestReactNoderequired | requiredName the application-owned operation and provide its authored request content. ToolCall does not parse or redact either value.
statepending | running | completed | failedrequiredProvide the current application-owned lifecycle state. It selects the default visible status text and which terminal payload may render.
openbooleanrequiredControl whether request and terminal details are disclosed. ToolCall never owns this state.
onOpenChange(open: boolean) => voidrequiredReceive the next disclosure state after the native trigger is activated.
result | errorReactNodenoneRender result only when state is completed, or error only when state is failed. Other supplied terminal content is not rendered.
activeLabel | statusLabelReactNodenone | state nameReplace the operation label while running or localize the visible status. The defaults are Pending, Running, Completed, and Failed.
target | icon | disclosureIcon | statusIconReactNodenoneAdd authored context or replace decorative visual icons. Do not use an icon as the only status signal.
announcebooleanfalseOpt into a polite, atomic status region. Prefer one application-owned announcer when a transcript can update frequently.
unmountOnExitbooleantrueUnmount request and terminal payload children while closed. Set false only when retained closed content is necessary and safe to keep in the DOM.
native section propsHTMLAttributes<HTMLElement>noneAdd an id, direction, data attribute, or application-owned relationship to the ToolCall root.

Accessibility

ToolCall renders a section containing a native button. The button exposes aria-expanded and aria-controls for the details group, so Enter and Space toggle it. Closed details are hidden and inert; payload children are unmounted by default. If a controlled close occurs while focus is inside the details, focus returns to the trigger. Status is plain accessible text by default, not a live region. Set announce only for a meaningful, infrequent update; it creates a polite, atomic status region. Decorative icons are hidden from assistive technology. Keep the operation label, status, and any error understandable without color or iconography, and do not expose credentials or unapproved request or result data.

Content guidance

Name the user-facing operation, not an internal function. Show only request and result details that are safe for this audience, and make an error say what happened and what the person can do next.