Trigger Menu

Opens suggestions at the caret when you type a trigger such as @, /, or #.

A trigger menu suggests what to insert when someone types a trigger character, like @ for people or / for commands. It opens at the caret, narrows as they type, and inserts the choice into the text.

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerMenuDataItem,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuEmpty,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuList,
  TriggerMenuStatus,
} from "@ui-sdk/vue/trigger-menu"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]
</script>

<template>
  <TriggerMenu :triggers="[{ char: '@', type: 'mention', items: people }]">
    <Field>
      <FieldLabel>Message</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput
            v-bind="props"
            placeholder="Type @ to mention someone…"
          />
        </template>
      </FieldControl>
    </Field>
    <div data-slot="visually-hidden">
      <TriggerMenuStatus />
    </div>
    <TriggerMenuContent>
      <TriggerMenuEmpty>No one found</TriggerMenuEmpty>
      <TriggerMenuList v-slot="{ state }">
        <TriggerMenuItem
          v-for="item in state.items as TriggerMenuDataItem[]"
          :key="item.value"
          :value="item.value"
          :label="item.label"
        >
          {{ item.label }}
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type @, narrow the list with a name, and press Enter to insert the highlighted person.

Installation

npm install @ui-sdk/vue @ui-sdk/core

Composition

Use the following composition to build a TriggerMenu:

TriggerMenu
├── TriggerMenuInput
├── TriggerMenuStatus
└── TriggerMenuContent
    ├── TriggerMenuEmpty
    └── TriggerMenuList
        ├── TriggerMenuItem
        └── TriggerMenuItem

TriggerMenu holds the triggers and what each one lists. TriggerMenuInput is the field people type in, and TriggerMenuContent is the popup with the suggestions. Without a TriggerMenuContent among its direct children, the menu renders the current trigger's items for you. Inside a Token Input, leave out TriggerMenuInput: the menu suggests into the token input.

Usage

Import the parts and put them together:

<script setup lang="ts">
import {
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuList,
} from "@ui-sdk/vue/trigger-menu"
</script>

<template>
  <TriggerMenu :triggers="[{ char: '@' }]">
    <TriggerMenuInput
      aria-label="Message"
      placeholder="Type @ to mention someone…"
    />
    <TriggerMenuContent>
      <TriggerMenuList>
        <TriggerMenuItem value="hollis" label="Hollis Grant"
          >Hollis Grant</TriggerMenuItem
        >
        <TriggerMenuItem value="ines" label="Inès Moreau"
          >Inès Moreau</TriggerMenuItem
        >
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

label is the text an item is matched by and inserts. Choosing Hollis Grant replaces @ and what was typed after it with @Hollis Grant .

Trigger Menu suggests what to insert: it matches the trigger, filters, moves the highlight, loads items and asks for a command's arguments. Token Input holds a value that mixes text and tokens.

Use Trigger Menu with a textarea or an input to insert text. Put it inside a Token Input to insert tokens instead. Another editor connects through an adapter.

Triggers as Data

Give each trigger a char and its items. Items can be strings, objects, groups or a loader, and they render themselves when you leave out TriggerMenuContent. The same field can offer people after @, commands after / and channels after #.

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerDefinition,
  TriggerMenu,
  TriggerMenuInput,
} from "@ui-sdk/vue/trigger-menu"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]

const commands = ["away", "remind", "search", "status"]

const channels = [
  "announcements",
  "design",
  "design-reviews",
  "engineering",
  "general",
  "launches",
  "support",
]

function searchChannels(query: string, { signal }: { signal: AbortSignal }) {
  return new Promise<string[]>((resolve, reject) => {
    const timer = setTimeout(
      () =>
        resolve(
          channels.filter((channel) => channel.includes(query.toLowerCase()))
        ),
      400
    )
    signal.addEventListener("abort", () => {
      clearTimeout(timer)
      reject(signal.reason)
    })
  })
}

const triggers: TriggerDefinition[] = [
  { char: "@", items: people },
  { char: "/", boundary: "start", items: commands },
  { char: "#", items: searchChannels },
]
</script>

<template>
  <TriggerMenu :triggers="triggers">
    <Field>
      <FieldLabel>Message</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput v-bind="props" placeholder="Type @, / or #…" />
        </template>
      </FieldControl>
    </Field>
  </TriggerMenu>
</template>

Type @ for people, / at the start for commands, or # to load channels.

Commands with Arguments

A trigger with boundary: "start" matches only at the start of the text, so a leading space escapes it. An item with arguments asks for each one in order: TriggerMenuHint shows what's left at the caret, Tab accepts the highlighted suggestion and moves to the next argument, Enter finishes once only optional arguments remain, and Backspace past an argument's start goes back. An argument without items is free text. after: "submit" sends the form once the item is inserted.

Console

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerMenuSelectDetails,
  TriggerMenu,
  TriggerMenuHint,
  TriggerMenuInput,
} from "@ui-sdk/vue/trigger-menu"
import { useLog } from "./log"

