How to Add @Mentions to a React Rich Text Editor 2026 (Autocomplete Guide)

How to Add @Mentions to a React Rich Text Editor 2026 (Autocomplete Guide)

Learning how to add mentions to a React rich text editor is one of the highest-value features you can ship in 2026. Slack normalized the @mention pattern. Notion made it universal. Linear made it mandatory. Every modern collaborative product now uses it — type @, pick a user, insert a styled mention, trigger a notification. Users expect this pattern the moment they see a text field.

Building it in a React editor is harder than it looks. Naive implementations mishandle keyboard navigation. Mentions break when users edit or delete part of them. The autocomplete lags on teams over 1,000 users. Notification hooks fail silently when the mention data structure isn't right. And custom builds routinely take 1-2 weeks of senior engineering time when the plumbing goes wrong.

This guide shows you exactly how to add mentions to a React rich text editor in 2026 — the full pattern with autocomplete, fuzzy search, keyboard navigation, atomic mention nodes, and notification hooks. You'll get three working paths: custom Lexical build, custom TipTap build, and Eddyter native @mentions at $12-$59/mo flat, 10 minutes.

The short answer: For most React and Next.js teams in 2026, the fastest way to add mentions to a React rich text editor is Eddyter's built-in mentions prop — pass a fetchUsers function, get autocomplete + notification webhooks in 10 minutes. For teams needing full control over mention UX, custom builds in Lexical or TipTap take 1-2 weeks. Full working code for both paths is below.

What @Mentions Actually Does (The Full Pattern)

Before writing code, clarify what pattern you need. "@mentions" describes five features that work together:

1. Trigger Detection

Detect the @ character reliably. Ignore @ inside code blocks and URLs. Handle IME edge cases (Japanese, Chinese input methods that use different modifier keys).

2. Autocomplete Menu

Show a menu of users below the cursor as you type. Filter by name or username. Update as you keep typing.

3. Fuzzy Search

Users type @joh and expect "John Smith" to match. Users type @js and expect "John Smith" AND "Jane Sanders" to match. Fuzzy matching, not exact matching, feels correct.

4. Structured Insertion

Insert the mention as a structured node in the editor — not just styled text. This lets you:

• Prevent editing the middle of a mention (deleting one character deletes the whole mention)
• Extract mentioned user IDs from the document
• Style mentions distinctly
• Trigger notifications on save

5. Notification Webhook

When the document saves, extract all mentions. Send notifications to mentioned users. Do this reliably even when they've been added, removed, or re-added multiple times.

This guide covers all five. Building mentions without any one of them creates a broken experience.

The 7 Technical Challenges of Building @Mentions

Teams building mentions consistently hit these issues. Solving each is required for production.

1. Trigger After Whitespace Only

@ inside a word ("my@email.com") shouldn't trigger the picker. Only @ after whitespace or at line start should.

2. Menu Positioning at Screen Edges

At the bottom of the viewport, menu clips off. At the right edge, menu extends past the window. Calculate available space and flip direction.

3. Fuzzy Search Performance

Filtering 10 users is fast. Filtering 10,000 users on every keystroke lags. Debounce input, index the user list, or query the server for large teams.

4. Keyboard Navigation

Arrow up/down cycles users. Enter selects. Esc closes. Tab autocompletes. Escape must also close if user types printable characters that don't match.

5. Mention as Atomic Unit

Once inserted, the mention should behave as one character to the editor. Cmd+Backspace deletes the whole mention. Selecting inside a mention selects the whole mention.

6. Notification Deduplication

If the user mentions Jane, saves, then mentions Jane again in the same save, Jane should get one notification (not two). Deduplication logic matters.

7. Data Structure for Downstream Systems

Mentions in HTML need consistent format so notifications, search indexing, and analytics can extract them. Standard pattern: <span data-mention data-user-id="123">@Jane</span>.

For deeper AI-powered editor patterns, see our How to Add AI Autocomplete to a React Editor 2026 and How to Add AI Slash Commands to Any React Editor 2026.

Two Paths: Custom Build vs Eddyter

You have two production-ready paths in 2026:

The custom path gives total control over UX behavior, styling, and notification logic. Eddyter gives you production quality in 10 minutes.

Both paths are covered below with working code.

Path 1: Custom Build in Lexical (1-2 Weeks)

If you need full control over the mention UX, this is the pattern that works in 2026 with Lexical.

Step 1: Install Dependencies

bash

1
npm install lexical @lexical/react @lexical/utils

Lexical is Meta's editor framework. The @lexical/utils package provides helpers for node manipulation.

