# Action (/docs/agent-ui/components/action)

Use an action for the answer to something a person ran on part of a reply, like **Explain** from a [Selection](./selection.mdx). It quotes the text the action ran on and shows the result below it, in a step that folds away once it's done.

<Example caption="Press Explain, or focus it and press Enter or Space, to show the quote and the result.">
<g />

```tsx
import { Action } from "@/components/ui/action";

export default function ActionExample() {
  return (
    <Action
      status="complete"
      label="Explain"
      quote="Add a retry with exponential backoff."
      result="**Exponential backoff** waits longer after each failed attempt, like 1 s, then 2 s, then 4 s. A server that's struggling gets room to recover instead of a burst of retries."
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/action
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/action-web
```

## Composition [#composition]

```text
Action
├── ActionTrigger
│   ├── ActionIcon
│   └── ActionTitle
└── ActionContent
    ├── ActionQuote
    └── ActionResult
```

`Action` renders these parts when you pass no children; any children you pass replace them. The trigger is a native button that shows or hides the content. `ActionTitle` shows the `label`, `ActionQuote` renders `quote` as a block quote, and `ActionResult` renders `result` as [Markdown](./markdown.mdx). The quote and the result are left out while they're empty.

## Usage [#usage]

### Quote and Result [#quote-and-result]

Pass the action's name as `label`, the text it ran on as `quote`, and what it returned so far as `result`. Set `status` as the work moves along, as a [Step](./step.mdx) does.

```tsx
<Action label="Explain" quote={text} result={answer} status={isDone ? "complete" : "running"} />
```

While the status is `running`, the content stays open and `result` renders as streaming Markdown: each chunk parses only the blocks it changed. When the status turns `complete`, the content closes on its own, unless someone opened or closed it in the meantime. An action that goes straight from `pending` to `complete` stays closed.

### Announcements [#announcements]

When the action completes or fails, screen readers hear its title, like "Explain complete" or "Explain failed", once. The streamed result is quiet.

### Motion [#motion]

The content grows open and shut. Under `prefers-reduced-motion`, or with `motion="reduced"`, it fades over 120 ms instead, and with `motion="none"` it changes at once.

## API Reference [#api-reference]

### ActionOptions

| Prop               | Type                                                                                   | Description                                                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status?`          | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`   | What the step is doing. The icon shows it. Default: `"pending"`                                                                                                                                |
| `kind?`            | `string \| undefined`                                                                  | Written as `data-kind`, for styling by step type.                                                                                                                                              |
| `open?`            | `boolean \| undefined`                                                                 | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                |
| `defaultOpen?`     | `boolean \| undefined`                                                                 | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                |
| `onOpenChange?`    | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined` | Called when the step opens or closes, with what caused it.                                                                                                                                     |
| `autoOpen?`        | `"never" \| "running"`                                                                 | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"` |
| `durationSeconds?` | `number \| undefined`                                                                  | Written as `--kind-step-duration`.                                                                                                                                                             |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                   |
| `label?`           | `string \| undefined`                                                                  | The title, like "Explain". Also names the action in announcements. Default: `"Action"`                                                                                                         |
| `quote?`           | `string \| undefined`                                                                  | The text the action was run on, shown as a quote above the result.                                                                                                                             |
| `result?`          | `string \| undefined`                                                                  | What the action returned so far, as markdown. Appending parses only the blocks that changed.                                                                                                   |

### Agent [#agent]

An agent connected with `createAgent` finds an action by its title and reads its `open` and `status`. It can run these actions, and press the trigger like a person would:

### ActionAgentActions

| Prop       | Type            | Description                                               |
| ---------- | --------------- | --------------------------------------------------------- |
| `expand`   | `() => boolean` | Opens the step. Returns whether the change was accepted.  |
| `collapse` | `() => boolean` | Closes the step. Returns whether the change was accepted. |

<Caption>
Runs in React and Web Components. On `<kind-action>`, each prop is a kebab-case attribute, so `autoOpen` is `auto-open`, and `onOpenChange` fires `openchange`. The element fills in its parts when it has no children, writes `quote` into its `<kind-action-quote>`, and writes `result` into a `<kind-markdown>` in its `<kind-action-result>`.
</Caption>