const commands = [
  {
    value: "status",
    label: "status",
    arguments: [
      {
        name: "status",
        hint: "<status>",
        required: true,
        items: ["available", "busy", "away"],
      },
      {
        name: "until",
        hint: "[until]",
        items: ["30m", "1h", "4h", "today"],
        allowCustomValue: false,
      },
    ],
  },
  {
    value: "search",
    label: "search",
    arguments: [{ name: "query", hint: "<query>", required: true }],
  },
  { value: "away", label: "away", after: "submit" as const },
  { value: "clear", label: "clear" },
]

const log = useLog()

function onSubmit(event: Event) {
  log(
    `Sent ${new FormData(event.currentTarget as HTMLFormElement).get("message")}`
  )
}

function onSelect(value: string, details: TriggerMenuSelectDetails<string>) {
  log(["Chose", `/${value}`, ...Object.values(details.arguments)].join(" "))
}
</script>

<template>
  <form data-slot="stack" @submit.prevent="onSubmit">
    <TriggerMenu
      :triggers="[
        { char: '/', boundary: 'start', type: 'command', items: commands },
      ]"
      @select="onSelect"
    >
      <Field name="message">
        <FieldLabel>Message</FieldLabel>
        <FieldControl>
          <template #render="{ props }">
            <TriggerMenuInput
              v-bind="props"
              placeholder="Type / for commands…"
            />
          </template>
        </FieldControl>
      </Field>
      <TriggerMenuHint />
    </TriggerMenu>
  </form>
</template>

Type /status, then press Tab to choose a status and an optional time, and Enter to finish. Choose /away to send it at once. The console logs each command.

Icons

Put an item's icon in a TriggerMenuItemIcon, before its text. Screen readers skip it, and filtering and the text a choice inserts ignore it, so an SVG's <title>, an icon font's glyph or an emoji never joins the item's name or the field. Items as data have no icon, so compose the items that show one.

Icons that point a way, like arrows and reply, flip in right-to-left text with mirror.
Items with only an icon need an aria-label, which filtering matches too. In development, one with no name warns.
Lining up items. Items with an icon get data-has-icon, and the list gets data-has-icons while any item has one, so items without an icon can keep its space with padding.

<script setup lang="ts">
import {
  ClockIcon,
  ReplyIcon,
  SearchIcon,
  ShareIcon,
  TrashIcon,
} from "@lucide/vue"
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuItemIcon,
  TriggerMenuList,
} from "@ui-sdk/vue/trigger-menu"

const commands = [
  { value: "reply", icon: ReplyIcon, mirror: true },
  { value: "remind", icon: ClockIcon },
  { value: "search", icon: SearchIcon },
  { value: "share", icon: ShareIcon },
  { value: "clear", icon: TrashIcon },
]
</script>

<template>
  <TriggerMenu :triggers="[{ char: '/', boundary: 'start', type: 'command' }]">
    <Field>
      <FieldLabel>Message</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput v-bind="props" placeholder="Type / for commands…" />
        </template>
      </FieldControl>
    </Field>
    <TriggerMenuContent>
      <TriggerMenuList>
        <TriggerMenuItem
          v-for="command in commands"
          :key="command.value"
          :value="command.value"
        >
          <TriggerMenuItemIcon :mirror="command.mirror">
            <component :is="command.icon" />
          </TriggerMenuItemIcon>
          {{ command.value }}
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type / to open the commands, then type re to narrow them. Each icon sits before its name, and filtering ignores it.

Loading Items

A trigger's items can be a loader, called with the query and an AbortSignal once typing pauses. A newer query aborts the older load, so only its results land, and the last results stay while the next ones load. TriggerMenuStatus and TriggerMenuEmpty get loading, and while a load runs, aria-busy marks the list, so you can fade the results that are about to change.

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerMenuDataItem,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuEmpty,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuList,
  TriggerMenuStatus,
} from "@ui-sdk/vue/trigger-menu"

const channels = [
  "announcements",
  "design",
  "design-reviews",
  "engineering",
  "general",
  "launches",
  "support",
]

function searchChannels(query: string, { signal }: { signal: AbortSignal }) {
  return new Promise<{ value: string; label: string }[]>((resolve, reject) => {
    const timer = setTimeout(
      () =>
        resolve(
          channels
            .filter((channel) => channel.includes(query.toLowerCase()))
            .map((channel) => ({ value: channel, label: channel }))
        ),
      600
    )
    signal.addEventListener("abort", () => {
      clearTimeout(timer)
      reject(signal.reason)
    })
  })
}
</script>

<template>
  <TriggerMenu
    :triggers="[{ char: '#', type: 'channel', items: searchChannels }]"
  >
    <Field>
      <FieldLabel>Message</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput
            v-bind="props"
            placeholder="Type # to link a channel…"
          />
        </template>
      </FieldControl>
    </Field>
    <TriggerMenuContent>
      <TriggerMenuStatus v-slot="{ state }">
        {{
          state.loading
            ? "Loading channels…"
            : state.count
              ? `${state.count} ${state.count === 1 ? "channel" : "channels"}`
              : ""
        }}
      </TriggerMenuStatus>
      <TriggerMenuEmpty v-slot="{ state }">
        <template v-if="state.empty && !state.loading"
          >No channels match “{{ state.query }}”</template
        >
      </TriggerMenuEmpty>
      <TriggerMenuList v-slot="{ state }">
        <TriggerMenuItem
          v-for="item in state.items as TriggerMenuDataItem[]"
          :key="item.value"
          :value="item.value"
          :label="item.label"
        >
          {{ item.label }}
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type # and a channel name. The list says it's loading, and older results fade while newer ones load.