Step 2: Define the Mention Node

Create a custom node that represents a mention:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
// nodes/MentionNode.ts
import {
  $applyNodeReplacement,
  DecoratorNode,
  DOMConversionMap,
  DOMExportOutput,
  EditorConfig,
  LexicalNode,
  NodeKey,
  SerializedLexicalNode,
  Spread,
} from 'lexical';
import React, { JSX } from 'react';
export type SerializedMentionNode = Spread
  {
    mentionName: string;
    userId: string;
    type: 'mention';
    version: 1;
  },
  SerializedLexicalNode
>;
export class MentionNode extends DecoratorNode<JSX.Element> {
  __mentionName: string;
  __userId: string;
  static getType(): string {
    return 'mention';
  }
  static clone(node: MentionNode): MentionNode {
    return new MentionNode(node.__mentionName, node.__userId, node.__key);
  }
  constructor(mentionName: string, userId: string, key?: NodeKey) {
    super(key);
    this.__mentionName = mentionName;
    this.__userId = userId;
  }
  createDOM(): HTMLElement {
    const dom = document.createElement('span');
    dom.className = 'mention';
    dom.setAttribute('data-mention', 'true');
    dom.setAttribute('data-user-id', this.__userId);
    return dom;
  }
  updateDOM(): boolean {
    return false;
  }
  decorate(): JSX.Element {
    return (
      <span
        className="mention"
        data-mention="true"
        data-user-id={this.__userId}
      >
        @{this.__mentionName}
      </span>
    );
  }
  static importDOM(): DOMConversionMap | null {
    return {
      span: (node: HTMLElement) => {
        if (node.getAttribute('data-mention') !== 'true') return null;
        return {
          conversion: (domNode: HTMLElement) => {
            const userId = domNode.getAttribute('data-user-id') || '';
            const mentionName = domNode.textContent?.slice(1) || '';
            return {
              node: $createMentionNode(mentionName, userId),
            };
          },
          priority: 1,
        };
      },
    };
  }
  exportDOM(): DOMExportOutput {
    const element = document.createElement('span');
    element.setAttribute('data-mention', 'true');
    element.setAttribute('data-user-id', this.__userId);
    element.textContent = `@${this.__mentionName}`;
    return { element };
  }
  static importJSON(serialized: SerializedMentionNode): MentionNode {
    return $createMentionNode(serialized.mentionName, serialized.userId);
  }
  exportJSON(): SerializedMentionNode {
    return {
      mentionName: this.__mentionName,
      userId: this.__userId,
      type: 'mention',
      version: 1,
    };
  }
  isInline(): boolean {
    return true;
  }
  isIsolated(): boolean {
    return true;
  }
}
export function $createMentionNode(
  mentionName: string,
  userId: string
): MentionNode {
  return $applyNodeReplacement(new MentionNode(mentionName, userId));
}
export function $isMentionNode(
  node: LexicalNode | null | undefined
): node is MentionNode {
  return node instanceof MentionNode;
}

What this defines:

• DecoratorNode — Lexical renders this as a React component
• __mentionName and __userId — the two required properties
• isIsolated: true — makes the mention atomic (deleting one char deletes all)
• DOM export — produces <span data-mention data-user-id="123">@Jane</span> (standard format for downstream systems)
• JSON serialization — lets Lexical save and load the mention

