# Chat Tool

A collapsible card showing a tool/function call's name, status, and result.

- Category: AI & Agents
- Page: https://wunderui.com/components/chat-tool
- Tier: Core and Pro

## Install

Chat Tool ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ChatTool, ChatToolStatus } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ChatTool } from "@wunderui/react"

export function Call({ status }: { status: "running" | "done" | "error" | "cancelled" }) {
  return (
    <ChatTool name="Search documents" status={status} duration="1.2 s" error="The request timed out after 30 s">
      12 matches in 4 files
    </ChatTool>
  )
}
```

Expected result: You see a card with a wrench, the name Search documents, 1.2 s, a green check and a chevron. Press it to open the result, and set the status to error to turn it red with the reason.

## When to use

### Use Chat Tool for

- A tool or function call an assistant makes inside a message
- A call that takes a moment, so the reader sees it running and then done, failed or cancelled
- Input, result and duration of a call behind a disclosure

### Use something else

- [Chat Loader](https://wunderui.com/components/chat-loader) for the dots while the assistant has not started its answer
- [Run Timeline](https://wunderui.com/components/run-timeline) for a whole run with many steps, tools and results
- [Alert](https://wunderui.com/components/alert) for an error that is about the whole page or request, not one tool call

## Keyboard

The header is a native button, so the browser handles focus and activation. A tool without content has no disclosure and does nothing on a press.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the header button, and, when the details are open, on to the buttons and links inside them. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | Opens or closes the details of the focused tool. `aria-expanded` follows. |

## Behavior

What the card does with its details, its status, assistive technology and motion.

- **Disclosure:** With content, the header is a disclosure button that reports whether it is expanded, and the card starts closed with no prop to open it. Without content there is no chevron.
- **Details:** The details stay mounted and are inert while closed, so nothing inside takes focus or is read out. They grow and shrink with the same height transition the Collapsible uses.
- **Status:** Running shows a turning loader, done a check, error a warning triangle on a red card, cancelled a muted ban. The word is hidden text in the button, and a change is not announced.
- **Duration:** The duration is shown as given, before the status mark, in tabular numbers so a changing value does not shift the row. Format it yourself, for example 1.2 s.
- **Live region:** Add a status line next to the card, mounted before it has text, saying the tool is running, then how long it took or why it failed. In a chat log, keep it marked busy while the reply streams.
- **Failure and cancel:** Error turns the card red and shows the error text under the name, and cancelled keeps it neutral. Neither has a retry control, so add a Button and set the status back to running.
- **States:** Focus is an indigo border with a 2 px ring on the header. The header has no hover fill.
- **Motion:** The loader turns, the details open with a smooth height change, and the chevron turns quickly.
- **Reduced motion:** With reduced motion the loader stands still, the details open and close at once and the chevron turns at once. The status and its text stay as before.

## Anatomy

- `ChatTool`: A card with a 1 px border and a 16 px radius. The header is one full-width button with the details under it, and a failed call turns the border and fill red.
- `Tool icon`: A 14 px wrench in the tertiary text colour.
- `Name`: The name in 12 px medium text. It takes the free width and wraps when long, and a failed call shows its error text in a second line under it.
- `Status icon`: A 14 px mark: a turning loader while running, a green check when done, a warning triangle on error, a muted ban when cancelled. The turning stops under reduced motion.
- `Chevron`: A 14 px chevron that turns when the details are open. It is drawn only when the tool has content.
- `Details`: The content of the card, in a 16 px padded area under a 1 px divider. Closed details are inert, so they take no focus and are not read out.
- `Duration`: The duration in 12 px tabular numbers, before the status mark. It is drawn only when you pass it.
- `Hidden text`: The word Running, Done, Failed or Cancelled inside the header button, visible only to assistive technology. It is part of the button's name.

## Best practices

### When to use

- Use ChatTool for a tool call inside a chat message. For a file edit use Diff View, and for a run with many steps use Run Timeline.

### Do

- Pass the input, the result and the duration as content, in rows, to make the card open. Keep them short and as text.
- Set the status to running while the call is in flight, then done, error or cancelled. Screen readers hear it in the button's name, and the spinner stops under reduced motion.
- Say the change in a status line next to the card that is in the page before it has text. The button's name changes, but a changed name is not announced.
- Name the call for the person, like Search documents, and keep the function name and its arguments in the details.
- For a failed call, pass the reason as the error in one short sentence a person can act on, and put a Retry button next to the card.

### Don't

- Don't put a long stack trace into the error. It is one line under the name, so keep the full message in the details.
- Don't put anything the reader needs into the details while the card is closed. Closed details are inert, so their buttons cannot be reached.

## API reference

### ChatTool

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | string |  | The label of the call, one row of text that wraps when it is long. Also part of the button's name. |
| badge | React.ReactNode |  | Status pill rendered after the name, replacing the status icon. |
| children | React.ReactNode |  | The details behind the row: input, result, duration. With children the card has a chevron and opens; without them it does neither. |
| className | string |  | Extra classes for the card, for example `w-full` or a margin. |
| defaultOpen | boolean | false | Whether the body starts open. |
| detail | React.ReactNode |  | Muted detail shown next to the name in the header. |
| duration | string |  | How long the call took, for example `1.2 s`. Shown as given before the status mark, in any status. |
| error | string |  | Why the call failed, one short sentence under the name. Shown only when `status` is `error`. |
| input | React.ReactNode |  | Labelled input block shown at the top of the expanded body. |
| meta | React.ReactNode |  | Small text rendered after the duration. |
| mono | boolean | false | Renders the name in monospace at a slightly larger size. |
| output | React.ReactNode |  | Labelled output block shown after the input in the expanded body. |
| status | "error" \| "cancelled" \| "running" \| "done" | "done" | `running` shows the turning loader, `done` (default) the green check, `error` a warning triangle on a red card and `cancelled` a muted ban. The word for each is hidden text in the button. |

## Examples

### Details: the input, the input with the result, with the duration

### Result: done with the duration, failed with the reason, cancelled

### Name: a label, a call, a long name that wraps

### Detail, badge, meta, input and output

## In context

### Turn: the tool runs, then the answer streams

Press Ask the question. The tool shows its spinner and a status line says it is running, then how long it took, and the answer streams in after it.

### Copy: the input of a call

The details hold a button that copies the input to the clipboard. A status line under the card confirms it, and the button is out of reach while the details are closed.

### Outcome: finished, failed or cancelled

The tool shows finished, failed and cancelled itself. A failed call keeps the reason under its name and a Retry button, which runs the call again.

## For AI agents

`get_component("chat-tool")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