Custom Items

Compose TriggerMenuItems with any content, in groups. label is what's matched and inserted, keywords adds words to match, and disabled keeps an item in the list without letting it be chosen. A trigger's spaces, pattern and maxLength decide what its query may hold, filter how it narrows the items, and insert what replaces the trigger and query. An item's own @select runs first and can insert something else with details.insert().

<script setup lang="ts">
import { UsersIcon } from "@lucide/vue"
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerDefinition,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuGroup,
  TriggerMenuGroupLabel,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuItemIcon,
  TriggerMenuList,
  TriggerMenuSeparator,
} from "@ui-sdk/vue/trigger-menu"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik", disabled: true },
]

const triggers: TriggerDefinition[] = [
  {
    char: "@",
    spaces: 2,
    maxLength: 30,
    pattern: /[\p{L}.'-]/u,
    filter: "startsWith",
    insert: (item) => `@${item.label.split(" ")[0]} `,
  },
]
</script>

<template>
  <TriggerMenu :triggers="triggers">
    <Field>
      <FieldLabel>Message</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput
            v-bind="props"
            placeholder="Type @ and a first name…"
          />
        </template>
      </FieldControl>
    </Field>
    <TriggerMenuContent>
      <TriggerMenuList>
        <TriggerMenuGroup>
          <TriggerMenuGroupLabel>People</TriggerMenuGroupLabel>
          <TriggerMenuItem
            v-for="person in people"
            :key="person.value"
            :value="person.value"
            :label="person.label"
            :disabled="person.disabled"
          >
            {{ person.label }}
            <span data-slot="hint">{{
              person.disabled ? "Deactivated" : `@${person.value}`
            }}</span>
          </TriggerMenuItem>
        </TriggerMenuGroup>
        <TriggerMenuSeparator />
        <TriggerMenuItem
          value="here"
          label="here"
          :keywords="['everyone', 'channel']"
          @select="(value, details) => details.insert('@here ')"
        >
          <TriggerMenuItemIcon>
            <UsersIcon />
          </TriggerMenuItemIcon>
          Notify everyone here
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type @ and the start of a first name to insert it, or choose Notify everyone here to insert @here. Deactivated people can't be chosen.

Input

Render the input part as an <input> for a single line. It's a combobox with aria-expanded. In a single line, Enter often submits a form, so this example sets :auto-highlight="false": Enter chooses only once an arrow key has highlighted a person, and :loop="false" stops the arrows at either end of the list.

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerMenuDataItem,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuList,
} from "@ui-sdk/vue/trigger-menu"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]
</script>

<template>
  <TriggerMenu
    :triggers="[{ char: '@', items: people }]"
    :auto-highlight="false"
    :loop="false"
  >
    <Field>
      <FieldLabel>Task</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput
            v-bind="props"
            placeholder="Type @ to assign someone…"
          >
            <template #render="{ props: inputProps }">
              <input v-bind="inputProps" />
            </template>
          </TriggerMenuInput>
        </template>
      </FieldControl>
    </Field>
    <TriggerMenuContent>
      <TriggerMenuList v-slot="{ state }">
        <TriggerMenuItem
          v-for="item in state.items as TriggerMenuDataItem[]"
          :key="item.value"
          :value="item.value"
          :label="item.label"
        >
          {{ item.label }}
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type @ in the empty task. Nothing is highlighted until you press ArrowDown, then Enter assigns the person.

Positioning

By default, the list opens below the trigger at the caret and flips to stay on screen. side, align and the offsets place it, and anchor positions it against another element. This example opens the list above the whole field, lines its items up with the label, and renders it inside the field with container.

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerMenuDataItem,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuList,
} from "@ui-sdk/vue/trigger-menu"
import { useTemplateRef } from "vue"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]

const field = useTemplateRef<{ $el: HTMLDivElement }>("field")
</script>

<template>
  <TriggerMenu :triggers="[{ char: '@', items: people }]">
    <Field ref="field">
      <FieldLabel>Comment</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput
            v-bind="props"
            placeholder="Type @ to mention someone…"
          />
        </template>
      </FieldControl>
    </Field>
    <TriggerMenuContent
      side="top"
      align="start"
      :side-offset="8"
      :align-offset="-5"
      :collision-padding="16"
      :anchor="field?.$el"
      :container="field?.$el"
      keep-mounted
    >
      <TriggerMenuList v-slot="{ state }">
        <TriggerMenuItem
          v-for="item in state.items as TriggerMenuDataItem[]"
          :key="item.value"
          :value="item.value"
          :label="item.label"
        >
          {{ item.label }}
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type @ in the comment. The list opens above the field, lined up with its label.

Controlled

