API reference

Root and channels

Mention.Root<T> and useMention<T>() accept:

A separating space is appended when neither the insertion nor the following text already supplies whitespace.

For multiple channels, Root and useMentionMulti<M>() accept a triggers map instead of a single channel. Each channel has items, getKey, getLabel, and optional getInsertText, allowSpaces, and filter. The multi-channel onSelect payload is keyed by the active trigger, for example { "@": person }.

Root also accepts children, unstyled, and handleRef. The handle exposes open(), close(), commit(item), and host. Opening rescans the existing text at the caret and retries a failed query; it does not insert a trigger or duplicate a pending or successful request.

MentionSelectMeta contains trigger, query, and triggerOffset. Offsets use UTF-16 within the adapter's current text region.

Compound components

React context cannot infer a List's item type from Root. Supply Mention.List<Person> and ensure that its type matches the selected channel. The same responsibility applies to useMentionContext<Person>().

Popover positioning

For a panel above the whole composer, attach a useRef<HTMLDivElement>(null) to its wrapper and pass it as anchorRef, with placement="top-start" and matchAnchorWidth. See the AI composer for the executable example. Mention retains collision handling and updates the position on relevant scrolling and resizing.

Hooks

useMention() and useMentionMulti() expose:

useMentionContext<T>() returns this interface inside Root. For standalone hooks, render the popup with the returned props. A hook's popup styling and positioning are application-owned.

Values belong on the textarea's standard value and onChange props. There is no second value state on the mention hook.

Editor adapter

interface EditorSnapshot {
  text: string;
  caret: number;
  key?: unknown;
}

interface MentionEdit {
  from: number;
  to: number;
  text: string;
}

interface EditorAdapter<T> {
  element: HTMLElement;
  read(): EditorSnapshot | null;
  getCaretRect(): DOMRect | null;
  replace(edit: MentionEdit, item: T, meta: MentionSelectMeta): void | boolean;
}

Return null when editing is unavailable, a selection spans a range, or composition is active. Keep offsets consistent within one editable region. Use key to distinguish regions with identical text. Replacements must use the host's transaction system; return false if the operation is rejected.

See the working editor integration.

Detection utility

findActiveMention(value, caret, trigger = "@", { allowSpaces: false }) returns { trigger, query } or null. The trigger can also be an array of characters. It scans backwards from the caret and suppresses mid-word triggers, with soft boundaries for selected Unicode scripts.

Pass { allowSpaces: true } to allow Unicode horizontal space separators (Zs) in the query. Tabs, line breaks, and U+FFFC editor atoms always stop the scan. See name matching for an opt-in local filter.