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

Use reasoning effort beside a [Model Selector](./model-selector.mdx) when the model can trade speed for more thinking. It's a row of levels, Low, Medium and High by default, with a mark that slides to the chosen one.

<Example caption="Press High, or focus the levels and press the arrow keys. The mark slides to the level you choose.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { ReasoningEffort } from "@/components/ui/reasoning-effort";

export default function ReasoningEffortExample() {
  const [effort, setEffort] = useState<string | null>("medium");
  return <ReasoningEffort value={effort} onValueChange={setEffort} />;
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
ReasoningEffort
├── ReasoningEffortIndicator
└── ReasoningEffortItem
```

`ReasoningEffort` is a group named by its `label` that holds UI SDK's Segmented Control, a radio group with one Tab stop. `ReasoningEffortIndicator` is the mark behind the chosen level, and each `ReasoningEffortItem` is a level.

## Usage [#usage]

### Levels [#levels]

Pass `levels` to name your own, each with the `value` the host receives and the `label` a person reads, from least to most effort.

```tsx
<ReasoningEffort
  levels={[
    { value: "minimal", label: "Minimal" },
    { value: "low", label: "Low" },
    { value: "high", label: "High" },
  ]}
  defaultValue="low"
  onValueChange={(effort) => setEffort(effort)}
/>
```

Pass `value` and `onValueChange` to control the chosen level, or `defaultValue` to start with one. `onValueChange` gets the level's `value`, with the reason `input-change` when a person chose it, or `imperative` from `setValue`. Pass `disabled` while the model can't change its effort.

### Keyboard [#keyboard]

Tab moves to the chosen level. The arrow keys move to the next or previous level and choose it, and Space chooses the focused one.

### Motion [#motion]

The mark slides to the chosen level. Under `prefers-reduced-motion`, or with `motion="reduced"`, it doesn't move: the chosen level fills in over 120 ms. With `motion="none"`, it changes at once.

## API Reference [#api-reference]

### ReasoningEffortOptions

| Prop             | Type                                                                                                       | Description                                                                                                                                                       |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `levels?`        | `ReasoningEffortLevel[] \| undefined`                                                                      | The levels, from least to most effort. Default: `Low, Medium and High`                                                                                            |
| `value?`         | `string \| null \| undefined`                                                                              | The chosen level's value. Passing it controls it: change it in `onValueChange`.                                                                                   |
| `defaultValue?`  | `string \| null \| undefined`                                                                              | The chosen level's value at first, when `value` isn't passed. Default: `null`                                                                                     |
| `onValueChange?` | `((value: string \| null, details: ChangeDetails<ReasoningEffortValueChangeReason>) => void) \| undefined` | Called when a person or `setValue` chooses a level, with why.                                                                                                     |
| `label?`         | `string \| undefined`                                                                                      | Names the control. Default: `"Reasoning effort"`                                                                                                                  |
| `disabled?`      | `boolean \| undefined`                                                                                     | Whether the levels can't be focused or chosen. Default: `false`                                                                                                   |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                                            | How the mark behind the chosen level moves: it slides at full motion and fades under reduced motion. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"` |

### Agent [#agent]

An agent connected with `createAgent` finds the control by its label and reads the chosen level. Its `setValue` takes a level's `value` or its label, the same as a person choosing it, and refuses a level that isn't listed. It needs no person to confirm.

### ReasoningEffortAgentActions

| Prop       | Type                         | Description                                                                                   |
| ---------- | ---------------------------- | --------------------------------------------------------------------------------------------- |
| `setValue` | `(value: string) => boolean` | Chooses a level, as a person would. Returns `false` for an unknown level or a refused change. |

<Caption>
Runs in React and Web Components. On `<kind-reasoning-effort>`, set `levels` and `value` as properties, and listen for `effortchange`, with the level's `value` as `event.detail.value`. The element fills in its levels when it has no children.
</Caption>