Step 3: Create the Mention Menu Component

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
"use client";
import { useEffect, useRef, useState } from 'react';
export interface User {
  id: string;
  name: string;
  username: string;
  avatar?: string;
}
interface MentionMenuProps {
  position: { top: number; left: number };
  users: User[];
  onSelect: (user: User) => void;
  onClose: () => void;
}
export function MentionMenu({
  position,
  users,
  onSelect,
  onClose,
}: MentionMenuProps) {
  const [selectedIndex, setSelectedIndex] = useState(0);
  const menuRef = useRef<HTMLDivElement>(null);
  // Reset selection when user list changes
  useEffect(() => {
    setSelectedIndex(0);
  }, [users]);
  // Keyboard navigation
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if (users.length === 0) return;
      if (e.key === 'ArrowDown') {
        e.preventDefault();
        setSelectedIndex((i) => (i + 1) % users.length);
      } else if (e.key === 'ArrowUp') {
        e.preventDefault();
        setSelectedIndex((i) => (i - 1 + users.length) % users.length);
      } else if (e.key === 'Enter' || e.key === 'Tab') {
        e.preventDefault();
        onSelect(users[selectedIndex]);
      } else if (e.key === 'Escape') {
        e.preventDefault();
        onClose();
      }
    };
    window.addEventListener('keydown', handleKeyDown, { capture: true });
    return () => window.removeEventListener('keydown', handleKeyDown, { capture: true });
  }, [users, selectedIndex, onSelect, onClose]);
  // Scroll selected user into view
  useEffect(() => {
    const menuEl = menuRef.current;
    if (!menuEl) return;
    const selectedEl = menuEl.children[selectedIndex] as HTMLElement;
    if (selectedEl) {
      selectedEl.scrollIntoView({ block: 'nearest' });
    }
  }, [selectedIndex]);
  if (users.length === 0) {
    return (
      <div
        className="fixed z-50 w-72 bg-white border border-gray-200 rounded-lg shadow-lg p-3"
        style={{ top: position.top, left: position.left }}
      >
        <div className="text-sm text-gray-500">No users found</div>
      </div>
    );
  }
  return (
    <div
      ref={menuRef}
      className="fixed z-50 w-72 max-h-64 overflow-y-auto bg-white border border-gray-200 rounded-lg shadow-lg py-1"
      style={{ top: position.top, left: position.left }}
    >
      {users.map((user, i) => (
        <button
          key={user.id}
          onClick={() => onSelect(user)}
          onMouseEnter={() => setSelectedIndex(i)}
          className={`w-full flex items-center gap-3 px-3 py-2 text-left transition-colors ${
            i === selectedIndex ? 'bg-blue-50' : 'hover:bg-gray-50'
          }`}
        >
          {user.avatar ? (
            <img
              src={user.avatar}
              alt={user.name}
              className="w-8 h-8 rounded-full"
            />
          ) : (
            <div className="w-8 h-8 rounded-full bg-gray-200 flex items-center justify-center text-sm font-medium text-gray-600">
              {user.name.charAt(0).toUpperCase()}
            </div>
          )}
          <div className="flex-1 min-w-0">
            <div className="text-sm font-medium text-gray-900 truncate">
              {user.name}
            </div>
            <div className="text-xs text-gray-500 truncate">
              @{user.username}
            </div>
          </div>
        </button>
      ))}
    </div>
  );
}

What this component handles:

• Keyboard navigation — arrow keys cycle, Enter/Tab selects, Esc closes
• Mouse hover sync — hovering updates selected index
• Auto-scroll — selected item stays visible
• Empty state — clear message when no users match
• Avatar fallback — initials when no image provided
• Capture phase listener — prevents editor from consuming keyboard events first

Step 4: Fuzzy Search Utility

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// utils/fuzzy-search.ts
import { User } from '@/components/MentionMenu';
export function fuzzySearchUsers(users: User[], query: string): User[] {
  if (!query) return users.slice(0, 10);
  const q = query.toLowerCase();
  // Score each user
  const scored = users.map((user) => {
    const name = user.name.toLowerCase();
    const username = user.username.toLowerCase();
    // Exact matches score highest
    if (name === q || username === q) return { user, score: 100 };
    // Start-of-word matches score high
    if (name.startsWith(q) || username.startsWith(q)) return { user, score: 80 };
    // Word-boundary matches score medium
    const nameWords = name.split(' ');
    if (nameWords.some((w) => w.startsWith(q))) return { user, score: 60 };
    // Substring matches score lower
    if (name.includes(q) || username.includes(q)) return { user, score: 40 };
    // Character-in-order matches score lowest
    let ni = 0;
    let matched = 0;
    for (const char of q) {
      const found = name.indexOf(char, ni);
      if (found === -1) return { user, score: 0 };
      matched++;
      ni = found + 1;
    }
    return { user, score: matched * 5 };
  });
  return scored
    .filter((s) => s.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, 10)
    .map((s) => s.user);
}

What this does:

• Exact match = highest score
• Start-of-word match = high score
• Substring match = medium score
• Character-in-order match = low score (catches typos)
• Returns top 10 — never overwhelm the menu