Bind v-model:open, or pass open and update it in @open-change, to own the popup state. The details say why it changed. @query-change reports the text after the trigger and the argument being typed, and @open-change-complete runs once the menu has finished opening or closing. Escape dismisses a match, and shortcut reopens it, Control+Space by default.

Console

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import { TriggerMenu, TriggerMenuInput } from "@ui-sdk/vue/trigger-menu"
import { ref } from "vue"
import { useLog } from "./log"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]

const commands = [
  {
    value: "status",
    label: "status",
    arguments: [
      {
        name: "status",
        hint: "<status>",
        required: true,
        items: ["available", "busy", "away"],
      },
    ],
  },
]

const log = useLog()
const open = ref(false)
</script>

<template>
  <TriggerMenu
    v-model:open="open"
    :triggers="[
      { char: '@', items: people },
      { char: '/', boundary: 'start', items: commands },
    ]"
    shortcut="ctrl+j"
    @open-change="
      (next, details) =>
        log(`${next ? 'Opening' : 'Closing'} (${details.reason})`)
    "
    @open-change-complete="(next) => log(next ? 'Open' : 'Closed')"
    @query-change="
      (query, details) =>
        log(
          `Query “${query}”${details.argument ? ` for ${details.argument}` : ''}`
        )
    "
  >
    <Field>
      <FieldLabel>Message</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <TriggerMenuInput v-bind="props" placeholder="Type @ or /…" />
        </template>
      </FieldControl>
    </Field>
  </TriggerMenu>
</template>

Type @ and a name, press Escape, then Control+J to reopen the list. The console logs each callback with its reason.

Controller

Create a controller with createTriggerMenuController() and pass it as controller to open suggestions, insert text at the caret, or read the current match. open() types the trigger at the caret and returns a Promise that resolves when the menu closes.

Console

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TriggerMenuDataItem,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuInput,
  TriggerMenuItem,
  TriggerMenuList,
  createTriggerMenuController,
} from "@ui-sdk/vue/trigger-menu"
import { useLog } from "./log"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]

const log = useLog()
const menu = createTriggerMenuController()

async function mention() {
  const closed = await menu.open({ trigger: "@" })
  log(`Closed (${closed.reason})`)
}

function insertDate() {
  menu.insert(
    new Date().toLocaleDateString("en-US", { month: "long", day: "numeric" })
  )
}
</script>

<template>
  <div data-slot="stack">
    <div data-slot="controls">
      <button type="button" @mousedown.prevent @click="mention">Mention</button>
      <button type="button" @mousedown.prevent @click="insertDate">
        Insert Date
      </button>
    </div>
    <TriggerMenu :controller="menu" :triggers="[{ char: '@', items: people }]">
      <Field>
        <FieldLabel>Message</FieldLabel>
        <FieldControl>
          <template #render="{ props }">
            <TriggerMenuInput v-bind="props" placeholder="Write a message…" />
          </template>
        </FieldControl>
      </Field>
      <TriggerMenuContent>
        <TriggerMenuList v-slot="{ state }">
          <TriggerMenuItem
            v-for="item in state.items as TriggerMenuDataItem[]"
            :key="item.value"
            :value="item.value"
            :label="item.label"
          >
            {{ item.label }}
          </TriggerMenuItem>
        </TriggerMenuList>
      </TriggerMenuContent>
    </TriggerMenu>
  </div>
</template>

Press Mention and choose a person. The console logs why the list closed. Insert Date adds today's date at the caret.

Any Editor

Pass editor to connect the menu to a field you render yourself, or to another editor. textFieldAdapter() makes one for a textarea or an input.

<script setup lang="ts">
import { Field, FieldControl, FieldLabel } from "@ui-sdk/vue/field"
import {
  type TextEditorAdapter,
  type TriggerMenuDataItem,
  TriggerMenu,
  TriggerMenuContent,
  TriggerMenuItem,
  TriggerMenuList,
  textFieldAdapter,
} from "@ui-sdk/vue/trigger-menu"
import { type Directive, shallowRef } from "vue"

const people = [
  { value: "hollis", label: "Hollis Grant" },
  { value: "ines", label: "Inès Moreau" },
  { value: "kofi", label: "Kofi Mensah" },
  { value: "wren", label: "Wren Takahashi" },
  { value: "tomasz", label: "Tomasz Wójcik" },
]

const editor = shallowRef<TextEditorAdapter>()
const vEditor: Directive<HTMLTextAreaElement> = {
  mounted: (field) => (editor.value = textFieldAdapter(field)),
}
</script>

<template>
  <TriggerMenu :editor="editor" :triggers="[{ char: '@', items: people }]">
    <Field>
      <FieldLabel>Notes</FieldLabel>
      <FieldControl>
        <template #render="{ props }">
          <textarea
            v-bind="props"
            v-editor
            placeholder="Type @ to mention someone…"
          />
        </template>
      </FieldControl>
    </Field>
    <TriggerMenuContent>
      <TriggerMenuList v-slot="{ state }">
        <TriggerMenuItem
          v-for="item in state.items as TriggerMenuDataItem[]"
          :key="item.value"
          :value="item.value"
          :label="item.label"
        >
          {{ item.label }}
        </TriggerMenuItem>
      </TriggerMenuList>
    </TriggerMenuContent>
  </TriggerMenu>
