User Mention Converters

Design converters that round-trip user mention data between view markup and model attributes while preserving metadata and display text.

Capabilities

Upcasts annotated mention links

• Loading <a class="mention" data-marker="@" data-id="chris" data-name="Chris Holm" data-href="/users/chris" data-avatar="/img/chris.png"> produces a model mention attribute with a marker-prefixed id, generated uid, preserved metadata (name, href, avatar), and uses the element text as display text when no explicit name is provided. @test

Downcasts mention attributes to links

• Given a mention attribute with id "@sara" and metadata { name: "Sara Li", href: "/profiles/sara", avatar: "/avatars/sara.png" }, the downcast converter renders an <a> element with mention styling, data attributes mirroring the metadata, and link text set to the display name. @test

Syncs metadata on updates

• When mention metadata changes (e.g., href updated), the converter keeps the uid stable, updates all view data attributes to match the model, and preserves any extra metadata keys present on the mention attribute. @test

Implementation

@generates

API

import type { Editor } from '@ckeditor/ckeditor5-core';

export interface UserMentionData {
  id: string;
  name: string;
  href?: string;
  avatar?: string;
  text?: string;
  [key: string]: unknown;
}

/**
 * Registers custom mention converters that upcast annotated links into mention attributes
 * and downcast mention attributes back into annotated links.
 */
export function registerUserMentionConverters(editor: Editor): void;

/**
 * Builds a mention attribute object with uid, marker-prefixed id, display text, and metadata
 * that can be attached before insertion.
 */
export function buildUserMentionAttribute(data: UserMentionData): Record<string, unknown>;

Dependencies { .dependencies }

@ckeditor/ckeditor5-mention { .dependency }

Provides mention attribute helpers and converter utilities.