Step 5: Build the Mention Plugin

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
"use client";
import { useEffect, useState, useCallback, useRef } from 'react';
import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
import {
  $getSelection,
  $isRangeSelection,
  $createTextNode,
  KEY_DOWN_COMMAND,
  COMMAND_PRIORITY_HIGH,
} from 'lexical';
import { MentionMenu, User } from './MentionMenu';
import { $createMentionNode } from '@/nodes/MentionNode';
import { fuzzySearchUsers } from '@/utils/fuzzy-search';
interface MentionPluginProps {
  users: User[]; // Or a fetch function for large teams
}
export function MentionPlugin({ users }: MentionPluginProps) {
  const [editor] = useLexicalComposerContext();
  const [isOpen, setIsOpen] = useState(false);
  const [filter, setFilter] = useState('');
  const [position, setPosition] = useState({ top: 0, left: 0 });
  const anchorOffsetRef = useRef(0);
  const filteredUsers = fuzzySearchUsers(users, filter);
  // Detect @ trigger
  useEffect(() => {
    return editor.registerCommand(
      KEY_DOWN_COMMAND,
      (event: KeyboardEvent) => {
        // Trigger on @
        if (event.key === '@' && !isOpen) {
          editor.getEditorState().read(() => {
            const selection = $getSelection();
            if (!$isRangeSelection(selection) || !selection.isCollapsed()) return;
            // Only trigger if preceded by whitespace or start of line
            const anchorNode = selection.anchor.getNode();
            const offset = selection.anchor.offset;
            const text = anchorNode.getTextContent();
            const charBefore = text[offset - 1];
            if (charBefore && !/\s/.test(charBefore)) return;
            const domSelection = window.getSelection();
            if (!domSelection || domSelection.rangeCount === 0) return;
            const range = domSelection.getRangeAt(0);
            const rect = range.getBoundingClientRect();
            setPosition({
              top: rect.bottom + 5,
              left: rect.left,
            });
            anchorOffsetRef.current = offset + 1;
            setIsOpen(true);
            setFilter('');
          });
        } else if (isOpen) {
          // Update filter as user types after @
          if (event.key.length === 1 && !event.metaKey && !event.ctrlKey) {
            // Don't intercept — let @ typed char flow to editor, then update filter
            setTimeout(() => setFilter((prev) => prev + event.key), 0);
          } else if (event.key === 'Backspace') {
            setFilter((prev) => {
              if (prev.length === 0) {
                setIsOpen(false);
                return prev;
              }
              return prev.slice(0, -1);
            });
          } else if (event.key === ' ' || event.key === 'Escape') {
            setIsOpen(false);
          }
        }
        return false;
      },
      COMMAND_PRIORITY_HIGH
    );
  }, [editor, isOpen]);
  // Insert mention when selected
  const handleSelect = useCallback(
    (user: User) => {
      editor.update(() => {
        const selection = $getSelection();
        if (!$isRangeSelection(selection)) return;
        const anchorNode = selection.anchor.getNode();
        const offset = selection.anchor.offset;
        const triggerLength = filter.length + 1; // @ + typed chars
        // Delete the @filter text
        if (anchorNode.getType() === 'text') {
          const text = anchorNode.getTextContent();
          const newText =
            text.slice(0, offset - triggerLength) + text.slice(offset);
          (anchorNode as any).setTextContent(newText);
        }
        // Insert mention node
        const mentionNode = $createMentionNode(user.name, user.id);
        selection.insertNodes([mentionNode]);
        // Insert space after mention
        selection.insertNodes([$createTextNode(' ')]);
      });
      setIsOpen(false);
      setFilter('');
    },
    [editor, filter]
  );
  if (!isOpen) return null;
  return (
    <MentionMenu
      position={position}
      users={filteredUsers}
      onSelect={handleSelect}
      onClose={() => setIsOpen(false)}
    />
  );
}

What this plugin does:

• Detects @ — only after whitespace or line start
• Positions menu — below current cursor
• Updates filter — as user types after @
• Handles Backspace — closes menu if backspaced past @
• Handles Space/Escape — closes menu without inserting
• Inserts mention — removes typed text, adds structured node, adds space

Step 6: Wire Everything Up

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
"use client";
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
import LexicalErrorBoundary from '@lexical/react/LexicalErrorBoundary';
import { MentionPlugin } from './MentionPlugin';
import { MentionNode } from '@/nodes/MentionNode';
const users = [
  { id: '1', name: 'Jane Smith', username: 'jane', avatar: '/avatars/jane.jpg' },
  { id: '2', name: 'John Doe', username: 'john', avatar: '/avatars/john.jpg' },
  { id: '3', name: 'Alice Johnson', username: 'alice', avatar: '/avatars/alice.jpg' },
  // ...
];
export default function EditorWithMentions() {
  const initialConfig = {
    namespace: 'mention-editor',
    onError: (error: Error) => console.error(error),
    nodes: [MentionNode],
    theme: {
      mention: 'mention-token',
    },
  };
  return (
    <LexicalComposer initialConfig={initialConfig}>
      <div className="relative border rounded-lg p-4">
        <RichTextPlugin
          contentEditable={
            <ContentEditable className="outline-none min-h-32" />
          }
          placeholder={
            <div className="text-gray-400 absolute top-4 left-4 pointer-events-none">
              Type @ to mention someone...
            </div>
          }
          ErrorBoundary={LexicalErrorBoundary}
        />
        <HistoryPlugin />
        <MentionPlugin users={users} />
      </div>
    </LexicalComposer>
  );
}