</template>

Type @ in the notes, a textarea connected through an editor adapter, and choose a person.

An adapter for another editor reads its text and selection, measures a rectangle at an offset, replaces a range as one undo step, and reports changes. Report changes that weren't the user's with user: false, like a collaborator's, and the menu never opens for them.

elementHTMLElement: The focused element that gets keys and the menu's ARIA. Undefined until it's in the page.
textBefore(length: number) => { text: string; offset: number; } | null: Up to length characters before the caret, and the offset they start at. A token reads as U+FFFC.
selection() => TextRange | null: The selection as text offsets, or null while unfocused.
rectAt(offset: number) => TextRect | null: The rectangle at a text offset, for anchoring.
replace(range: TextRange, content: string | TokenInsert, options?: EditorReplaceOptions) => void: Replaces a range with text or a token as one undoable step, and puts the caret after it.
subscribe(listener: (change: EditorChange) => void) => () => void: Calls listener for text edits, caret moves and composition. Returns a cleanup.
composing() => boolean: Whether an input method is composing.
tokens?boolean: Whether replace accepts tokens.
submit?((event?: Event) => void): Sends what's typed, like a form submit, for items that end with after: "submit".

Undo

Choosing an item keeps the native text field's undo history. Press Command+Z or Control+Z to bring back the query. Safari may combine the insertion with the typing before it in one undo step.

A custom editor adapter must make each replacement one undo step. Token Input handles its own token history.

Custom Rendering

Every part takes a render slot. Render TriggerMenuInput as an <input>, as the input example does, or inside another component's render slot, like a FieldControl's, as every example here does to join a Field. Parts and Composition explains how props merge, and each part's state is listed under State.

Styling

Style the field, the popup and its items. The content shows data-trigger, so each trigger's list can look different, like commands in a monospace font. Items show data-highlighted and data-disabled, and data-has-icon when they hold a TriggerMenuItemIcon; the list shows data-has-icons while any item has one. Fade a loading list with aria-busy, and style the hint as ghost text: it's positioned at the caret for you.

Each part has a data-slot, such as trigger-menu-item, and shows its state through the attributes listed under Data Attributes.

TriggerMenuContent

Variable	What it holds
`--anchor-width`	Width of the anchor, usually the trigger. Use it to match widths.
`--anchor-height`	Height of the anchor.
`--available-width`	Space beside the popup, up to the viewport edge. Not inherited either.
`--available-height`	Space between the anchor and the viewport edge. Use it for max-height. Not inherited, so a child that needs it copies it on the popup, like `[--list-height:var(--available-height)]`, and reads `max-h-(--list-height)`. The first popup registers both names for the whole page with `CSS.registerProperty`, so they don't inherit anywhere. A page that needs them to inherit calls it first, with `inherits: true`. An `@property` rule can't, since a registration in script wins.
`--transform-origin`	The point on the anchor the popup opens from. Use it to scale from the right place.
`--arrow-offset`	Where the anchor's center falls along the popup's edge, kept `arrowPadding` from the corners. Position a ::before arrow with it.

Data Attributes

TriggerMenuInput

[data-slot="trigger-menu-input"]

Attribute	What it means
`data-closed`	Present while the list is closed, including while it animates out.
`data-open`	Present while the list is open.
`data-trigger`	The trigger of the current match, like `@`, while there is one.

TriggerMenuContent

[data-slot="trigger-menu-content"]

Attribute	What it means
`data-closed`	Present while the list is closed, including while it animates out.
`data-starting-style`	Present for the first frame. Style the state you animate from.
`data-ending-style`	Present while the list animates out. Style the state you animate to.
`data-open`	Present while the list is open.
`data-trigger`	The trigger of the current match, like `@`, while there is one.
`data-has-icons`	Present while any item inside holds an icon part, so items without one can line up.

TriggerMenuItem

[data-slot="trigger-menu-item"]

Attribute	What it means
`data-disabled`	Present when the item can't be chosen.
`data-highlighted`	Present on the highlighted item. Focus stays in the field.
`data-has-icon`	Present on an item while it holds an icon part.

TriggerMenuEmpty

[data-slot="trigger-menu-empty"]

Attribute	What it means
`data-empty`	Present while no item matches.
`data-loading`	Present while items load.

TriggerMenuItemIcon

[data-slot="trigger-menu-item-icon"]

Attribute	What it means
`data-mirror`	Present on an icon that flips in right-to-left text, with `mirror`.

API Reference

Props are the same as below, and callbacks are events, except onSelect, which is a function prop bound with @select.

TriggerMenu

