---
title: "Prompt input"
description: "The text box of an AI chat: a growing textarea with attachments, tools and a send button that turns into stop, plus @ mentions and / commands."
url: "https://susonwaiba.github.io/htmx-ui/docs/components/prompt-input"
section: "Components"
---
# Prompt input
The text box of an AI chat: a growing textarea with attachments, tools and a send button that turns into stop, plus @ mentions and / commands.
```html
```
A prompt input is where the user writes to an AI model. It looks like one big input, but holds a textarea that grows with the text, a toolbar for attachments, tools and the model, and a send button that turns into a stop button while the answer is on its way. Typing `@` or `/` opens a list of people, files or commands to insert. The demo posts to a mock endpoint that is part of the dev server, so it only answers on a running site, not on a static host.
## Markup
- The box is a `
```
## Actions
Anything can go in `.prompt-input-tools`: small ghost buttons (`btn btn-ghost btn-icon btn-sm`), [toggles](https://susonwaiba.github.io/htmx-ui/docs/components/toggle) with `aria-pressed` for tools the model may use, a [select](https://susonwaiba.github.io/htmx-ui/docs/components/select) for the model with `class="prompt-input-select"`, `size="sm"` and `side="top"` (it looks like a ghost button until hovered, and opens above the box), [tooltips](https://susonwaiba.github.io/htmx-ui/docs/components/tooltip) on icon buttons, or a [dropdown](https://susonwaiba.github.io/htmx-ui/docs/components/dropdown). Give them `type="button"` so they don't send the form.
The submit button is disabled while the box is empty: no text (spaces don't count) and no [attachment](https://susonwaiba.github.io/htmx-ui/docs/components/attachment) inside. Put attachments in `.prompt-input-attachments`, above the text; the button follows as they are added and removed.
```html
```
Remove the attachment and the send button disables itself; type something and it comes back.
## Mentions and commands
A `.prompt-input-menu` with `data-prompt-input-menu="@"` and `role="listbox"` (and an `aria-label`) holds suggestions for one trigger character. Typing the trigger opens it above the box, and the text typed after the trigger filters it: an option matches on its `data-value`, its text and its `data-keywords`, ignoring case and accents. Each option is a `.prompt-input-option` with `role="option"` and a `data-value`; inside, anything goes: an icon or an [avatar](https://susonwaiba.github.io/htmx-ui/docs/components/avatar), a `.prompt-input-option-label` and a `.prompt-input-option-description`. A `.prompt-input-empty` with `data-prompt-input-empty` shows when nothing matches; without one the menu closes instead.
- **Where a trigger counts.** `@` (and any other character) opens its menu at the start of the text or after a space, so an email address doesn't. `/` only counts as the very first character of the text, as in most chat apps, so a URL or a fraction never opens it. Set `data-prompt-input-position="start"` or `"word"` on a menu to choose.
- **Picking** replaces the trigger and the query with the trigger, the option's `data-value` and a space (`@grace `, `/summarize `). Give an option `data-insert` to insert other text.
- **Groups:** wrap options in a `.prompt-input-group` with `role="group"`, headed by a `.prompt-input-label` it names through `aria-labelledby`. A group with nothing left in it hides.
- Menus open above the box, as wide as it, or below it when there is no room above. Add `.prompt-input-menu-down` to always open below.
```html
```
The folders insert `@src/` with no space after it (`data-insert`), ready for a path. The textarea becomes a `role="combobox"` (still `aria-multiline`) whose `aria-expanded`, `aria-controls` and `aria-activedescendant` follow the open menu, so screen readers announce the highlighted suggestion while focus stays in the text.
## Suggestions from the server
For a list too long to put in the page, add `data-prompt-input-src` to the menu and leave it empty. As the user types, the behaviour fetches `src?q=&trigger=@` (debounced: 150 ms, or `data-prompt-input-delay`; older answers are dropped), and the returned option markup replaces the menu's content. The server does the filtering. Return a `.prompt-input-empty` with `data-prompt-input-empty` to say nothing matched, or nothing to close the menu. The request carries `HX-Request: true`, so a route shared with htmx can return fragments as usual.
```html
```
The endpoint answers with plain option markup, the same as inline options: `
…
`. This demo's endpoint is part of the dev server, so it only answers on a running site, not on a static host.
## With htmx
Put `hx-post` on the form. `Enter` sends it with `requestSubmit()`, so htmx, native validation (`required`, `maxlength`) and your own `submit` listeners all run, and every field in the form goes along: the prompt, the model select, hidden inputs for toggles or attachment ids.
- While the form's request runs (from htmx's `htmx:before:request` to `htmx:finally:request`), the form has `data-state="loading"`. `htmx:finally:request` is used rather than `htmx:after:request` because htmx 4 also fires it after an error or an abort.
- In the loading state the submit button shows the stop square, is labelled "Stop" (`data-prompt-input-stop-label` on the button changes that), and `Enter` sends nothing.
- Clicking stop fires `prompt-input:stop` on the form, then sends htmx an `htmx:abort`, which cancels the request. Call `preventDefault()` on the event to stop the answer your own way instead (say, by telling a streaming server to stop).
- When the response is under 400 the textarea is cleared. An error keeps the text, so the user can try again. Add `data-prompt-input-clear="false"` to keep it always.
Streaming the answer (server-sent events, or a request that appends as it goes) is the server's business; the prompt input only needs the request's start and end. An app that sends prompts without htmx sets and removes `data-state="loading"` on the form itself; the button follows, and stop then clears the state after firing its event.
```html A stop that tells the server
```
## Keyboard
| Key | Action |
| --- | --- |
| `Enter` | Send the prompt (nothing while empty or loading) |
| `Shift` `Enter` | New line |
| `@`, `/` | Open that trigger's menu; the text after it filters the menu |
| `↓` `↑` | Menu open: move the highlight (wrapping round) |
| `Enter`, `Tab` | Menu open: insert the highlighted suggestion |
| `Esc` | Close the menu; it stays closed until the next trigger |
The first suggestion is highlighted as soon as a menu opens, so `Enter` takes it. While an IME composition is in progress, `Enter` is left to the IME.
## Events
Both events bubble from the form.
- `prompt-input:select`, after a suggestion is inserted, with `detail` `{ trigger, value, option, query }`: the trigger character, the option's value, the option element and the text that was typed after the trigger.
- `prompt-input:stop`, when the stop button is clicked. Cancelable: `preventDefault()` keeps the request running and the loading state on.
Picks are inserted as plain text, which the server can read straight from the prompt. To show them as chips instead, or to send the picked ids, listen for `prompt-input:select`:
```js app.js
document.addEventListener("prompt-input:select", (e) => {
const { trigger, value } = e.detail;
if (trigger !== "@") return;
// Send the mentioned ids with the prompt, as hidden fields in the form.
const input = Object.assign(document.createElement("input"), { type: "hidden", name: "mentions", value });
e.target.append(input);
});
```
## Nunjucks macro
The `prompt_input` macro writes the form, the textarea, the toolbar with its submit button and the menus. The call body goes in the toolbar. `mentions` and `commands` take options as `{value, label, description, keywords, icon}`; `mentions_src` and `commands_src` fetch them from the server instead.
```html
```
```jinja page.html
{% from "components/prompt-input/prompt-input.html" import prompt_input %}
{% call prompt_input(action="/chat", target="#messages", swap="beforeend",
mentions=json("data/people.json"), commands_src="/chat/commands") %}
{% endcall %}
```
Other options: `name`, `placeholder`, `label`, `rows`, `maxlength` and `required` for the textarea; `attachments=true` for an empty attachments row (id `-attachments`); `clear=false`; `submit_label` and `stop_label`; `id`, `class` and `attrs` for the form.
## Reference
| Class / attribute | Description |
| --- | --- |
| `.prompt-input` | The box: a