# ApprovalRequest

ApprovalRequest presents a consequential decision with details, consequences, explicit choices, and a separate submission action.

State the consequence before the choice. Selecting approve or reject only updates the decision. Use a full warning border for a blocked request. Require explicit submission and keep the terminal result visible.

<h2 id="purpose">Purpose</h2>

Use ApprovalRequest when an agent needs human authorization before consequential work. Do not use it as a passive status card or an automatic confirmation.

<h2 id="anatomy">Decision flow</h2>

State the consequence before the decision controls. A radio choice updates `decision` but does not call `onSubmit`. The user must activate the submit action to approve or reject the request.

ApprovalRequest does not render a form. Its submit action uses `type="button"` and calls `onSubmit` only after a valid choice. The component can sit inside a consumer-owned form without causing a nested form or an implicit form submission.

Use `onEdit` when the user can change the proposed operation before deciding. Do not treat editing as approval. Keep request details specific enough to identify the target, scope, and expected side effects.

Only queued or blocked requests accept a decision. Application state owns the transition after submission and must keep the terminal result visible. A failed result must state whether any changes were applied.

<h2 id="focus-and-announcements">Focus and announcements</h2>

Set `focusHeading` when a newly active request needs focus. Do not move focus on routine data refreshes. Supply one completed status announcement and avoid a duplicate live region around the component.

<h2 id="tokens">Tokens and style hooks</h2>

ApprovalRequest uses a complete warning border for blocked requests and a complete danger border for failed requests. The consequence remains on a quiet inset layer. The component also uses display type, mono detail, radius, spacing, and focus tokens.

## API

The package declarations define these public members.

| Member | Type | Kind | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `announcement` | `string` | prop | No | `undefined` | Message for the owned live region. |
| `approveLabel` | `string` | prop | Yes | - | No additional description. |
| `busy` | `boolean` | prop | No | `false` | No additional description. |
| `decision` | `ApprovalDecision \| null` | binding | No | `null` | No additional description. |
| `decisionLabel` | `string` | prop | Yes | - | No additional description. |
| `disabled` | `boolean` | prop | No | `false` | No additional description. |
| `editLabel` | `string` | prop | No | `undefined` | No additional description. |
| `focusHeading` | `boolean` | prop | No | `false` | Moves focus to the decision heading when the request becomes active. |
| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | prop | No | `2` | Heading level for the request title. Nested headings use the next level, capped at 6. |
| `onDecisionChange` | `(decision: ApprovalDecision) => void` | callback | No | `undefined` | No additional description. |
| `onEdit` | `(requestId: string) => void` | callback | No | `undefined` | No additional description. |
| `onSubmit` | `(requestId: string, decision: ApprovalDecision) => void` | callback | Yes | - | No additional description. |
| `rejectLabel` | `string` | prop | Yes | - | No additional description. |
| `request` | `ApprovalRequestData` | prop | Yes | - | No additional description. |
| `submitLabel` | `string` | prop | Yes | - | No additional description. |

## Related

- [ActivityStatus](/docs/components/activity-status): Compact agent activity status with elapsed time, task progress, and one live announcement.
- [AgentTrace](/docs/components/agent-trace): Controlled disclosure of observable stages, searches, tools, files, and checks.
- [AgentResponse](/docs/components/agent-response): Assistant result with consumer-rendered content, streaming state, sources, actions, and follow-up prompts.