Mention-Enabled Editor

Build helpers that configure an editor with mention support across people and topic markers, including custom rendering, async feeds, and programmatic insertion.

Capabilities

Separate feeds for markers

• Typing @al surfaces only person suggestions, while #al surfaces only topic suggestions, each limited to its own dropdown size and minimum character rule. @test

Custom rows and inserted text

• Person suggestions render labels that combine name and handle, and choosing a suggestion inserts the provided display text while keeping the original id/metadata in the stored mention attribute. @test

Async hashtag sourcing

• Hashtag suggestions come from an async provider; if a slower response for an older query arrives after a newer one, the dropdown keeps the newer results. @test

Programmatic mention command

• A helper inserts a mention at the current selection or given range, preserves existing text attributes (for example, bold) across the inserted mention, and skips adding an extra trailing space when one already follows. @test

Implementation

@generates

API

type MentionFeedItem = {
  id: string;
  label?: string;
  text?: string;
  metadata?: Record<string, unknown>;
};

type FeedConfig = {
  marker: '@' | '#';
  items: MentionFeedItem[] | ((queryText: string) => Promise<MentionFeedItem[]> | MentionFeedItem[]);
  minimumCharacters?: number;
  dropdownLimit?: number;
};

export interface MentionEditorSetupOptions {
  element: HTMLElement;
  feeds: FeedConfig[];
  renderer?(item: MentionFeedItem): string | HTMLElement;
  commitKeys?: string[];
}

export interface MentionEditor {
  element: HTMLElement;
}

export function createMentionEditor(options: MentionEditorSetupOptions): Promise<MentionEditor>;

export function insertMention(
  editor: MentionEditor,
  mention: { marker: '@' | '#'; id: string; text?: string; metadata?: Record<string, unknown> },
  range?: unknown
): void;

Dependencies { .dependencies }

@ckeditor/ckeditor5-mention { .dependency }

Mention editing, feed handling, and dropdown UI for the editor.