# Approval Card

The human-in-the-loop gate: what the agent wants to do, how risky it is, approve or reject.

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

## Install

Approval Card ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

Then use it:

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

export function Request({ onAnswer }: { onAnswer: (answer: "approved" | "rejected") => void }) {
  return (
    <ApprovalCard
      title="Send 14 payment reminders"
      summary="Emails the contact on every invoice more than 30 days overdue. Sent emails cannot be recalled."
      risk="medium"
      onApprove={() => onAnswer("approved")}
      onReject={() => onAnswer("rejected")}
    />
  )
}
```

Expected result: You should see a card with a shield, the title, a Medium risk badge, the summary, and Approve and Reject buttons. Press one and the buttons give way to Approved or Rejected, and your handler runs.

## When to use

### Use Approval Card for

- A step an agent may not take without a person's yes: sending, deleting, paying, publishing
- A permission an agent asks for, an edit it proposes (with a diff) or a run that goes over its budget
- A request that can lapse, with the time left and a clear outcome when it does

### Use something else

- [Tool Permission Row](https://wunderui.com/components/tool-permission-row) for a lasting Allow, Ask or Deny setting per tool
- [Alert Dialog](https://wunderui.com/components/alert-dialog) for a confirmation of the person's own action, outside an agent run
- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of a run; the card goes inside the step that waits

## Keyboard

Every control is a native button, so the browser provides focus and activation. The card itself is not in the tab order: it takes focus only when your code focuses it.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the details toggle (inline and high-cost), then Approve, the second yes, Reject and Edit, in that order. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | On Approve, Reject, the second yes or Edit: answers or runs it. On the details toggle: opens or closes the payload (`aria-expanded` follows). After an answer, focus moves to the card. |
| `Esc` | Does nothing. An unanswered request stays open until it is answered or expires; closing it is not an answer. |

## Behavior

What the card does when it is answered, controlled or left alone, and what it leaves to you.

- **Answering:** Uncontrolled, the card resolves in place: Approve (and the second yes) approves, Reject rejects, then your handlers run. Edit calls its handler and leaves the request pending.
- **Controlled:** When you set the state, the card shows exactly that. A press calls your handler but changes nothing and an expiry only calls the expire handler, so update the state when the decision is saved.
- **Expiry:** An expiry starts a countdown (9m 00s left) that turns red under a minute and expires a pending card at zero. An answered card never expires; the expire handler runs once.
- **First paint:** The countdown is empty on the server and the first client render, and fills in after mount, so the card never prints a stale time.
- **Details:** In inline and high-cost kinds the preview sits behind a toggle that starts closed unless you open it by default. In dialog-diff and permission it is shown at once, and closed details are inert.
- **Focus:** The card is a focusable group named by its title. Focus it when a request needs attention; after an answer or expiry focus moves to it unless your handler already moved it.
- **Live region:** The card has no live region. A new card, an answer and an expiry are not announced, so mount a status line next to it before it has text and say what changed.
- **Failure and abort:** Rejected means a person said no, Expired without an answer means nobody did, and in both nothing ran. Say what the agent does instead next to the card.
- **Motion:** The details open smoothly and the chevron turns. Nothing else on the card moves.
- **Reduced motion:** With reduced motion on, the details and chevron change at once. The countdown, the outcome and every state are unchanged.

## Anatomy

- `ApprovalCard`: A bordered, rounded card built as a labelled group named by its title. The border is indigo while pending and neutral after an answer, and the card takes focus by script, not by Tab.
- `Risk icon`: A 32 px shield tile, tinted green, amber or red by risk. Decorative: the risk badge says the same in words.
- `Title`: The request in one line, 14 px semibold. It names the group for assistive technology.
- `Risk badge`: Low risk, Medium risk or High risk (medium by default). It labels the request and does not change the buttons.
- `Summary`: One sentence, 13 px: what happens if the request is approved. Write the consequence, not the mechanism.
- `Request line`: The request time as you wrote it, then a clock and the time left (8m 56s left) while pending with an expiry set. The time turns red under a minute; the line is gone after an answer.
- `Details`: The preview payload. In inline and high-cost kinds it sits behind a Show what will run toggle; in dialog-diff and permission it is shown at once.
- `Actions`: Approve (filled), an optional softer secondary action, Reject (plain), and Edit if given. Labels follow the kind unless you pass your own, and after an answer the row becomes the outcome.
- `Cost banner`: In the high-cost kind with a cost: an amber banner with the estimate, the run budget and a note, shown above the details.
- `Outcome`: Approved, Rejected or Expired without an answer, with a check, cross or clock in the outcome's colour. It replaces the buttons and does not name who decided: write that under the card.

## Best practices

### When to use

- Use it wherever an agent may not go on without a person's yes. For a lasting Allow, Ask or Deny setting per tool use Tool Permission Row; for a typed answer use a form.

### Do

- Write the summary as the consequence in one sentence (Sent emails cannot be recalled), set the risk honestly and put the exact payload in the preview so people can inspect what will run.
- When the default words are too vague, name the buttons after what happens: Send 14 reminders, Don't send. Reject stays next to Approve, never in a menu.
- When a request appears, move focus to the card, never to Approve, and say it in a status line. The card does not announce itself.
- Write who decided and when as a line under the card, like Approved by Nora Lindgren at 14:02. The card shows the outcome; naming the person is up to you.
- Set an expiry where requests lapse, and use the expire handler to tell your agent that nobody answered and nothing ran. Pass the expired state back so card and store agree.
- Show two requests at once, oldest first, each on its own. Answering one never answers the other.

### Don't

- Don't start in the approved state or approve inside your own handler. A default yes removes the gate, and no button may take focus on its own.
- Don't read high risk as a lock: it adds no confirmation and changes no button. For an action that cannot be undone, say so in the summary and on the button.
- Don't offer a second yes such as Always allow on a high-risk request, and don't add a louder Approve elsewhere. A lasting yes is a decision of its own.

## API reference

### ApprovalCard

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The request in one line. Also the accessible name of the card. |
| approveLabel | string |  | The text of the Approve button. Defaults per kind: Approve, Allow once, Allow, Run anyway. |
| className | string |  | Extra classes for the card, for example `w-full` or a margin. |
| cost | { estimate: React.ReactNode; budget?: React.ReactNode; note?: React.ReactNode } |  | For `high-cost`: `{ estimate, budget?, note? }`, shown in an amber banner above the details. Nothing is drawn without it. |
| defaultOpen | boolean | false | Opens the details toggle on the first render, in `inline` and `high-cost`. `false` by default. |
| expiresAt | Date \| string \| number |  | A `Date`, an ISO string or a timestamp. A pending card counts down to it and resolves as `expired` at zero (when `state` is not set). `onExpire` is called at that moment either way. |
| kind | "inline" \| "dialog-diff" \| "permission" \| "high-cost" | "inline" | `inline` (default), `dialog-diff`, `permission` or `high-cost`. Picks where the payload sits and the default button words. |
| leading | React.ReactNode |  | A slot before the risk icon, for a selection checkbox in a queue. Not rendered when empty. |
| onApprove | () => void |  | Called when Approve is pressed, after the card has resolved (uncontrolled) or at once (controlled). |
| onEdit | () => void |  | When given, an Edit button appears beside Reject. It leaves the request pending. |
| onExpire | () => void |  | Called once when `expiresAt` passes while the card still waits for an answer, also in controlled mode. Store the outcome and stop the run here; set `state="expired"` if you control the card. Not called for an answered card or again for the same time. |
| onReject | () => void |  | Called when Reject is pressed. |
| preview | React.ReactNode |  | The payload, diff or scopes behind the request, for example a pre block, a DiffView or a ScopeList. Behind a toggle in `inline` and `high-cost`, shown at once in `dialog-diff` and `permission`. |
| ref | React.Ref<HTMLDivElement> |  | Reaches the card. Call `ref.current.focus()` when a new request needs attention, instead of focusing Approve. |
| rejectLabel | string |  | The text of the Reject button. Defaults per kind: Reject, Reject, Deny, Cancel. |
| requestedAt | React.ReactNode |  | Shown as written next to the countdown, for example `2 min ago`. Not formatted by the card. |
| resolvedAt | React.ReactNode |  | When it was decided, shown as given after the decision ("Approved by Nora Lindgren · 2 min ago"). |
| resolvedBy | React.ReactNode |  | Who decided, shown in the resolved line ("Approved by Nora Lindgren"). Text or an element. |
| risk | "medium" \| "low" \| "high" | "medium" | `low`, `medium` (default) or `high`. Sets the label and the tint of the icon. It does not change the buttons. |
| secondaryAction | { label: string; onClick?: () => void } |  | `{ label, onClick? }`. A softer second yes such as `Always allow`. It resolves the card as approved and calls its own `onClick`, not `onApprove`. |
| state | "pending" \| "approved" \| "rejected" \| "expired" |  | `pending`, `approved`, `rejected` or `expired`. Pass it to control the card from your store; leave it out and the card resolves itself. |
| summary | React.ReactNode |  | One sentence: what happens if this is approved. |
| warnAt | number | 60_000 | Milliseconds left at which the countdown turns amber. Passed to the Expiry Timer inside the card. Default `60000`. |

## Examples

### Kind: inline, diff, permission and high cost

### Risk: low, medium and high, each with a request that fits

### Actions: the default pair, own labels, a second yes, Edit

### Expiry: counting, the last minute, expired

### Resolved: who decided, when, and a batch checkbox

## In context

### A request arrives: focus goes to the card, the answer is written down

Press Simulate a request. The card appears and takes focus as a group, not on Approve, and a status line says what is waiting, then after you answer it says who decided and when.

### Two requests at once: oldest first, each on its own

Answering one request never answers the other, and the line above says how many are still waiting. Show both, oldest first, and keep the high-risk one visible while the first is open.

### Over budget: the run is paused until someone decides

The high-cost card shows the estimate against the budget and a cheaper second yes. Every answer states what happens next and what it costs, and the run state follows the answer.

### Expiry: nobody answers

The request lapses after 10 seconds and your code is told once. The demo passes the state back so card and store agree, and the line says nothing was sent, with Ask again opening a new request.

## For AI agents

`get_component("approval-card")`

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