# Composer (/docs/agent-ui/components/composer)

Use a composer where someone writes a prompt. It holds the text, the mentions and commands typed into it, and the attached files, and sends them together as one draft.

<Example caption="Type @ or / to pick a suggestion, then press Enter to send. While it sends, press Stop to end it early.">
<Basic />

```tsx
"use client";
import { useRef } from "react";
import {
  Composer,
  ComposerAttach,
  ComposerAttachments,
  ComposerInput,
  ComposerStop,
  ComposerSubmit,
  ComposerTriggerMenu,
} from "@/components/ui/composer";

const mentions = [
  { value: "src/client.ts", label: "client.ts", description: "src" },
  { value: "src/retry.ts", label: "retry.ts", description: "src" },
];

const commands = [
  { value: "explain", label: "explain", description: "Explain the selected code" },
  { value: "test", label: "test", description: "Write tests" },
];

export default function ComposerExample() {
  const finish = useRef<() => void>(undefined);
  const send = () =>
    new Promise<void>((resolve) => {
      finish.current = resolve;
      setTimeout(resolve, 3000);
    });

  return (
    <Composer
      aria-label="Message"
      mentions={mentions}
      commands={commands}
      onSubmit={send}
      onStop={() => finish.current?.()}
    >
      <ComposerAttachments />
      <ComposerInput aria-label="Prompt" placeholder="Ask anything. Type @ to mention, / for commands">
        <ComposerTriggerMenu />
      </ComposerInput>
      <ComposerAttach />
      <ComposerSubmit />
      <ComposerStop />
    </Composer>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Composer
├── ComposerAttachments
├── ComposerInput
│   └── ComposerTriggerMenu
├── ComposerAttach
├── ComposerSubmit
└── ComposerStop
```

The composer renders a form, and everything inside it takes dropped files. `ComposerAttachments` shows the attached files as [Attachments](./attachments.mdx), and stays empty until there are some. `ComposerInput` is the prompt, and `ComposerTriggerMenu` inside it shows the suggestions. `ComposerAttach` opens the file picker. `ComposerSubmit` and `ComposerStop` are Send and Stop, which take turns in the same place. Name the composer and its input with `aria-label`.

## Usage [#usage]

### Sending [#sending]

Enter sends the draft to `onSubmit`, and Shift+Enter starts a new line. Pass `submitOn="mod-enter"` to send with Ctrl+Enter or Cmd+Enter instead, so Enter starts a new line. A draft with only whitespace doesn't send.

The draft has `text`, `tokens` and `attachments`. In `text`, each mention or command reads `[@label](kind:value)`, and `tokens` lists them in order:

```tsx
<Composer
  aria-label="Message"
  onSubmit={(draft) => chat.send(draft.text, draft.attachments)}
>
```

Return a promise from `onSubmit` to keep the composer pending: Send is locked, and screen readers hear "Sending". When the promise resolves, the draft clears, unless someone kept typing in the meantime. When it rejects, the draft stays and screen readers hear "Message not sent".

To own the draft, pass `value` and `onValueChange`. Cancel the change's `details` to refuse an edit, and the prompt goes back to the draft.

### Stop [#stop]

Pass `onStop` to show Stop in Send's place while a submission is pending, so someone can end the agent's reply. Settle the `onSubmit` promise once it stops, and Send comes back. When the button that had focus leaves, focus moves to the one that took its place.

### Mentions and Commands [#mentions-and-commands]

Pass `mentions` to suggest them after `@`, and `commands` to suggest them after `/` at the start of a line. Each item has a `value`, a `label` and an optional `description`. Choosing one inserts it into the prompt as a token, and Escape closes the suggestions.

### Files [#files]

Files attach when someone presses `ComposerAttach`, drops them on the composer, or pastes them while it has focus. Pass `accept` and `maxSize` to limit them. A file they rule out still attaches, with its error on the chip, so the person sees why; it has an `error` in the draft, and a draft with only those files doesn't send. Each chip has a remove button, and Delete or Backspace removes the focused one.

### History [#history]

Pass earlier prompts as `history`, oldest first. ArrowUp at the start of the prompt brings back the previous one, and ArrowDown moves forward again, back to what was being typed.