Step 7: Add CSS Styling

css

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/* mention.css */
.mention {
  display: inline-block;
  padding: 2px 6px;
  background-color: #dbeafe;
  color: #1e40af;
  border-radius: 4px;
  font-weight: 500;
  cursor: pointer;
  user-select: all;
  white-space: nowrap;
}
.mention:hover {
  background-color: #bfdbfe;
}

That's the full custom Lexical implementation. Type @ and the user picker opens. Filter by typing. Enter to insert. Mention appears as a styled atomic node.

Step 8: Extract Mentions for Notifications

When the document saves, extract all mentions to send notifications:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// utils/extract-mentions.ts
export function extractMentions(html: string): { userId: string; name: string }[] {
  const parser = new DOMParser();
  const doc = parser.parseFromString(html, 'text/html');
  const mentionElements = doc.querySelectorAll('[data-mention="true"]');
  const mentions = new Map<string, string>();
  mentionElements.forEach((el) => {
    const userId = el.getAttribute('data-user-id');
    const name = el.textContent?.replace(/^@/, '') || '';
    if (userId) mentions.set(userId, name);
  });
  return Array.from(mentions.entries()).map(([userId, name]) => ({
    userId,
    name,
  }));
}

Then wire it into your save handler:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
async function saveDocument(html: string, documentId: string) {
  // Save the document
  await saveToDatabase(documentId, html);
  // Extract and notify mentions
  const mentions = extractMentions(html);
  for (const mention of mentions) {
    await sendNotification({
      userId: mention.userId,
      type: 'mention',
      documentId,
      message: `You were mentioned in a document`,
    });
  }
}

The Real Cost of Custom Lexical Mentions

Production-quality mentions built this way typically takes 1-2 weeks and costs:

Plus opportunity cost: 1-2 weeks of senior engineering time is $6K-$12K in salary alone.

For build-vs-buy analysis, see Build vs Buy: Real Cost of Building a Rich Text Editor 2026 and Why Building Your Own Rich Text Editor Is a Startup Killer.

Path 1B: Custom Build in TipTap (1-2 Weeks)

If you're already on TipTap, the pattern uses TipTap's official Mention extension.

Install the Mention Extension

bash

1
npm install @tiptap/extension-mention @tiptap/suggestion tippy.js

Basic Setup

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
"use client";
import { EditorContent, useEditor, ReactRenderer } from '@tiptap/react';
import StarterKit from '@tiptap/starter-kit';
import Mention from '@tiptap/extension-mention';
import tippy from 'tippy.js';
import { MentionList } from './MentionList';
const users = [
  { id: '1', name: 'Jane Smith', username: 'jane' },
  { id: '2', name: 'John Doe', username: 'john' },
  { id: '3', name: 'Alice Johnson', username: 'alice' },
];
export default function TipTapMentionEditor() {
  const editor = useEditor({
    extensions: [
      StarterKit,
      Mention.configure({
        HTMLAttributes: {
          class: 'mention',
        },
        suggestion: {
          items: ({ query }) => {
            return users
              .filter((user) =>
                user.name.toLowerCase().includes(query.toLowerCase())
              )
              .slice(0, 10);
          },
          render: () => {
            let component: ReactRenderer;
            let popup: any;
            return {
              onStart: (props) => {
                component = new ReactRenderer(MentionList, {
                  props,
                  editor: props.editor,
                });
                popup = tippy('body', {
                  getReferenceClientRect: props.clientRect as any,
                  appendTo: () => document.body,
                  content: component.element,
                  showOnCreate: true,
                  interactive: true,
                  trigger: 'manual',
                  placement: 'bottom-start',
                });
              },
              onUpdate: (props) => {
                component.updateProps(props);
                popup[0].setProps({
                  getReferenceClientRect: props.clientRect as any,
                });
              },
              onKeyDown: (props) => {
                if (props.event.key === 'Escape') {
                  popup[0].hide();
                  return true;
                }
                return (component.ref as any)?.onKeyDown?.(props);
              },
              onExit: () => {
                popup[0].destroy();
                component.destroy();
              },
            };
          },
        },
      }),
    ],
  });
  return <EditorContent editor={editor} />;
}

TipTap's official Mention extension handles trigger detection, positioning, and node insertion. You write the menu component and the users list.

For the MentionList component, use a similar pattern to the Lexical MentionMenu component from Step 3.