container?DocumentFragment | Element | null: Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
triggersTriggerDefinition<T>[]: The texts that open the menu, and what each one lists.
editor?TextEditorAdapter: The editor the menu reads and writes, for editors without a part of their own, like Tiptap. TriggerMenuInput and a surrounding TokenInput set it for you.
open?boolean: Whether the menu is open. Pass it to control it; it shows only while there's a match.
@open-change((open: boolean, details: ChangeDetails<TriggerMenuOpenChangeReason> & { trigger: string | null; }) => void): Runs when the menu wants to open or close. details.reason says why, details.trigger which trigger, and details.cancel() stops it.
@open-change-complete((open: boolean) => void): Runs once the menu has finished opening or closing, after any animation.
@query-change((query: string, details: ChangeDetails<TriggerMenuQueryChangeReason> & { trigger: string; argument?: string; }) => void): Runs when the text after the trigger changes. Read-only: it's the editor's text. details.argument names the argument being typed.
@select((value: T, details: TriggerMenuSelectDetails<T>) => void | Promise<void | Partial<TokenInsert>>): Runs when an item, with every required argument, is chosen. The default insertion follows unless details.preventDefault(). Return a Promise and a token is inserted at once as pending, updated with what it resolves to and removed if it rejects; the menu closes either way.
pendingAnnouncement?string: What screen readers hear once an @select Promise has been pending for a second, so a slow action doesn't pass in silence. Set it in the page's language. An empty string says nothing.
status?AsyncOptionsStatus: Whether items that come from outside are loading or failed, for the status and empty parts. Loaders report their own.
autoHighlight?boolean: Whether the first match is highlighted so Enter and Tab choose it. Visual only: screen readers hear about it once an arrow key moves the highlight, so typed characters keep being echoed.
loop?boolean: Whether arrow keys wrap from the last item to the first.
shortcut?string: Reopens a match dismissed with Escape, with the caret in it.
controller?object: Opens, closes and inserts from anywhere. Create one with createTriggerMenuController().
dismissible?boolean: Whether Escape, an outside press, focus or the window leaving, Android's back gesture and a sheet's swipe can close it. Triggers, Close parts and the controller always can. Pass false while it holds unsaved work, and ask in @dismiss-attempt.
@dismiss-attempt((details: { reason: "escape-key"; event?: KeyboardEvent | undefined; } | { reason: "outside-press"; event?: MouseEvent | undefined; }) => void): Runs when dismissible refused a dismissal made on purpose: Escape, an outside press, back or a swipe. Focus or the window leaving is refused without it. Ask "Discard changes?" here.
debug?boolean: Logs every state change with its reason to the console, in development builds.

Triggers

charstring: The text that starts a match: "@", "/", "#", or several characters like "[[".
boundary?TriggerBoundary: Where a match may start.
spaces?number | boolean: Whether the query may contain spaces, or up to how many words, like @next Wednesday.
pattern?RegExp: Characters a query may contain, tested one at a time.
maxLength?number: The longest query before the match ends.
type?string: The kind of token choosing an item inserts, where the editor takes tokens.
items?TriggerItemsLoader<T> | TriggerMenuData<T>: Suggestions as data, or a loader given the query and an AbortSignal. Without them, the composed items show.
filter?ListFilter<T>: How typing narrows data items. Loaded items aren't filtered.
insert?((item: TriggerMenuDataItem<T>, details: { match: TriggerMatch; arguments: Record<string, string>; }) => string | TokenInsert): What replaces the trigger and query. Defaults to a token where the editor takes tokens, else the trigger, the label and a space.

Items as Data

valueT: Identifies the item, and is what choosing it reports. A string, or any value with itemToValue.
labelstring: The text shown and matched by typeahead and filtering. A select's trigger shows it once chosen.
keywords?string[]: More words filtering matches, like ["team"] for a plan called Pro.
disabled?boolean: Keeps the item from being chosen. The keyboard skips it, like in a native select.
after?TriggerAfter: After choosing it: "compose" closes the menu, "continue" keeps it open and lists the same trigger's items for the text typed after it, and "submit" asks the editor to send. Tab never submits.
arguments?TriggerArgument[]: Typed arguments asked for in order once it's chosen, like /model <name>.

Arguments

namestring: The name it's reported under in details.arguments.
hint?string: Ghost text shown at the caret until it's typed. Defaults to <name>.
required?boolean: Whether Enter can finish the command without it.
items?TriggerItemsLoader<string> | TriggerMenuData<string>: Suggestions for it, as data or a loader. Without them, it's free text and no list shows.
allowCustomValue?boolean: Whether text that matches no suggestion is accepted, like a combobox's custom value.

TriggerMenuInput

The field the menu suggests into. Renders a textarea, or an input through its render slot.

TriggerMenuStatus

A polite status that says the count and the keys once typing pauses. Use its default slot, which receives the state, to say something else. Renders a div.

TriggerMenuContent

side?Side: Which side of the anchor the popup opens on. Flips to the other side when there isn't room. Which side of the trigger the list opens on.
align?Align: How the popup lines up with the anchor along that side. start and end follow the reading direction. How the list lines up with the trigger along that side.
sideOffset?number: Gap between the anchor and the popup, in pixels. Gap between the line of text and the list, in pixels.
alignOffset?number: Shift along the anchor, in pixels. Shift along the text, in pixels.
collisionPadding?number: Space to keep from the viewport edges, in pixels.
arrowPadding?number: Space to keep between the arrow and the popup's corners, in pixels.
anchor?string | Anchor | null: Positions the popup against this instead of its trigger: an element, a CSS selector, a point like { x, y }, or anything with getBoundingClientRect(). It's read on every check, so it can move. A controller's open({ anchor }) wins for that open.
container?DocumentFragment | Element | null: Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
keepMounted?boolean: Whether the list stays in the page, hidden, while closed.