## API Reference [#api-reference]

### ComposerOptions

| Prop             | Type                                                                                               | Description                                                                                                                                                                                                 |
| ---------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value?`         | `ComposerDraft \| undefined`                                                                       | The draft. Passing it controls it: change it in `onValueChange`. Don't pass it with `defaultValue`.                                                                                                         |
| `defaultValue?`  | `ComposerDraft \| undefined`                                                                       | The draft at first, when `value` isn't passed.                                                                                                                                                              |
| `onValueChange?` | `((value: ComposerDraft, details: ChangeDetails<ComposerValueChangeReason>) => void) \| undefined` | Called when the draft changes, with what caused it. Cancel `details` to refuse the change.                                                                                                                  |
| `onSubmit?`      | `((draft: ComposerDraft) => unknown) \| undefined`                                                 | Called with the draft when it's sent. Return a promise to keep the composer pending: resolving clears the draft unless it changed meanwhile, and rejecting keeps it. Otherwise the draft clears right away. |
| `onStop?`        | `(() => void) \| undefined`                                                                        | Called when Stop is pressed. While it's set, Stop takes Send's place during a pending submission.                                                                                                           |
| `submitOn?`      | `"enter" \| "mod-enter"`                                                                           | Which keys send. With `"enter"`, Shift+Enter starts a new line; with `"mod-enter"`, Enter does. Default: `"enter"`                                                                                          |
| `mentions?`      | `readonly ComposerTriggerItem[] \| undefined`                                                      | What typing `@` suggests.                                                                                                                                                                                   |
| `commands?`      | `readonly ComposerTriggerItem[] \| undefined`                                                      | What typing `/` at the start of a line suggests.                                                                                                                                                            |
| `accept?`        | `string \| undefined`                                                                              | The file types to accept, like the `accept` attribute. Other files attach with an error.                                                                                                                    |
| `maxSize?`       | `number \| undefined`                                                                              | The largest file to accept, in bytes. Larger files attach with an error.                                                                                                                                    |
| `history?`       | `readonly string[] \| undefined`                                                                   | Earlier prompts, oldest first, that ArrowUp brings back.                                                                                                                                                    |
| `disabled?`      | `boolean \| undefined`                                                                             | Stops editing, attaching, sending and every agent action. Default: `false`                                                                                                                                  |
| `agentConfirm?`  | `boolean \| undefined`                                                                             | Makes an agent ask a person before it runs any composer action, unless the host's `allow` lets it through. Default: `true`                                                                                  |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                                    | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                                |

### Agent [#agent]

An agent connected with `createAgent` reads the composer's `value`, and whether it's pending. It can run these actions, and `stop` only while Stop shows. While `agentConfirm` is on, every one of them waits for a person to confirm, unless the host's `allow` lets it through:

### ComposerAgentActions

| Prop               | Type                                                         | Description                                                                                                             |
| ------------------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `setValue`         | `(value: ComposerDraft \| string, event?: Event) => boolean` | Replaces the draft. A string replaces only the text and keeps the attachments. Returns whether the change was accepted. |
| `insertToken`      | `(token: TokenToInsert) => boolean`                          | Inserts a mention or command at the caret. Returns whether it was inserted.                                             |
| `removeAttachment` | `(id: string, event?: Event) => boolean`                     | Removes an attachment from the draft by its `id`. Returns whether the change was accepted.                              |
| `submit`           | `(event?: Event) => void`                                    | Sends the draft, unless there's nothing to send, it's pending or disabled, or `onSubmit` isn't set.                     |
| `stop`             | `((event?: Event) => void) \| undefined`                     | Calls `onStop`. Offered only while a submission is pending and `onStop` is set.                                         |

<Caption>
Runs in React and Web Components. On `<kind-composer>`, each prop is a kebab-case attribute, so `submitOn` is `submit-on`, and `value`, `defaultValue`, `mentions`, `commands` and `history` are properties. Each callback is a lowercase event, so `onValueChange` fires `valuechange`, but `onSubmit` fires `composersubmit`, whose listeners call `event.detail.waitUntil(promise)`, and Stop shows with the `can-stop` attribute and fires `stop`.
</Caption>