Path 2: Eddyter Built-In @Mentions (10 Minutes)

If mentions are a feature (not your core product), Eddyter ships them in 10 minutes with autocomplete, notification webhooks, and multi-framework support.

Step 1: Get Your Eddyter API Key

Visit eddyter.com/user/license-key. Copy your key. Add it to .env.local:

bash

1
NEXT_PUBLIC_EDDYTER_API_KEY=your-eddyter-api-key

Step 2: Install Eddyter

bash

1
npm install eddyter

Step 3: Render the Editor with Mentions Enabled

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
"use client";
import {
  ConfigurableEditorWithAuth,
  EditorProvider,
} from 'eddyter';
import 'eddyter/style.css';
export default function EditorWithMentions() {
  const apiKey = process.env.NEXT_PUBLIC_EDDYTER_API_KEY;
  const handleContentChange = (html: string) => {
    console.log('Editor content:', html);
  };
  return (
    <EditorProvider>
      <ConfigurableEditorWithAuth
        apiKey={apiKey}
        mentions={{
          enabled: true,
          fetchUsers: async (query) => {
            // Fetch matching users from your backend
            const response = await fetch(`/api/users/search?q=${query}`);
            return response.json();
            // Should return: [{ id, name, username, avatar }]
          },
          onMention: (mentionedUser, documentId) => {
            // Called when a mention is inserted
            console.log(`${mentionedUser.name} was mentioned`);
          },
        }}
        onChange={handleContentChange}
      />
    </EditorProvider>
  );
}

That's it. Type @ and the user picker opens. Fetch users from your backend. Pick a user. Structured mention node inserts. All keyboard behavior matches Slack/Notion conventions. Works in React 18.2+/19 and Next.js 14/15.

Backend Notification Webhook

Configure Eddyter to send a webhook when mentions are saved:

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// app/api/eddyter-webhook/route.ts
export async function POST(req: Request) {
  const payload = await req.json();
  // Verify webhook signature (Eddyter signs webhooks)
  if (!verifyWebhookSignature(payload)) {
    return new Response('Invalid signature', { status: 401 });
  }
  if (payload.event === 'mention.created') {
    const { mentionedUserId, documentId, mentionerUserId } = payload.data;
    await sendNotification({
      userId: mentionedUserId,
      type: 'mention',
      documentId,
      mentionerUserId,
      message: `You were mentioned in a document`,
    });
  }
  return new Response('OK');
}

Small Teams: Static User List

For teams under 100 users, skip the fetchUsers function and pass a static list:

tsx

1
2
3
4
5
6
7
8
9
10
11
<ConfigurableEditorWithAuth
  apiKey={apiKey}
  mentions={{
    enabled: true,
    users: [
      { id: '1', name: 'Jane Smith', username: 'jane', avatar: '/avatars/jane.jpg' },
      { id: '2', name: 'John Doe', username: 'john', avatar: '/avatars/john.jpg' },
      // ...
    ],
  }}
/>

Eddyter handles fuzzy search on the static list automatically.

Customizing Mention Appearance

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
<ConfigurableEditorWithAuth
  apiKey={apiKey}
  mentions={{
    enabled: true,
    fetchUsers: async (query) => fetchMatchingUsers(query),
    styles: {
      backgroundColor: '#dbeafe',
      color: '#1e40af',
      borderRadius: '4px',
      padding: '2px 6px',
    },
  }}
/>

For deeper integration patterns, see Eddyter's docs and Best Rich Text Editor for Chat & Messaging Apps 2026.

🎥 See real Eddyter setup: Integrate Eddyter in 30 Minutes with Cursor, Claude, Lovable

Custom Build vs Eddyter: Full Comparison

The pattern: Custom builds make sense when mention UX is your core differentiator (Slack, Linear, Discord). Eddyter makes sense when mentions are a feature (SaaS with commenting, docs, project management).

3-Year Cost Math: Real Numbers

For a typical React SaaS with team-based mentions:

Custom Build (Self-Hosted)

• Senior engineering (1.5 weeks initial build): $9,000
• User search backend (API endpoint, indexing): $3,000
• Notification service integration: $2,000
• Ongoing maintenance (bug fixes, edge cases, ~4 hours/mo × $150/hr × 36 mo): $21,600
• 3-year total: $35,600

Eddyter AI Pro Managed

• Base plan: $59/mo × 36 = $2,124
• Includes: mentions with fetchUsers hook, notification webhooks, ongoing updates, multi-framework support
• 3-year total: $2,124

The Real Savings

