# Prompt Input

An auto-resizing chat input with attach and send buttons.

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

## Install

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

## Import

```tsx
import { PromptInput, ModelCompareMenu, PromptProjects } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

export function Composer() {
  const [value, setValue] = useState("")
  return (
    <PromptInput
      value={value}
      onValueChange={setValue}
      onSubmit={() => {
        // send `value` to your model, then clear the box
        setValue("")
      }}
    />
  )
}
```

Expected result: You should see a bordered box with the placeholder Ask anything..., an attach button and a dimmed round Send button. Type a word and Send turns solid; press Enter and the box empties.

## When to use

### Use Prompt Input for

- The message box of a chat, an assistant or an agent where the user writes a prompt and sends it
- A prompt that may run over several lines, with attachments, tools or a choice of model
- A turn that can be stopped while the reply is generated

### Use something else

- [Textarea](https://wunderui.com/components/textarea) for a multi-line field in a form, with no send button
- [Input](https://wunderui.com/components/input) for a short single-line value such as a search term or a name
- [Rich Text Editor](https://wunderui.com/components/rich-text-editor) for formatted documents; a chat composer never gets a formatting toolbar

## Keyboard

The field is a native textarea and the controls are native buttons, so the browser provides typing, focus and activation.

| Key | Action |
|---|---|
| `Enter` | Sends. It calls `onSubmit` when the text is not empty and no reply is generating, and does nothing otherwise. The Enter that confirms an IME composition is not a send. |
| `Shift+Enter` | Adds a new line. The field grows with it. |
| `Tab` or `Shift+Tab` | Moves focus through the field, Attach files, your tools, the model chip and Send or Stop, in that order. Send stays a tab stop while it is `aria-disabled`, so its tooltip can be read. |
| `Enter` or `Space` | Presses the focused button: attaches, runs a tool, opens the model list, sends or stops. |
| `Escape` | Closes the model popover and returns focus to the chip. |

Every control is a tab stop and the box has no arrow-key navigation of its own (the model list has its own). Escape closes the model popover, and when disabled nothing in the box takes focus.

## Behavior

What the box does with the text, the send keys, the reply state and the focus.

- **Controlled text:** The value and its change handler are required. The box keeps no text of its own, so clear the field in the submit handler after you have read the value.
- **When Send works:** Send, by key or by click, only works when the trimmed text is not empty and no reply is generating. Spaces alone count as empty.
- **Send keys:** Enter sends and Shift+Enter adds a line. An Enter pressed while an IME composition is open confirms the composition instead, so Japanese, Chinese and Korean input work.
- **Send that is not ready:** While Send is not ready it is aria-disabled, so it stays in the tab order, is dimmed to 40 % and shows a tooltip: Type a message first, or Wait for the reply to finish.
- **Generating:** Set loading while the reply runs; with a stop handler, Send is replaced by a Stop button. The field stays editable so the next prompt can be written, but it is not sent until loading ends.
- **Disabled:** Disabled turns the whole box off: the field and all buttons are dimmed to 40 % and out of the tab order, and nothing can be sent. Buttons in the tools slot are yours to disable.
- **Growth:** The field is one line at rest and grows with its content up to 160 px, then scrolls. The height is set directly and is not animated.
- **Names:** The placeholder is not a name: the field is named by its aria-label, Message by default. The buttons are named Attach files, Send, Stop generating and Model followed by the name.
- **Attachments:** The box holds no files. The paperclip only calls the attach handler; keep the files in your state and show them with Chat Attachment above the field.
- **Focus:** The box draws the focus ring (indigo border and 2 px ring) while the text field has focus. Each button inside draws its own ring when it takes keyboard focus.
- **Motion:** The box changes its border and background with a quick colour transition. The model chevron turns 180 degrees when the list opens.
- **Reduced motion:** No motion carries meaning here. The growth and the swap from Send to Stop are instant, so reduced motion changes nothing.
- **While a request is blocked:** Disable the box when the person cannot write at all, such as a closed conversation, a used-up quota or an approval pending. Use loading while a reply is generated, so the next prompt can be written.

## Anatomy

- `PromptInput`: A 16 px bordered box with 12 px padding that holds the field and the toolbar. It draws the focus ring while the text field has focus and looks dimmed when disabled.
- `Text field`: A textarea named by an aria-label, Message by default. It starts at one line, grows to 160 px, then scrolls, and is dimmed to 40 % when disabled.
- `Attach button`: An icon button named Attach files that only calls the attach handler; opening the file picker is yours. You can hide it, and disabling the box turns it off.
- `Tools`: A slot after the attach button for your own icon buttons, such as web search or a link. Give each one an aria-label. The attach button and your tools sit in this slot: their icons are grey at rest and black on hover, focus and when pressed. A button with `data-tinted` keeps its own colour.
- `Model chip`: A Model Picker pill that opens a popover with the models. It exists only when you pass models and is named Model followed by the current name.
- `Send button`: A round primary icon button named Send, aria-disabled while the text is empty or a reply is generating. With loading and a stop handler it becomes the Stop generating button.
- `Mentions`
- `Mention`
- `Suggestion`
- `Attachments`: A wrapping row above the text field for Chat Attachment items, shown when you pass `attachments`.
- `Chips`: A wrapping row in the footer after the tools and the model chip for a Model Compare Menu or removable Record Chip tags, shown when you pass `chips`.

## Best practices

### When to use

- Use a Prompt Input for chat and agent prompts. For a short single-line field use Input; for a multi-line field in a form use Textarea.

### Do

- Send in the submit handler and clear the value there. The component skips an empty prompt and a send while generating, so you need no second check.
- While a reply runs, pass loading and a stop handler together, so the person can always stop it. Without the stop handler, Send only turns off.
- When more than one box is on a screen, set an aria-label that names the conversation, such as Message to the planner.
- Disable the box when writing is not possible, such as a closed conversation or an exhausted quota, and say why next to it. While a reply is generated, use loading, not disabled.
- Give every icon button in the tools slot an aria-label. An icon alone is not a name.
- Show an example prompt with suggestion (Tab takes it) and mentions with the mentions prop instead of capturing keys around the box; use onKeyDown and textareaProps for anything else.

### Don't

- Don't build a composer with a rich text toolbar (bold, italic, underline). A prompt is plain text; formatting belongs in the reply, not in the box.
- Don't send on blur or on every change. Sending is the person's decision: Enter or the Send button.
- Don't use disabled to show that a reply is generating. The person could not write the next prompt meanwhile; use loading with a stop handler instead.

## API reference

### PromptInput

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: string) => void |  | Called with the new text on every change, including the new lines added with Shift+Enter. |
| value* | string |  | The text of the field. The box is controlled, so keep it in state. |
| aria-label | string |  | The accessible name of the text field, `Message` by default. Set one that fits the screen. |
| attach | boolean | true | Set to false to hide the Attach files button. |
| attachments | React.ReactNode |  | A row above the text field for Chat Attachment items (each with its own remove button). It wraps onto more lines and never clips. Nothing renders when it is empty. |
| chips | React.ReactNode |  | Chips in the footer after the tools and the model chip: a Model Compare Menu ("4 models") or removable tags (Record Chip with `onRemove`). They wrap below the tools on narrow boxes. |
| className | string |  | Extra classes for the box, for example `max-w-2xl` to set its width. |
| defaultModel | string |  | The id of the model the chip starts on when you do not control it. Without it the first model is used. |
| disabled | boolean | false | Turns the whole box off: the field, Attach files, the model chip and Send or Stop. Nothing is sent. Buttons in `tools` are not affected. |
| loading | boolean |  | A reply is being generated. Enter and Send do not send; with `onStop` the Send button is replaced by Stop. |
| mentions | PromptMentions |  | Mentions: typing the trigger ("@") lists the items above the box (below it, or scrolling, where the space above is too small); ↑ ↓ move, Enter or Tab pick, Esc closes. |
| model | string |  | The id of the chosen model, for a controlled chip. |
| models | ModelOption[] |  | The models of the chip: each has an `id` and a `name`, and optionally a `description`, a `tag` and an `icon`. The chip is shown only when the list is not empty. |
| onAttach | () => void |  | Called by the Attach files button. Open your file picker here; the box does not read or show files. |
| onKeyDown | React.KeyboardEventHandler<HTMLTextAreaElement> |  | Keys on the text field, before the box handles them (Enter sends, Tab takes the suggestion, the mention keys). Call `e.preventDefault()` to stop the built-in handling of that key. |
| onModelChange | (id: string) => void |  | Called with the id of the model the person picks. |
| onStop | () => void |  | Called by the Stop button. It shows only while `loading` is true. Abort the request here and set `loading` to false. |
| onSubmit | () => void |  | Called by Enter and by the Send button when the text is not empty and no reply is generating. Read `value` here, then clear it. |
| onSuggestionAccept | (text: string) => void |  | Called after Tab took the suggestion over. |
| placeholder | string | "Ask anything..." | The hint shown while the field is empty. It is not the accessible name. |
| suggestion | string |  | A suggested prompt as ghost text: in an empty box (in place of the placeholder), or as the rest of what was typed while the suggestion starts with it. Tab takes it over. |
| textareaProps | Omit<React.ComponentProps<"textarea">, "value" \| "defaultValue" \| "onChange" \| "disabled"> |  | Extra props for the text field (`ref`, `id`, `autoFocus`, `name`, `onFocus` …); `value`, `onChange` and `disabled` stay with the box. |
| tools | React.ReactNode |  | Extra buttons after Attach files, such as web search or a link. Use icon buttons with an `aria-label`. |

### ModelCompareMenu

| Prop | Type | Default |
|---|---|---|
| models* | ModelOption[] |  |
| onValueChange* | (ids: string[]) => void |  |
| value* | string[] |  |
| className | string |  |
| disabled | boolean | false |
| label | string | "Answer with" |
| primaryHint | string | "The chat's model, always answers" |

### PromptProjects

| Prop | Type | Default | Description |
|---|---|---|---|
| projects* | PromptProject[] |  |  |
| aria-label | string |  | Accessible name of the group (required when no labelledBy). |
| aria-labelledby | string |  |  |
| className | string |  |  |
| clearable | boolean | true | Clicking the chosen card again clears the choice. Default true. |
| defaultValue | string \| null |  |  |
| onValueChange | (id: string \| null) => void |  |  |
| value | string \| null |  |  |

## Examples

### Toolbar: attach and send, send only, tools, a model chip

### State: empty, ready, generating with Stop, generating without Stop, disabled

### Text length: one line, three lines, past the maximum height

### Attachments and chips: a row above the field, chips after the tools

## In context

### Simple: a text field, attach and send

The smallest box: controlled text, an Attach files button and a round Send button. Press Enter to send, Shift+Enter for a new line.

### With attachments: files stand above the field

The paperclip opens your file picker. Pass the chosen files as `attachments` (Chat Attachment items) and the box shows them above the field, wrapping onto more lines; remove one with its ×, and clear them with the text after Send.

### With tags and suggestions: "4 models", "Design system ×" and prompt chips

`chips` holds a Model Compare Menu (the chip reads "N models" in an orange tint once you tick more than one) and removable tags (Record Chip). Prompt Suggestion chips below the box fill the field; they wrap onto more lines.

### Start in a project: radio cards under the box

Prompt Projects are radio cards with an icon tile, title, description and meta, and a check at the top right. Arrow keys move and choose; click the chosen card to clear it. Three columns, one on a phone, equal heights.

### Send, stream and stop: the box controls the whole turn

Type a question and press Enter. The loader shows first, the words stream in, and Send becomes Stop while the reply runs; Stop keeps what has arrived, and Shift+Enter adds a line.

### Model chip: the choice stays with the caller

The chip opens a popover with the models and closes when you pick one. Control the choice yourself with a value and change handler, or let the chip keep it with a default.

### Suggestion and mentions: Tab takes the example, @ lists teammates

An empty box shows `suggestion` as ghost text in place of the placeholder; Tab takes it over. With `mentions`, typing @ lists the items above the box (below it when the space above is too small, scrolling when neither side holds the list): the arrow keys move, Enter or Tab inserts the name, Escape closes the list. `onKeyDown` runs before these keys and `textareaProps` reaches the text field (a ref to focus it).

## For AI agents

`get_component("prompt-input")`

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