TriggerMenuEmpty

Shown while no item matches. Rendering it keeps the menu open with no matches; without it, the menu closes until something matches. Renders a div.

TriggerMenuList

The listbox. Without a default slot, it renders the current trigger's items. Renders a div.

TriggerMenuItem

valueT: What @select receives when the item is chosen.
label?string: The text inserted and matched, when the content isn't plain text.
keywords?string[]: More words filtering matches.
disabled?boolean: Keeps the item from being chosen. It can still be highlighted, as the listbox pattern asks.
@select((value: T, details: TriggerMenuSelectDetails<T>) => void | Promise<void | Partial<TokenInsert>>): Runs before the menu's @select. details.preventDefault() skips the default insertion.

TriggerMenuItemIcon

mirror?boolean: Flips the icon horizontally in right-to-left text, for icons that point a way, like arrows and chevrons. Icons that picture a thing, like a clock or a check, stay as they are.

TriggerMenuGroup and TriggerMenuGroupLabel

A group of items, named by its label. Each renders a div.

TriggerMenuSeparator

A line between items or groups, hidden from screen readers. Renders a div.

TriggerMenuHint

Ghost text at the caret for the arguments still to type, like <status>. Renders a span, hidden from screen readers.

State

What render slots and the default slot receive, per part.

TriggerMenuInput:

openboolean: Whether the menu is open. It opens on a typed trigger, and closes when nothing matches unless it's loading or renders an empty part.
triggerstring | null: The trigger of the current match, like "@", or null.

TriggerMenuContent and TriggerMenuList:

openboolean: Whether the menu is open. False while it animates out.
triggerstring | null: The trigger of the current match, like "@", or null.
querystring: The text after the trigger, or after the current argument's start.
argumentstring | null: The argument being typed, by name, or null at the first level.
statusAsyncOptionsStatus: Whether items are loading or failed.
itemsTriggerMenuData<unknown>: The visible data items, for rendering them yourself.

TriggerMenuItem:

highlightedboolean: Whether the item is highlighted, by the keyboard or the pointer.
disabledboolean: Whether the item can't be chosen.

TriggerMenuItemIcon:

mirrorboolean: Whether it flips in right-to-left text.

TriggerMenuEmpty:

loadingboolean: Whether items are loading.
emptyboolean: Whether no item matches.
querystring: The text after the trigger.

TriggerMenuStatus:

openboolean: Whether the menu is open. It opens on a typed trigger, and closes when nothing matches unless it's loading or renders an empty part.
statusAsyncOptionsStatus: Whether items are loading or failed.
loadingboolean: Whether items are loading.
countnumber: How many items match.
argumentstring | null: The argument being typed, by name, or null.

TriggerMenuHint:

argumentstring | null: The argument being typed, by name, or null.
hintstring: The ghost text: the hints of the arguments still to type.

Reasons

details.reason says why the menu opened or closed.

input-changeEvent: Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
caret-moveEvent | KeyboardEvent | PointerEvent: The caret left a trigger menu's match: an arrow key, Home or End, a click, or a selection change.
item-pressMouseEvent | KeyboardEvent: A member of a collection was chosen: a menu item, a tab, a radio or a checkbox item.
escape-keyKeyboardEvent: Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
close-pressMouseEvent | KeyboardEvent | SubmitEvent: A Close part was pressed, or a form with method="dialog" was submitted.
outside-pressMouseEvent: A press outside the layer.
focus-outKeyboardEvent | FocusEvent: Focus left the layer, or Tab moved it out.
window-blurFocusEvent: The window lost focus.
imperativenone: A controller or api call, or a property set on a web component.
shortcutKeyboardEvent: A keyboard shortcut, like a trigger's shortcut.

With dismissible false, the refused dismissals @dismiss-attempt reports:

escape-keyKeyboardEvent: Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
outside-pressMouseEvent: A press outside the layer.

Why the query changed:

input-changeEvent: Typing, pasting or dropping changed a text field's value; in a combobox it can also open or close it, or Enter keeps the typed text as the value.
item-pressMouseEvent | KeyboardEvent: A member of a collection was chosen: a menu item, a tab, a radio or a checkbox item.
imperativenone: A controller or api call, or a property set on a web component.

Controller

Create one with createTriggerMenuController() and pass it as controller.