• vs Custom build: Eddyter saves $33,476 over 3 years (94% cost reduction)

Plus 1-2 weeks of senior engineering time freed for actual product work.

5-Question Decision Framework

Use this to decide which path fits your team:

1. Are mentions your core product differentiator?

Yes → Custom build. If users choose your product BECAUSE of unique mention behavior (Slack's channels, Discord's roles), you need total UX control.

No → Eddyter. If mentions are a feature that makes your existing product better, managed mentions deliver 95% of the value with 5% of the engineering cost.

2. What frameworks does your product use?

React only → Either path works.

Multi-framework → Eddyter. Custom builds require per-editor implementation. Eddyter supports 7 frameworks natively.

3. Do you have engineering bandwidth for 1-2 weeks of work?

Yes + no other priorities → Custom build possible.

No → Eddyter. 10-minute setup vs 1-2 weeks is a 500x time saving.

4. Do you have complex mention rules?

Role-based mentions (@team-lead, @project-alpha) → Custom build. More flexibility for group and rule-based mentions.

Standard @user mentions → Eddyter. Config-based approach handles the standard case.

5. How large is your user base?

Under 100 users → Either works with static list.

100-10,000 users → Either works with fetch function.

Over 10,000 users → Consider Eddyter or invest more in search infrastructure. Fuzzy search at scale requires more engineering with custom builds.

7 Common Mention Pitfalls

Teams building mentions consistently hit these issues. Solving each is required for production.

Pitfall 1: Triggering @ Inside Emails/URLs

my@email.com shouldn't trigger the picker. Neither should URLs like https://github.com/@username.

Fix: Only trigger @ after whitespace or at line start. Check the character before @ in your trigger detection.

Pitfall 2: Menu Positioning at Screen Bottom

At the bottom of the viewport, menu clips off. Users can't see the users to pick.

Fix: Calculate available space below cursor. If less than 300px, position menu above cursor instead.

Pitfall 3: Fuzzy Search Lag on Large Teams

Filtering 10,000 users on every keystroke lags. Users see stale results.

Fix: Debounce input to 100-200ms. For large teams, query the server with the fuzzy query instead of filtering client-side.

Pitfall 4: Mention Not Atomic

Users edit the middle of "Jane" and it becomes "Jne" — but the mention node still says user ID 123 for Jane. Data integrity breaks.

Fix: Make mention nodes atomic. In Lexical: isIsolated: true. In TipTap: atom: true. Deleting one character deletes the whole mention.

Pitfall 5: Duplicate Notifications

User mentions Jane, saves, edits, mentions Jane again, saves. Jane gets two notifications for the same document edit session.

Fix: Deduplicate mentions per save. Use a Map keyed by user ID. Alternatively, deduplicate at the notification service level (only send one notification per user per document per hour).

Pitfall 6: No HTML Standard for Extraction

Different implementations output different mention markup. Notification services can't extract consistently.

Fix: Use the standard pattern: <span data-mention data-user-id="123">@Jane</span>. Every mention extractor supports this pattern.

Pitfall 7: No Support for Groups/Roles

Users type @everyone or @team-eng and expect it to work. Naive implementations only support individual users.

Fix: Add a type field to your mention data: type: 'user' | 'group' | 'role'. Handle each type in notification dispatch.

Advanced Patterns

Mention with Preview Card

Show a preview card when hovering a mention:

tsx

1
2
3
4
5
6
7
8
9
<span
  className="mention"
  data-mention="true"
  data-user-id={userId}
  onMouseEnter={() => showPreview(userId)}
  onMouseLeave={() => hidePreview()}
>
  @{name}
</span>

Group Mentions

Support @team-lead style group mentions:

typescript

1
2
3
4
5
const mentionTypes = {
  user: { icon: '👤', color: 'blue' },
  group: { icon: '👥', color: 'purple' },
  role: { icon: '🎯', color: 'green' },
};

When rendering, use the type to determine icon and color.

Cross-Document Mentions

