4e:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 4f:T1c7c,--- title: Mention description: Inline markable void mentions backed by trigger combobox input. docs: - route: /docs/combobox title: Combobox - route: /docs/components/mention-node title: Mention Nodes - route: /docs/components/inline-combobox title: Inline Combobox --- Mention turns trigger text such as `@` into an inline combobox input and inserts a markable void `mention` node when the user selects an item. The package owns trigger detection, input node creation, mention insertion, selection movement, and Markdown mention serialization. The registry owns the demo item list and the inline combobox UI. ## Features - Inline void `mention` nodes with `value` and optional `key`. - Inline void `mention_input` nodes created by trigger text. - Trigger combobox support from `@platejs/combobox`. - Configurable trigger strings, regexes, and trigger queries. - Markable void rendering so bold, italic, and underline can style a mention. - Optional trailing space after selected mention items. - Markdown format through `[display text](mention:id)` plus bare `@name` deserialization. ## Fast Path ### Add The Kit `MentionKit` installs `MentionPlugin`, `MentionInputPlugin`, the registry mention nodes, and a trigger rule that allows `@` at the start of a line, after whitespace, or after quotes. ```tsx import { createPlateEditor } from 'platejs/react'; import { MentionKit } from '@/components/editor/plugins/mention-kit'; export const editor = createPlateEditor({ plugins: MentionKit, }); ``` ### Render Mentions `mention-node` renders both the selected mention and the temporary combobox input. The demo data lives in that registry UI file, so replace it with your app users, pages, or records. ### Add Static Rendering `mention-base-kit` uses `BaseMentionPlugin` with the static mention node for read-only output. ## Ownership | Layer | Owner | What It Does | |-------|-------|--------------| | `@platejs/mention` | Package | Exports `BaseMentionPlugin`, `BaseMentionInputPlugin`, and `getMentionOnSelectItem`. | | `@platejs/mention/react` | Package | Exports `MentionPlugin` and `MentionInputPlugin`. | | `@platejs/combobox` | Package | Provides `withTriggerCombobox`, trigger options, and combobox input hooks. | | `mention-kit` | Registry | Adds mention plugins with editable mention and input components. | | `mention-base-kit` | Registry | Adds `BaseMentionPlugin.withComponent(MentionElementStatic)`. | | `mention-node` | Registry UI | Renders mention atoms, the inline combobox input, and demo items. | | `inline-combobox` | Registry UI | Renders the Ariakit-backed popover, input, groups, items, and empty state. | | `@platejs/markdown` | Package | Serializes mentions as `mention:` links and deserializes mention links or bare mentions. | ## Manual Setup ### Install Package ```bash npm install @platejs/mention ``` ### Add Plugins Configure the mention plugin with the trigger behavior and render both node types. ```tsx import { MentionInputPlugin, MentionPlugin } from '@platejs/mention/react'; import { createPlateEditor } from 'platejs/react'; import { MentionElement, MentionInputElement, } from '@/components/ui/mention-node'; export const editor = createPlateEditor({ plugins: [ MentionPlugin.configure({ options: { triggerPreviousCharPattern: /^$|^[\s"']$/, }, }).withComponent(MentionElement), MentionInputPlugin.withComponent(MentionInputElement), ], }); ``` ### Select An Item Use `getMentionOnSelectItem` from your combobox item renderer. It inserts the mention, moves the cursor after it, and inserts a trailing space only when `insertSpaceAfterMention` is enabled and the mention lands at the end of the block. ```tsx import { getMentionOnSelectItem } from '@platejs/mention'; const onSelectItem = getMentionOnSelectItem(); onSelectItem(editor, item, search)} > {item.text} ; ``` ## Value Shape `BaseMentionPlugin` uses `KEYS.mention`, which resolves to the `mention` node type. The input plugin uses `KEYS.mentionInput`, which resolves to `mention_input`. ```tsx const value = [ { children: [ { text: 'Assigned to ' }, { children: [{ text: '' }], key: 'user_123', type: 'mention', value: 'Jane Smith', }, { text: '.' }, ], type: 'p', }, ]; ``` | Field | Type | Notes | |-------|------|-------| | `type` | `'mention'` | Inline void mention node. | | `value` | `string` | Display text rendered by the registry node. | | `key` | `unknown` | Optional stable id used by selection handlers and Markdown serialization. | | `children` | `[{ text: '' }]` | Empty child required for Slate inline void nodes. | The mention node is `isMarkableVoid`, so marks on its empty child can style the rendered mention. ## Trigger Flow `withTriggerCombobox` overrides `insertText`. It creates a combobox input only when every gate passes. | Gate | Source | |------|--------| | Inserted text matches `trigger` | `string`, `string[]`, or `RegExp`. | | Insert is not using `options.at` | Programmatic text insertion bypasses the trigger. | | Editor has a selection | No selection means no inline input target. | | `triggerQuery(editor)` returns true | Optional app veto for custom contexts. | | Previous character matches `triggerPreviousCharPattern` | Defaults to `/^\s?$/`; registry kit uses `/^$\|^[\s"']$/`. | The default `createComboboxInput` creates: ```tsx { children: [{ text: '' }], trigger: '@', type: KEYS.mentionInput, } ``` If `editor.meta.userId` exists, the combobox input stores that `userId` so only the creator sees the transient input in collaborative editors. ## Markdown `@platejs/markdown` serializes mentions as link-style `mention:` URLs. It uses `key` for the URL when present and `value` for the visible text. ```md Hello [Jane Smith](mention:user_123). ``` Deserialization supports link-style mentions and bare `@alice` text. Normal links such as `[@docs](/docs/mention)` stay links. ## API Reference | API | Package | Use | |-----|---------|-----| | `BaseMentionPlugin` | `@platejs/mention` | Headless inline markable void mention plugin with trigger-combobox behavior. | | `BaseMentionInputPlugin` | `@platejs/mention` | Inline void input node inserted while the combobox is active. | | `MentionPlugin` | `@platejs/mention/react` | React mention plugin. | | `MentionInputPlugin` | `@platejs/mention/react` | React mention input plugin. | | `editor.tf.insert.mention({ key, value })` | `BaseMentionPlugin` transform | Inserts the mention node at the current selection. | | `getMentionOnSelectItem({ key? })` | `@platejs/mention` | Returns an item handler for mention combobox selection. | | `withTriggerCombobox` | `@platejs/combobox` | Creates temporary combobox input nodes from trigger text. | | `useComboboxInput` | `@platejs/combobox/react` | Handles focus, cancellation, arrow/backspace/escape behavior, and undo/redo forwarding for custom input UI. | 4d:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4e",null,{"files":[{"path":"../../content/docs/(plugins)/(elements)/mention.mdx","content":"$4f","type":"registry:file","target":"content/docs/plate/(plugins)/(elements)/mention.mdx"}],"className":"h-[70svh] min-h-80"}]]}]