isOpen()() => boolean: Whether the menu is open.
setOpen(open, options?)(open: boolean, options?: TriggerMenuChangeOptions<TriggerMenuOpenChangeReason> | undefined) => boolean: Opens or closes the menu. Opening needs a match; see open() for one that types the trigger. Returns false when the change was canceled or it was already open or closed.
open(options?)(options?: (TriggerMenuChangeOptions<TriggerMenuOpenChangeReason> & { trigger?: string | undefined; signal?: AbortSignal | undefined; }) | undefined) => Promise<...>: Opens the menu for trigger, typing it at the caret first unless a match for it is already there, and resolves once it closes. Resolves exactly once and never rejects.
close(options?)(options?: TriggerMenuChangeOptions<TriggerMenuOpenChangeReason> | undefined) => boolean: Closes the menu. The match isn't dismissed, so typing in it opens it again. Returns false when the close was canceled or it was already closed.
getQuery()() => string: The text after the trigger, or after the current argument's start. Empty while closed.
getMatch()() => TriggerMatch | null: The current match, or null.
insert(content)(content: string | Token) => void: Replaces the current match with text or a token, or inserts at the caret without one.
focus()() => void: Moves focus to the editor.

Events

Events get the new state first, then the details. v-model only updates when the change event wasn't canceled.

Binding	On	Receives
`v-model:open`	`TriggerMenu`	Whether the menu is open
`@open-change`	`TriggerMenu`	`(open, details)`: the new state, the reason and the `trigger`
`@open-change-complete`	`TriggerMenu`	`(open)`, after the animation
`@query-change`	`TriggerMenu`	`(query, details)`: the text after the trigger, and the `argument` being typed
`@dismiss-attempt`	`TriggerMenu`	`({ reason, event })`, when a dismissal was refused
`@select`	`TriggerMenu`, `TriggerMenuItem`	`(value, details)`, a function prop: the item, its `arguments`, `insert()` and `preventDefault()`

When @select returns a Promise and the editor takes tokens, the token is inserted at once with data-pending, updated with what the Promise resolves to, and removed if it rejects. The menu closes either way, so people keep typing.

Accessibility

Focus stays in the field while the arrow keys move the highlight. A <textarea> stays a textbox, the only role ARIA allows it, and points at the list with aria-controls and, after an arrow key, aria-activedescendant. An <input> is a combobox with aria-expanded. Counts and loading are said through TriggerMenuStatus, a polite status, never through the field, so render one: visually hidden, as in the demo, or at the top of the list, as in Loading Items. Give the field a visible label through a Field, or an aria-label.

Keyboard

Key	Does
ArrowDown, ArrowUp	Moves the highlight while the list is open; the caret stays in the field
Enter	Chooses the highlighted item. In a command's arguments, finishes once only optional ones are left
Tab	Chooses the highlighted item, or accepts an argument and moves to the next
Escape	Closes the list and dismisses the match, so typing on doesn't reopen it
Control+Space	Reopens a dismissed match with the caret in it; `shortcut` changes the key
Backspace	Past an argument's start, goes back to the previous argument
Command+Z, Control+Z	Undoes the insertion and brings back the query

Tested Behavior

Every line below is an automated test.

Opening

Typing a trigger opens the list with every item.
Typing after the trigger filters the list.
Queries match Unicode letters and ignore accents.
A trigger mid-word doesn't open.
A trigger followed by a space doesn't open.
A command trigger opens only at the start, so a leading space escapes it.
The list opens at the trigger and stays there as the query grows.
Pasting a trigger opens the list.
Focusing a field that already has a match doesn't open the list.
Moving the caret into a match doesn't open the list.
A query that matches nothing closes the list, and Backspace that matches again opens it.
With an empty part, a query that matches nothing keeps the list open with the message.

Choosing

The first match is highlighted, and Enter inserts it with a space.
Tab accepts the highlighted suggestion and focus stays in the field.
Arrow keys move the highlight, and wrap.
A disabled item can be highlighted but not chosen.
Clicking an item inserts it and keeps focus and the caret in the field.
Text after the caret stays where it was.

Dismissing

Escape closes the list, keeps the text and focus.
A dismissed match stays closed through caret moves, typing in it and clicks.
A new trigger after a dismissed one opens.
Deleting and retyping the trigger opens it again.
Ctrl+Space reopens a dismissed match.
Moving the caret out of the match closes the list.
Pressing outside closes the list.

Arguments

A command with arguments asks for each one, and Enter finishes with them.
Enter finishes once only optional arguments are left.
A free-text argument shows no list, and Enter takes the typed text.
Backspace past an argument's start goes back a level.
Escape in an argument keeps the inserted text.
An item that submits sends the form once inserted.

Items load for the query.
A newer query aborts the older load, and only its results land.

Undo

Undo after choosing brings the query back, never a dead undo.

Input

The SDK's Textarea works as the field, and undo still works.
An <input> field works the same.

Runs in React, Vue and web components.

No axe violations while closed.
No axe violations while open with an item highlighted.
No axe violations while open on an input.
No axe violations with nothing found.
A textarea stays a textbox, without aria-expanded, and controls the list while open.
An input is a combobox that says whether it's expanded.
Aria-activedescendant waits for an arrow key and clears on the next edit.
Two menus on a page have their own ids, and the role never changes.
Options are named by their text.
The status says the count and the keys once typing pauses, then that nothing matches.
The hint is hidden from assistive technology, and the status names the argument.
Accessibility tree.

Runs in React, Vue and web components.