# ComposerPrimitive
URL: /docs/api-reference/primitives/composer

Primitives for the text input, send button, and attachments.

The user interface to add new messages or edit existing ones.

<Callout>
  **Dual Use!** A Composer placed directly inside a `Thread` will compose new
  messages. A Composer placed inside a `Message` will edit that message.
</Callout>

Anatomy \[#anatomy]

```tsx
import { ComposerPrimitive } from "@assistant-ui/react";

// creating a new message
const Composer = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.AttachmentDropzone>
      <ComposerPrimitive.Quote>
        <ComposerPrimitive.QuoteText />
        <ComposerPrimitive.QuoteDismiss />
      </ComposerPrimitive.Quote>
      <ComposerPrimitive.Attachments />
      <ComposerPrimitive.AddAttachment />
      <ComposerPrimitive.Input />
      <ComposerPrimitive.Send />
    </ComposerPrimitive.AttachmentDropzone>
  </ComposerPrimitive.Root>
);

// editing an existing message
const EditComposer = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.Input />
    <ComposerPrimitive.Send />
    <ComposerPrimitive.Cancel />
  </ComposerPrimitive.Root>
);

// with voice input (dictation)
const ComposerWithDictation = () => (
  <ComposerPrimitive.Root>
    <ComposerPrimitive.Input />
    <AuiIf condition={(s) => s.composer.dictation == null}>
      <ComposerPrimitive.Dictate />
    </AuiIf>
    <AuiIf condition={(s) => s.composer.dictation != null}>
      <ComposerPrimitive.StopDictation />
    </AuiIf>
    <ComposerPrimitive.Send />
  </ComposerPrimitive.Root>
);
```

API Reference \[#api-reference]

Root \[#root]

Contains all parts of the composer.

This primitive renders a `<form>` element unless `asChild` is set.

<ParametersTable
  type="ComposerRootProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

Input \[#input]

The text input field for the user to type a new message.

This primitive renders a `<textarea>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveInputProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
{
name: &#x22;submitMode&#x22;,
type: '&#x22;enter&#x22; | &#x22;ctrlEnter&#x22; | &#x22;none&#x22;',
default: '&#x22;enter&#x22;',
description:
'Controls how the Enter key submits messages. &#x22;enter&#x22;: plain Enter submits (Shift+Enter for newline). &#x22;ctrlEnter&#x22;: Ctrl/Cmd+Enter submits (plain Enter for newline). &#x22;none&#x22;: keyboard submission disabled.',
},
{
name: &#x22;cancelOnEscape&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to cancel message composition when Escape is pressed.&#x22;,
},
{
name: &#x22;unstable_focusOnRunStart&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to automatically focus the input when a new run starts.&#x22;,
},
{
name: &#x22;unstable_focusOnScrollToBottom&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to automatically focus the input when scrolling to bottom.&#x22;,
},
{
name: &#x22;unstable_focusOnThreadSwitched&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to automatically focus the input when switching threads.&#x22;,
},
{
name: &#x22;addAttachmentOnPaste&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description:
&#x22;Whether to automatically add pasted files as attachments.&#x22;,
},
]"
/>

Keyboard Shortcuts \[#keyboard-shortcuts]

Default (`submitMode="enter"`):

| Key                      | Description            |
| ------------------------ | ---------------------- |
| <Kbd>Enter</Kbd>         | Sends the message.     |
| <Kbd>Shift + Enter</Kbd> | Inserts a newline.     |
| <Kbd>Escape</Kbd>        | Sends a cancel action. |

With `submitMode="ctrlEnter"`:

| Key                         | Description            |
| --------------------------- | ---------------------- |
| <Kbd>Ctrl/Cmd + Enter</Kbd> | Sends the message.     |
| <Kbd>Enter</Kbd>            | Inserts a newline.     |
| <Kbd>Escape</Kbd>           | Sends a cancel action. |

Send \[#send]

The button to send the message.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveSendProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

Cancel \[#cancel]

Sends a cancel action.

In edit composers, this action exits the edit mode.
In thread composers, this action stops the current run.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveCancelProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

Attachments \[#attachments]

Renders attachments. This primitive renders a separate component for each attachment.

<ParametersTable
  type="ComposerPrimitiveAttachmentsProps"
  parameters="[
{
name: &#x22;components&#x22;,
type: &#x22;ComposerAttachmentsComponents&#x22;,
description: &#x22;The component to render for each attachment.&#x22;,
children: [
{
type: &#x22;ComposerPrimitiveAttachmentsProps['components']&#x22;,
parameters: [
{
name: &#x22;Image&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for each image attachment.&#x22;,
},
{
name: &#x22;Document&#x22;,
type: &#x22;ComponentType&#x22;,
description:
&#x22;The component to render for each document attachment.&#x22;,
},
{
name: &#x22;File&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The component to render for each file attachment.&#x22;,
},
{
name: &#x22;Attachment&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;The fallback component to render for each attachment type.&#x22;,
},
],
},
],
},
]"
/>

AttachmentByIndex \[#attachmentbyindex]

Renders a single attachment at the specified index within the composer.

```tsx
<ComposerPrimitive.AttachmentByIndex
  index={0}
  components={{
    Image: MyImageAttachment,
    Document: MyDocumentAttachment
  }}
/>
```

<ParametersTable
  type="ComposerPrimitive.AttachmentByIndex.Props"
  parameters="[
{
name: &#x22;index&#x22;,
type: &#x22;number&#x22;,
required: true,
description: &#x22;The index of the attachment to render.&#x22;,
},
{
name: &#x22;components&#x22;,
type: &#x22;ComposerAttachmentsComponents&#x22;,
description: &#x22;The components to render for the attachment.&#x22;,
},
]"
/>

AddAttachment \[#addattachment]

Renders a button to add an attachment.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveAddAttachmentProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
{
name: &#x22;multiple&#x22;,
type: &#x22;boolean | undefined&#x22;,
description: &#x22;Allow selecting multiple attachments at the same time.&#x22;,
default: &#x22;true&#x22;,
},
]"
/>

AttachmentDropzone \[#attachmentdropzone]

A drag-and-drop zone that accepts file drops and adds them as attachments to the composer.

When a file is dragged over the zone, a `data-dragging="true"` attribute is set on the element, which can be used for styling the active drag state.

This primitive renders a `<div>` element unless `asChild` is set.

```tsx
<ComposerPrimitive.AttachmentDropzone className="relative data-[dragging]:ring-2">
  <ComposerPrimitive.Input />
  <ComposerPrimitive.Send />
</ComposerPrimitive.AttachmentDropzone>
```

<ParametersTable
  type="ComposerPrimitiveAttachmentDropzoneProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
{
name: &#x22;disabled&#x22;,
type: &#x22;boolean | undefined&#x22;,
description: &#x22;When true, drag-and-drop is disabled and files will not be added on drop.&#x22;,
},
]"
/>

Dictate \[#dictate]

Renders a button to start dictation to convert voice to text.

Requires a `DictationAdapter` to be configured in the runtime.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveDictateProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

StopDictation \[#stopdictation]

Renders a button to stop the current dictation session.

Only rendered when dictation is active.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveStopDictationProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

DictationTranscript \[#dictationtranscript]

Renders the current interim (partial) transcript while dictation is active.

<Callout type="info">
  **Note:** By default, interim transcripts are displayed directly in the composer input (like native dictation).
  This component is for **advanced customization** when you want to display the interim transcript separately (e.g., in a different style or location).
</Callout>

Only renders when there is an active interim transcript (returns `null` otherwise).

This primitive renders a `<span>` element.

```tsx
{/* Optional: Display interim transcript separately with custom styling */}
<AuiIf condition={(s) => s.composer.dictation != null}>
  <div className="dictation-preview">
    <ComposerPrimitive.DictationTranscript className="italic text-muted" />
  </div>
</AuiIf>
```

Quote \[#quote]

A container for displaying a quote preview in the composer. Only renders when a quote is set via `composer.setQuote()`.

This primitive renders a `<div>` element.

```tsx
<ComposerPrimitive.Quote className="flex items-start gap-2 bg-muted/60 px-3 py-2">
  <ComposerPrimitive.QuoteText className="line-clamp-2 flex-1 text-sm" />
  <ComposerPrimitive.QuoteDismiss>×</ComposerPrimitive.QuoteDismiss>
</ComposerPrimitive.Quote>
```

QuoteText \[#quotetext]

Renders the quoted text content. Only renders when a quote is set.

This primitive renders a `<span>` element.

QuoteDismiss \[#quotedismiss]

A button that clears the current quote from the composer by calling `setQuote(undefined)`.

This primitive renders a `<button>` element unless `asChild` is set.

<ParametersTable
  type="ComposerPrimitiveQuoteDismissProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
},
]"
/>

<Callout type="info">
  See the [Quoting guide](/docs/guides/quoting) for a complete walkthrough including the floating selection toolbar and backend handling.
</Callout>

Conditional Rendering \[#conditional-rendering]

Use `AuiIf` for conditional rendering based on composer state:

```tsx
import { AuiIf } from "@assistant-ui/react";

<AuiIf condition={(s) => s.composer.isEditing}>
  {/* rendered if message is being edited */}
</AuiIf>

<AuiIf condition={(s) => s.composer.dictation != null}>
  {/* rendered if dictation is active */}
</AuiIf>
```

Trigger Popover Primitives (Unstable) \[#trigger-popover-primitives-unstable]

<Callout type="warn">
  These primitives are under the `Unstable_` prefix and may change without notice.
</Callout>

Unified primitives for any character-triggered popover (`@` mentions, `/` slash commands, `:` emoji, etc.). Multiple triggers coexist under a single `TriggerPopoverRoot`. See the [Mentions guide](/docs/guides/mentions) and [Slash Commands guide](/docs/guides/slash-commands) for full documentation and the [ComposerTriggerPopover component](/docs/ui/composer-trigger-popover) for a pre-built implementation.

Anatomy \[#anatomy-1]

```tsx
import { ComposerPrimitive } from "@assistant-ui/react";
import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";

const Composer = () => (
  <ComposerPrimitive.Unstable_TriggerPopoverRoot>
    <ComposerPrimitive.Root>
      <ComposerPrimitive.Input />

      <ComposerPrimitive.Unstable_TriggerPopover
        char="@"
        adapter={mention.adapter}
      >
        <ComposerPrimitive.Unstable_TriggerPopover.Directive
          {...mention.directive}
        />
        <ComposerPrimitive.Unstable_TriggerPopoverCategories>
          {(categories) =>
            categories.map((cat) => (
              <ComposerPrimitive.Unstable_TriggerPopoverCategoryItem
                key={cat.id}
                categoryId={cat.id}
              >
                {cat.label}
              </ComposerPrimitive.Unstable_TriggerPopoverCategoryItem>
            ))
          }
        </ComposerPrimitive.Unstable_TriggerPopoverCategories>
        <ComposerPrimitive.Unstable_TriggerPopoverItems>
          {(items) =>
            items.map((item) => (
              <ComposerPrimitive.Unstable_TriggerPopoverItem
                key={item.id}
                item={item}
              >
                {item.label}
              </ComposerPrimitive.Unstable_TriggerPopoverItem>
            ))
          }
        </ComposerPrimitive.Unstable_TriggerPopoverItems>
        <ComposerPrimitive.Unstable_TriggerPopoverBack>
          Back
        </ComposerPrimitive.Unstable_TriggerPopoverBack>
      </ComposerPrimitive.Unstable_TriggerPopover>
    </ComposerPrimitive.Root>
  </ComposerPrimitive.Unstable_TriggerPopoverRoot>
);
```

Unstable\_TriggerPopoverRoot \[#unstable\_triggerpopoverroot]

Root provider that groups one or more `TriggerPopover` declarations. Owns the shared `ComposerInputPluginRegistry` that routes cursor and keyboard events to each registered trigger.

No props.

Unstable\_TriggerPopover \[#unstable\_triggerpopover]

Declares a trigger and renders its popover container. Only renders its DOM (and children) while this trigger is active in the composer input. Each declaration has an isolated scope — sub-primitives placed inside read state from this declaration only.

| Prop      | Type                      | Default | Description                                                                         |
| --------- | ------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `char`    | `string`                  | —       | Character(s) that activate the trigger (e.g. `"@"`, `"/"`) — unique within the root |
| `adapter` | `Unstable_TriggerAdapter` | —       | Provides categories, items, and search                                              |

Selection behavior is declared by rendering **exactly one** behavior sub-primitive inside the `TriggerPopover`:

* [`Unstable_TriggerPopover.Directive`](#unstable_triggerpopoverdirective) — inserts `:type[label]{name=id}` into the composer on selection (mention behavior).
* [`Unstable_TriggerPopover.Action`](#unstable_triggerpopoveraction) — fires `onExecute` on selection; leaves a directive chip as an audit trail by default.

Renders a `<div>` with `role="listbox"` when open.

Unstable\_TriggerPopover.Directive \[#unstable\_triggerpopoverdirective]

Behavior sub-primitive. Placed inside a `<Unstable_TriggerPopover>`. Renders nothing — registers an `"directive"` behavior with its parent. Exactly one behavior sub-primitive is allowed per `TriggerPopover`.

| Prop         | Type                          | Default                              | Description                                                           |
| ------------ | ----------------------------- | ------------------------------------ | --------------------------------------------------------------------- |
| `formatter`  | `Unstable_DirectiveFormatter` | `unstable_defaultDirectiveFormatter` | Serializes the selected item into composer text (and parses it back). |
| `onInserted` | `(item) => void`              | —                                    | Fires after the directive text has been inserted.                     |

Unstable\_TriggerPopover.Action \[#unstable\_triggerpopoveraction]

Behavior sub-primitive. Placed inside a `<Unstable_TriggerPopover>`. Renders nothing — registers an `"action"` behavior with its parent. Exactly one behavior sub-primitive is allowed per `TriggerPopover`.

| Prop              | Type                          | Default                              | Description                                                                          |
| ----------------- | ----------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
| `formatter`       | `Unstable_DirectiveFormatter` | `unstable_defaultDirectiveFormatter` | Serializes the audit-trail chip (unused when `removeOnExecute` is true).             |
| `onExecute`       | `(item) => void`              | —                                    | Called the moment an item is selected — typically routes to a handler map. Required. |
| `removeOnExecute` | `boolean`                     | `false`                              | When `true`, strips the trigger text from the composer instead of leaving a chip.    |

Unstable\_TriggerBehavior \[#unstable\_triggerbehavior]

Union type returned by the two behavior sub-primitives and consumed internally by the popover resources. Exported for advanced use cases (e.g. custom sub-primitives).

```ts
import type { Unstable_TriggerBehavior } from "@assistant-ui/react";

// Equivalent shape:
// Unstable_TriggerBehavior =
//   | { kind: "directive"; formatter: Unstable_DirectiveFormatter; onInserted?: (item) => void }
//   | { kind: "action"; formatter: Unstable_DirectiveFormatter; onExecute: (item) => void; removeOnExecute?: boolean }
```

Unstable\_TriggerPopoverCategories \[#unstable\_triggerpopovercategories]

Renders the top-level category list. Accepts a render function `(categories) => ReactNode`. Hidden when a category is selected or when in search mode.

Unstable\_TriggerPopoverCategoryItem \[#unstable\_triggerpopovercategoryitem]

A button that drills into a category. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.

| Prop         | Type     | Description                     |
| ------------ | -------- | ------------------------------- |
| `categoryId` | `string` | The category to select on click |

Unstable\_TriggerPopoverItems \[#unstable\_triggerpopoveritems]

Renders the item list for the active category or search results. Accepts a render function `(items) => ReactNode`. Hidden when no category is selected and not in search mode.

Unstable\_TriggerPopoverItem \[#unstable\_triggerpopoveritem]

A button that selects an item. Renders `role="option"` with automatic `data-highlighted` and `aria-selected` when keyboard-navigated.

| Prop    | Type                   | Description                                    |
| ------- | ---------------------- | ---------------------------------------------- |
| `item`  | `Unstable_TriggerItem` | The item to select on click                    |
| `index` | `number`               | Optional index override for highlight matching |

Unstable\_TriggerPopoverBack \[#unstable\_triggerpopoverback]

A button that navigates back from items to the category list. Only renders when a category is active.

unstable\_useTriggerPopoverScopeContext \[#unstable\_usetriggerpopoverscopecontext]

Hook to access the popover state and actions for the nearest enclosing `Unstable_TriggerPopover`.

```tsx
const {
  open,           // boolean — whether popover is visible
  query,          // string — text after the trigger character
  isSearchMode,   // boolean — whether showing search results
  highlightedIndex,
  categories,
  items,
  activeCategoryId,
  selectCategory,
  selectItem,
  goBack,
  close,
  handleKeyDown,
} = unstable_useTriggerPopoverScopeContext();
```

unstable\_useTriggerPopoverTriggers \[#unstable\_usetriggerpopovertriggers]

Hook to iterate every trigger registered under the current `Unstable_TriggerPopoverRoot`. Intended for input-level integrations (e.g. Lexical `DirectivePlugin`). Returns `ReadonlyMap<string, Unstable_RegisteredTrigger>`.

unstable\_useMentionAdapter \[#unstable\_usementionadapter]

Returns a spreadable `{ adapter, directive }` bundle for `@` mentions. Reads tools registered via `useAssistantTool`, accepts explicit `items`, and supports multi-category drill-down.

```tsx
import {
  unstable_useMentionAdapter,
  type Unstable_Mention,
} from "@assistant-ui/react";

function MyComposer() {
  // Default: tools from model context as a single "Tools" category
  const mention = unstable_useMentionAdapter();

  return (
    <ComposerTriggerPopover char="@" {...mention} />
  );
}
```

```tsx
// Multi-category + tools appended as their own category
const mention = unstable_useMentionAdapter({
  categories: [
    { id: "users", label: "Users", items: [/* ... */] },
    { id: "files", label: "Files", items: [/* ... */] },
  ],
  includeModelContextTools: true,
});
```

Options:

| Option                     | Type                                            | Description                                                                 |
| -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| `items`                    | `Unstable_Mention[]`                            | Flat list; ignored when `categories` is set.                                |
| `categories`               | `{ id, label, items: Unstable_Mention[] }[]`    | Drill-down groups.                                                          |
| `includeModelContextTools` | `boolean \| { category?, formatLabel?, icon? }` | Tools integration. Defaults to `true` iff neither `items` nor `categories`. |
| `formatter`                | `Unstable_DirectiveFormatter`                   | Override directive serialization.                                           |
| `onInserted`               | `(item) => void`                                | Fires after the directive is inserted.                                      |
| `iconMap`                  | `Record<string, Unstable_IconComponent>`        | `metadata.icon` / category id → React component.                            |
| `fallbackIcon`             | `Unstable_IconComponent`                        | Fallback when no `iconMap` entry matches.                                   |

Returns `{ adapter, directive, iconMap?, fallbackIcon? }`.

unstable\_useSlashCommandAdapter \[#unstable\_useslashcommandadapter]

Returns a spreadable `{ adapter, action }` bundle for slash commands. Commands are declared as data + inline `execute` callbacks; `execute` lives in the hook closure and is never attached to the returned `Unstable_TriggerItem`, keeping items JSON-serializable.

```tsx
import {
  unstable_useSlashCommandAdapter,
  type Unstable_SlashCommand,
} from "@assistant-ui/react";

const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
  { id: "summarize", execute: () => runSummarize(), icon: "FileText" },
  { id: "translate", execute: () => runTranslate(), icon: "Languages" },
];

function MyComposer() {
  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
  return (
    <ComposerTriggerPopover char="/" {...slash} />
  );
}
```

Pass `removeOnExecute: true` on the hook options to strip the trigger text from the composer after executing. The hook also accepts `iconMap` / `fallbackIcon` options that flow into the returned bundle — `{...slash}` spreads them into `ComposerTriggerPopover`.