Use user mentions

Detect @mention triggers, fetch user suggestions, and track mentioned users in text input

Overview

useUserMentions manages the full @mention flow inside a text input. It monitors the cursor position and content, detects when the user is typing an @mention, debounces a search call, and returns suggestions to display. When the user selects a suggestion, it inserts the username into the content and tracks the mention.

This hook is intended to be used alongside a controlled text input where you manage the content and cursor position.

Usage Example

import { useUserMentions } from "@sublay/react-js";
import { useState, useRef } from "react";

function CommentInput() {
  const [content, setContent] = useState("");
  const [cursorPosition, setCursorPosition] = useState(0);
  const [isSelectionActive, setIsSelectionActive] = useState(false);
  const inputRef = useRef<HTMLTextAreaElement>(null);

  const {
    isMentionActive,
    loading,
    mentionSuggestions,
    handleMentionClick,
    mentions,
  } = useUserMentions({
    content,
    setContent,
    focus: () => inputRef.current?.focus(),
    cursorPosition,
    isSelectionActive,
  });

  return (
    <div>
      <textarea
        ref={inputRef}
        value={content}
        onChange={(e) => setContent(e.target.value)}
        onSelect={(e) => {
          const target = e.target as HTMLTextAreaElement;
          setCursorPosition(target.selectionStart);
          setIsSelectionActive(target.selectionStart !== target.selectionEnd);
        }}
      />
      {isMentionActive && (
        <ul>
          {loading && <li>Loading...</li>}
          {mentionSuggestions.map((user) => (
            <li key={user.id} onClick={() => handleMentionClick(user)}>
              {user.username}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Props

content · string · required

The current text content of the input.

setContent · (value: string) => void · required

Setter for the content. Called when a mention is selected and the username is inserted.

focus · () => void · required

A function that re-focuses the input. Called after a mention is selected.

cursorPosition · number · required

The current cursor position (character index) within the content.

isSelectionActive · boolean · required

Whether the user has text selected. Mention detection is suppressed while a selection is active.

trigger · string

The character that activates mention mode. Defaults to "@".

minChars · number

Minimum characters after the trigger before fetching suggestions. Defaults to 3.

debounceDelay · number

Milliseconds to wait after the user stops typing before fetching suggestions. Defaults to 1000.

validPattern · string

Regex pattern (as a string) that the text after the trigger must match. Defaults to "[\\w.]+".

Return Values

isMentionActive · boolean

true when the cursor is inside a valid mention trigger sequence.

loading · boolean

true while user suggestions are being fetched.

mentionSuggestions · User[]

The list of matching users to display as suggestions.

handleMentionClick · (user: User) => void

Call this when the user selects a suggestion. Replaces the trigger text in content with the user’s username, adds the user to mentions, and closes the suggestion list.

mentions · Mention[]

Accumulated list of confirmed mentions in the current content. Each entry has id, foreignId, username, and type: "user".

addMention · (user: User) => void

Manually adds a user to the mentions list. Used internally by handleMentionClick.

resetMentions · () => void

Clears the mentions list and resets all mention state. Call this after the content is submitted.