# Reasoning (/docs/agent-ui/components/reasoning)

Use reasoning for the thoughts a model writes before it answers. It reads "Thinking" while the model works, then "Thought for 4 s", and keeps the thoughts one press away.

<Example caption="Press Thought for 4 s, or focus it and press Enter or Space, to read what the model thought.">
<g />

```tsx
import { Reasoning } from "@/components/ui/reasoning";

export default function ReasoningExample() {
  return (
    <div className="flex flex-col gap-1">
      <Reasoning
        status="complete"
        durationSeconds={4}
        text="The user wants the **cheapest** route. Compare the three fares, then check the layovers."
      />
      <Reasoning
        status="running"
        text="Two of the flights leave before 7 a.m., so rank the third one first."
      />
    </div>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Reasoning
├── ReasoningTrigger
│   ├── ReasoningIcon
│   └── ReasoningTitle
└── ReasoningContent
```

`Reasoning` 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. `ReasoningTitle` shows the title, or its own children, and `ReasoningContent` renders `text` as [Markdown](./markdown.mdx), or its own children. When you compose the parts yourself, keep `ReasoningTitle` or pass `label`: the title names the reasoning and is what it announces.

## Usage [#usage]

### Streaming Thoughts [#streaming-thoughts]

Pass the thoughts so far as `text`, and set `status` as the model works. While the status is `running`, the title shimmers, the content stays open and `text` renders as streaming Markdown: each chunk parses only the blocks it changed, and the trigger above never moves.

```tsx
<Reasoning status={isThinking ? "running" : "complete"} durationSeconds={seconds} text={reasoningText} />
```

### Summary [#summary]

When the status turns `complete`, the title becomes "Thought for N s", from `durationSeconds` rounded to the nearest second and never less than 1, or "Thought" without one. The content closes on its own, unless someone opened or closed it while the model thought. Pass `label` to replace the title with your own words.

A reasoning that goes straight from `pending` to `complete`, like a cached answer, stays closed.

### Announcements [#announcements]

When the model finishes, screen readers hear the title, like "Thought for 4 s", once. A failure says "Thinking failed" and a cancelled run "Thinking stopped". Streamed text is quiet. On Web Components, set `duration-seconds` before `status`, so the announced summary has the duration.

### Motion [#motion]

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

## API Reference [#api-reference]

### ReasoningOptions

| 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"` |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                   |
| `text?`            | `string \| undefined`                                                                  | The model's thoughts so far, as markdown. Appending parses only the blocks that changed.                                                                                                       |
| `label?`           | `string \| undefined`                                                                  | Replaces the title, "Thinking" or "Thought for N s", and is announced on completion, so name the outcome in it. A failure or a stop still announces "Thinking failed" or "Thinking stopped".   |
| `durationSeconds?` | `number \| undefined`                                                                  | How long the model thought, shown as "Thought for N s" once done. Set it with or before `status`, so the summary announced on completion has it. Also written as `--kind-step-duration`.       |

### Agent [#agent]

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

### ReasoningAgentActions

| 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-reasoning>`, each prop is a kebab-case attribute, so `durationSeconds` is `duration-seconds`, and `onOpenChange` fires `openchange`. The element fills in its parts when it has no children, writes its title into an empty `<kind-reasoning-title>`, and writes `text` into a `<kind-markdown>` in its content.
</Caption>