# Prompt Mode Switch

What the agent may do with the next prompt — answer, act or edit — with the send keys underneath.

- Category: AI & Agents
- Page: https://wunderui.com/components/prompt-mode-switch
- Tier: Core and Pro

## Install

Prompt Mode Switch ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { PromptModeSwitch } from "@wunderui/react"

export function Composer() {
  const [mode, setMode] = useState<"ask" | "agent" | "edit">("ask")

  return <PromptModeSwitch value={mode} onValueChange={setMode} />
}
```

Expected result: You should see a pill switch with Ask pressed, the line Answers questions, and the send keys underneath. Press Agent and the line changes to Plans and runs tools.

## When to use

### Use Prompt Mode Switch for

- A prompt box where the same text can only answer, run tools or edit files
- A chat or an agent with a safe default and a person who widens its reach on purpose
- Any place where the consequence of a prompt depends on a choice made before it is sent

### Use something else

- [Model Picker](https://wunderui.com/components/model-picker) for choosing which model answers
- [Model Select](https://wunderui.com/components/model-select) for choosing the model and how hard it thinks, with its price
- [Tool Permission Row](https://wunderui.com/components/tool-permission-row) for a lasting Allow, Ask or Deny setting for one tool
- [Segment](https://wunderui.com/components/segment) for a switch with your own options, labels and icons

## Keyboard

The three options are a tab group: one tab stop, and the arrow keys move inside it.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the group on the pressed option and out of it again. The two other options are skipped. |
| `→` or `←` | Moves focus to the next or previous option and selects it at once, so `onValueChange` is called on every press. After Edit comes Ask, and before Ask comes Edit. |
| `Home` or `End` | Moves focus to the first option (Ask) or the last (Edit) and selects it. |
| `Enter` or `Space` | Presses the focused option. On the pressed option nothing changes. |

The options are tabs, so a screen reader says tab and selected, not radio button. Up and Down do nothing, and a disabled mode does not exist.

## Behavior

What the switch does with the mode, the hint and the keys, and what it leaves to you.

- **Selection follows focus:** An arrow key moves focus and selects in one step, and the change handler is called each time, so a key press that only passes Agent still reports Agent. Read the mode when the prompt is sent.
- **It only reports:** The switch does not stop a run, ask for a confirmation or store the mode. What a mode lets the agent do is your rule; show it in words near the switch.
- **Controlled or not:** Pass a value and the switch shows exactly that; if your state does not change, the pressed option does not move. Without a value the switch keeps the mode itself, starting at ask.
- **The hint:** The line under the switch is a polite live region, so a change is read out. Custom hints replace all three lines and need a text for every mode.
- **The send keys:** The two key hints are plain text: the switch does not listen to Enter, Prompt Input does. Turn the line off where the box sends differently.
- **Three fixed modes:** The options are Ask, Agent and Edit. You cannot hide, disable, rename or add a mode, and there are no icons.
- **Failure: a mode that is not allowed:** A mode cannot be disabled, so in the handler keep the old value, show the reason next to the switch with an Alert and offer the fix. The Examples tab shows Agent without a connected workspace.
- **Layout:** A column that aligns to the start: switch, hint, send keys. The hint and the keys wrap on a narrow screen; the switch keeps its width.
- **Motion:** The options change colour quickly and nothing slides: the pressed pill appears in place. Nothing else moves.
- **Reduced motion:** With reduced motion the colour change still runs; there is no transform to remove.

## Anatomy

- `PromptModeSwitch`: A column with an 8 px gap that carries the chosen mode (ask, agent or edit), which you can style or test against. Beside its own props it takes only a class name.
- `Segment`: The pill switch: a small segmented control named Prompt mode, with the options Ask, Agent and Edit. It is a tab list, so a screen reader announces three tabs, not radio buttons.
- `Selected option`: The pressed option: a white pill marked selected, and the only tab stop of the group. The other two are reached with Arrow keys.
- `Hint`: One 12 px line about the chosen mode, in a polite live region so a change is read out. It comes from the hints and is always shown.
- `Send keys`: A line of text with two Kbd badges: ↵ to send and ⇧↵ for a new line. It is a legend only and the switch does not listen to Enter, so you can hide it.

## Best practices

### When to use

- Use PromptModeSwitch next to a prompt box when the same text can mean different permissions for the agent. For the choice of model use Model Picker; for how hard it thinks use Model Select.

### Do

- Read the mode when the prompt is sent, not in the change handler. Arrow keys select at every step, so a keyboard user passes through Agent on the way from Ask to Edit.
- Write each hint as the consequence, not the label: Edits the selected files in place tells a person what will happen, Edit mode does not.
- Keep ask as the default. The mode with the least reach is the safe one to start in; a person widens it on purpose.
- Show the mode where the run is shown (for example next to Agent Status), so the mode a run started in is still visible once the switch has moved on.
- When a mode is not allowed, keep the old value, say why next to the switch and offer the way out, such as connecting a workspace. The switch has no disabled option.

### Don't

- Don't let a change of the switch stop, restart or re-plan a run that is going. It applies to the next prompt; say so in a line of text.
- Don't start an agent, send a request or delete anything in the change handler. A key press that is only passing through can call it.
- Don't rely on the look of the pressed option alone. The state is exposed as selected and the hint names the mode in words.

## API reference

### PromptModeSwitch

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the column that holds the switch and the two lines. |
| defaultValue | "edit" \| "agent" \| "ask" | "ask" | The mode that starts pressed when you do not pass `value`. `ask` by default. |
| hints | Record<PromptMode, string> | MODE_HINT | The line under the switch for each mode, as `{ ask, agent, edit }`. All three keys are needed. The default lines are `Answers questions. Changes nothing.`, `Plans and runs tools. Asks before risky steps.` and `Edits the selected files in place.` |
| onValueChange | (mode: PromptMode) => void |  | Called with the new mode on every click and every arrow key, also when the key only passes the mode. Read the mode when the prompt is sent, not here. |
| showKeys | boolean | true | Shows the line `↵ to send ⇧↵ for a new line`. `true` by default. It is text only. |
| value | "edit" \| "agent" \| "ask" |  | The mode that is pressed, for a controlled switch: `ask`, `agent` or `edit`. If you do not change it in `onValueChange`, the switch stays where it was. |

## Examples

### Mode: ask, agent and edit, and what each one lets the agent do

### Hints: the default line, your own words, no send keys

### Control: the switch keeps the mode, or your state does

## In context

### The mode travels with the prompt: it is read when the prompt is sent

Pick a mode and press Enter. The line under the box says what the app did in that mode; the switch changes nothing itself, so the app reads the mode when the prompt is sent.

### A run is going: the new mode applies to the next prompt

Start a run, then pick another mode. The run keeps the mode it started in and the line says so, because changing the switch never stops, restarts or re-plans a running run.

### A mode that is not allowed yet: the switch stays, the reason and the way out stand next to it

Choose Agent without a connected workspace. The switch has no disabled option, so the handler keeps the old value and the warning says why and offers the fix; after Connect workspace, Agent is on.

### Arrow keys switch at every step: read the mode when you send

Tab to the switch and press the right arrow twice. The mode changes on every press, so the change handler hears Agent on the way to Edit; apply the mode when the prompt is sent, not in the handler.

## For AI agents

`get_component("prompt-mode-switch")`

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