Mention Span Round-Trip Utility

Build a small adapter around a rich text editor that uses the dependency's mention feature to import and export HTML mention spans.

Capabilities

Round-trips valid mention spans

• Loading <p><span class="mention" data-mention='{"id":"@ada","_text":"@ada","uid":"m1"}'>@ada</span> rocks</p> and immediately exporting preserves the mention span with the same id, _text, and uid in the data payload. @test

Discards malformed mentions

• If the input HTML contains a mention span whose JSON lacks the id field, whose id does not start with the trigger marker (e.g., @), or whose payload is not valid JSON, exporting should emit plain text with no mention attribute or class. @test

Keeps custom payload data

• Additional fields inside data-mention (e.g., userId, role) should survive a load/export cycle and remain serialized in the outgoing JSON. @test

Cleans partial mention edits

• After loading a valid mention and inserting extra characters inside its text, the exported HTML should no longer contain a broken mention attribute; the mention should either stay intact when edits are within the attribute range or be converted to plain text if split. @test

Implementation

@generates

API

export interface MentionAdapterOptions {
  marker?: string;
  feedItems?: Array<string | { id: string; text?: string; [key: string]: unknown }>;
}

export interface MentionAdapter {
  load(html: string): Promise<void>;
  insertTextInsideFirstMention(text: string, offset?: number): Promise<void>;
  export(): Promise<string>;
  destroy(): Promise<void>;
}

/**
 * Create a mention-enabled adapter bound to a provided DOM element.
 * The adapter should configure the dependency's mention feature so that mention spans are interpreted and serialized by the default converters.
 */
export function createMentionAdapter(root: HTMLElement, options?: MentionAdapterOptions): Promise<MentionAdapter>;

Dependencies { .dependencies }

@ckeditor/ckeditor5-mention { .dependency }

Provides mention span recognition and conversion between HTML and the editor model.