Skip to contentKino
Skip to Content

Trigger menu

Suggestions that open at a character typed in a field, such as @ for people or / for commands, and put the pick in place of what was typed.

npx shadcn add https://kinoui.com/r/trigger-menu.json
Share on

Examples

KN-2481Ship the replacement card readerPRPriya Raman · In progress
Comment

Default

Type @ to mention someone, # to link an issue, or / at the start of a line for a command: the list opens under the character, narrows as you type, and Enter or Tab puts the pick in its place.

One-line field

TriggerMenuInput is a single line, such as a task’s title: # files it under a project and @ assigns it.

Announcement

From a server

onMatchChange tells you what is typed after the trigger, so you can ask a server and render what it answers. TriggerMenuEmpty says it is looking until the rows arrive.

Installation

npx shadcn@latest add https://kinoui.com/r/trigger-menu.json
Files
lib/reduce-motion.tslib/scroll.tslib/trigger-editor.tsxlib/refs.tslib/resize.tslib/swap.tsxlib/popup.tslib/glide.tsxcomponents/kino/tooltip.tsxlib/cut.tsxcomponents/kino/spinner.tsxcomponents/kino/button.tsxcomponents/kino/input.tsxcomponents/kino/separator.tsxlib/run-progress.tslib/highlight.tslib/menu.tsxcomponents/kino/select.tsxlib/filter-list.tsxlib/announce.tsxcomponents/kino/textarea.tsxcomponents/kino/trigger-menu.tsx
Packages
@base-ui/reactclass-variance-authority

New to Kino? Installation covers what your project needs first and the @kino namespace.

API reference

TriggerMenu

PropTypeDefaultDescription
triggers(string | TriggerMenuTrigger)[]NoneThe characters that open it. As an object: char; start, word (the default, so an email address doesn’t open it) or line (only as a line’s first character, as for commands); label, the list’s name for a screen reader; and type, the kind of token a pick becomes in an editor that holds tokens.
onMatchChange(match: TriggerMatch | null) => voidNoneCalled when the trigger or the text after it changes, and with null when the caret leaves it. match has the trigger, the query, and the start and end of what a pick replaces.
editorTriggerEditorNoneAn editor of your own in place of TriggerMenuTextarea or TriggerMenuInput. An editor that provides TriggerEditorContext around the menu needs nothing here.
resultsLabel(count: number) => string“3 suggestions”What a screen reader hears once typing pauses. With nothing found it reads TriggerMenuEmpty instead.

TriggerMenuContent

PropTypeDefaultDescription
side'left''top''bottom''right''inline-start''inline-end''bottom'The side of the character it opens on. It flips when there isn’t room.
align'start''center''end''start'How it lines up with the character.
sideOffsetnumberfunction6The gap between it and the line of text, in pixels.
alignOffsetnumberfunction0How far it shifts along that side, in pixels.
classNamestringNoneGoes to the content inside the box.

TriggerMenuItem

PropTypeDefaultDescription
valuestringNoneUnique among the rows.
labelstringNoneWhat it is matched by and inserted as. Its text when that’s a string, else value.
keywordsstring[]NoneMore words it matches, such as a handle or an ID.
insertstringTriggerTokenContent`@label ` or a tokenWhat replaces the trigger and the query: by default the trigger and the label, and in an editor that holds tokens, a token. Text gets a space after it unless one, or closing punctuation, follows. An empty string removes them, as a command does.
onSelect() => voidNoneCalled once it is picked and inserted.
disabledbooleanfalseShows but can’t be picked; the arrows pass over it.

Accessibility

  • Focus stays in the field. It points at the list with aria-controls and at the highlighted row with aria-activedescendant, which a screen reader reads as the highlight moves. A one-line field is a combobox.
  • It opens as a trigger is typed. Moving the caret into a mention already written leaves it shut, so Enter there is still a new line; Ctrl+Space opens it there.
  • Arrow keys move the highlight, Enter or Tab puts it in, and Escape closes the list without leaving a dialog around the field. Typing on doesn’t bring it back; Ctrl+Space does.
  • An insert is one step in the field’s own undo, so ⌘Z or Ctrl+Z brings back what was typed.
  • How many suggestions there are is said once typing pauses, and what TriggerMenuEmpty says when there are none.
  • Name the field with a label, aria-label or aria-labelledby, and the list with its trigger’s label.
  • When the system asks for less motion, the box fades instead of growing, and changes height at once.