TinyMCE mentions: insert a stable person ID and resolve it on hover

A fictional project handoff refers to two people named Alex. One handles print proofs; the other handles delivery. Storing only “@Alex” makes the next reader guess who owns the proof check. The record needs a stable identifier and enough visible context to distinguish the person.

Return the permitted directory results

The current documentation identifies Mentions as available for paid TinyMCE subscriptions. Confirm access in the application's existing setup before integrating it; adding a plugin name does not activate an entitlement.

The fetch callback receives a query and a success callback. This small local fixture demonstrates its data shape without calling a directory service:

const handoffPeople = [
  { id: 'person-41', name: 'Alex Rivera', description: 'Print proofs' },
  { id: 'person-77', name: 'Alex Chen', description: 'Delivery' }
];

const handoffMentionsFetch = (query, success) => {
  const term = query.term.toLowerCase();
  const matches = handoffPeople.filter(person =>
    person.name.toLowerCase().includes(term)
  );
  success(matches);
};

These people are illustrative data. In a production application, the server should return only people the author may discover in that project. Do not download an unrestricted directory and rely on client filtering to protect its contents.

The default item type displays names. Set mentions_item_type: 'profile' when the result menu needs the optional description, here the proof or delivery role. Both item types require string id and name values. The default mentions_min_chars is 1, so typing @ alone does not yet meet the normal threshold.

Keep the identifier in the inserted element

Merge this fragment into the existing TinyMCE initialization, retaining its other plugins and applicable configuration:

const handoffMentionOptions = {
  plugins: 'mentions',
  mentions_fetch: handoffMentionsFetch,
  mentions_item_type: 'profile',
  mentions_selector: 'span.handoff-person',
  mentions_menu_complete: (editor, person) => {
    const span = editor.getDoc().createElement('span');
    span.className = 'handoff-person';
    span.setAttribute('data-person-id', person.id);
    span.appendChild(editor.getDoc().createTextNode('@' + person.name));
    return span;
  }
};

Create the element with the editor's document, as TinyMCE's callback contract requires. Using a text node keeps the display name as text instead of interpreting it as HTML. The selector matches the inserted class, while data-person-id preserves the identity even if a person's display name later changes.

The menu description helps the author choose the right Alex. It is not automatically part of the inserted text. Write the surrounding sentence clearly, for example “@Alex Rivera checks the print proof before Friday's handoff.”

Use the saved ID for an existing mention's card

mentions_select is the documented callback for showing information when a reader hovers over a mention inside TinyMCE. It receives the mention element and a success callback. Read the stored ID, resolve the current permitted person, and return either a custom element or the documented profile template object.

Keep result-menu hover and existing-mention hover separate: mentions_menu_hover serves a candidate in the suggestion menu, while mentions_select serves an inserted mention. If the latter never runs, inspect mentions_selector and the saved element before debugging the directory request.

Decide how the application should display a departed or inaccessible person. Retain enough text for the handoff to remain understandable without silently remapping the old ID to somebody else.

Check persistence before treating the mention as an assignment

Insert the proof-review Alex in a disposable handoff, save through the real application, and reopen it. Inspect whether the span's class, ID attribute, and display text survived the storage and rendering filters. The TinyMCE content extraction guide covers capturing the current editor data.

A mention's presence does not itself establish a notification or task-assignment workflow. Implement and verify those application behaviors separately if the product needs them. Finish by reading the saved handoff as a colleague would: the proof check names the right Alex, and the stored identity still resolves to that person.