Support mentioning a document with [[:

typescript

1
2
3
// Trigger both @ (users) and [[ (documents)
if (event.key === '@') openUserMention();
if (event.key === '[' && lastKeyPressed === '[') openDocumentMention();

Notion uses this pattern for backlinks.

Frequently Asked Questions

1. What's the best React editor for @mentions in 2026?

For most React apps in 2026, Eddyter delivers the strongest mention experience — built-in fuzzy search, keyboard navigation, notification webhooks, 10-minute setup, $12-$59/mo flat pricing, and native support across 7 frameworks (React, Next.js, Vue 3, Angular 17-20, Svelte 4/5, Laravel, Vanilla JS). For custom mention UX with total control, Lexical + custom MentionNode is the strongest path (1-2 weeks engineering, free MIT foundation). TipTap + @tiptap/extension-mention is the second choice for custom builds — the official extension handles most of the tedious work. Skip building mentions from scratch on Slate — the ecosystem support is thinner.

2. How long does it take to add @mentions to a React editor?

Adding production-quality @mentions to a React editor takes 1-2 weeks of engineering time in 2026. This covers: mention node definition (2-3 days), autocomplete menu UI with keyboard navigation (2-3 days), fuzzy search implementation or backend integration (2-3 days), atomic node behavior and edge cases (2-3 days), notification webhook integration (2-3 days), and QA (2-3 days). Total 3-year cost including engineering and infrastructure: $15,000-$35,000+. Eddyter delivers equivalent mentions in 10 minutes at $2,124 over 3 years.

3. Can I add @mentions to an existing Lexical or TipTap editor?

Yes. Lexical requires defining a custom DecoratorNode for the mention and building a plugin for trigger detection and menu positioning (~1-2 weeks). TipTap has an official @tiptap/extension-mention package that handles the trigger, node insertion, and positioning — you provide the menu component and user list (~3-5 days for basic implementation). Slate requires custom void element definition and manual menu positioning (~1-2 weeks). For teams wanting to skip integration work, Eddyter is built on Lexical with mentions included natively — 10-minute setup with fetch-user hook and notification webhooks.

4. How do I handle mentions for large teams (10,000+ users)?

For large teams, don't filter client-side — query the server. Setup: as user types after @, send a debounced fuzzy search request to your backend. Backend uses PostgreSQL trigram search, Elasticsearch, or Algolia for fast fuzzy matching. Return top 10 matches to display in the menu. Debounce to 100-200ms to avoid excessive requests. Cache recent results to feel snappier. Eddyter's fetchUsers prop handles this pattern natively — you implement the search endpoint, Eddyter handles the UI, debouncing, and menu rendering. For teams under 100 users, static client-side filtering with fuzzy search is faster and simpler.

5. How do I send notifications when someone is mentioned?

Extract mentions from the document on save, then trigger notifications for each mentioned user. Custom pattern: parse the document HTML, find all <span data-mention="true"> elements, extract user IDs from data-user-id attributes, dedupe by user ID, send notifications via your notification service (Email, Slack, in-app, or push). Eddyter's onMention callback fires when mentions are inserted — pass it to your notification service directly. Deduplicate mentions per save to avoid double-notifying users who are mentioned multiple times in the same edit session.

6. How do I prevent mentions from being edited or broken?

Make mention nodes atomic — deleting one character deletes the whole mention. In Lexical: set isIsolated: true on your DecoratorNode. In TipTap: use atom: true in the extension config. In Slate: define the mention as a void element. This prevents users from accidentally corrupting mention data by editing the middle of a mention. Also make mentions non-editable so users can't type inside them. Set contenteditable="false" on the mention DOM element in all three editors.

7. Can I customize how mentions look?

Yes, in all three paths. Lexical — customize the createDOM method and decorate component to render your styling. Use CSS class .mention for global styles. TipTap — pass HTMLAttributes: { class: 'my-mention-class' } to the Mention extension config. Eddyter — pass a styles object to the mentions prop with backgroundColor, color, borderRadius, padding. All three support CSS customization for hover states, active states, and different mention types (user vs group vs role).

8. What's the alternative to building custom @mentions?

The strongest managed alternative in 2026 is Eddyter — built on Meta's Lexical framework with mentions included natively, 10-minute setup, notification webhooks, fetchUsers hook for backend integration, and native support across 7 frameworks at $12-$59/mo flat pricing. Other managed options exist with trade-offs: TipTap's official Mention extension works but requires 3-5 days of integration work plus $49-$999/mo Cloud pricing for advanced features. CKEditor 5 Mentions plugin works for enterprise at $144-$864/mo Cloud pricing. For most React and Next.js teams in 2026, Eddyter delivers the strongest cost-to-quality ratio for mentions specifically.

Ready to Ship @Mentions?

Stop engineering trigger detection, autocomplete menus, fuzzy search, atomic nodes, and notification webhooks from scratch. Deploy Eddyter into your React or Next.js product today — @mentions with autocomplete, notification hooks, and multi-framework support built in, $12-$59/mo flat pricing, unlimited users, 10-minute setup.

👉 Try Eddyter free at eddyter.com
📚 Read the docs
💰 See pricing
🎥 Watch the intro video | Watch the 30-min integration guide