Add @Mentions

Format @mentions with styled tokens, suggestion lists, and click handling

AI Agent Component Spec

{
  "package": "@cometchat/chat-uikit-react",
  "keyClass": "CometChatMentionsFormatter",
  "extends": "CometChatTextFormatter",
  "purpose": "Format @mentions with styled tokens, suggestion list, and click handling for users and group members"
}

Overview

CometChatMentionsFormatter formats @mentions in text messages. It styles mention tokens, generates suggestion lists as users type, and handles click events on rendered mentions.

Time estimate: 10 minutes
Difficulty: Intermediate

Prerequisites

• React.js integration completed
• Custom Formatters guide reviewed

Steps

Step 1: Import the formatter

import { CometChatMentionsFormatter } from "@cometchat/chat-uikit-react";

Step 2: Initialize with users

Set up the formatter with a list of mentionable users:

import { CometChatMentionsFormatter } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

// Get users or group members
const users = await CometChat.fetchUsers(
  new CometChat.UsersRequestBuilder().setLimit(50).build()
);

const mentionsFormatter = new CometChatMentionsFormatter();
mentionsFormatter.setCometChatUserGroupMembers(users);

Step 3: Pass to components

Use the textFormatters prop on message components:

import {
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function ChatWithMentions({ user }: { user: CometChat.User }) {
  const mentionsFormatter = new CometChatMentionsFormatter();
  
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
      <CometChatMessageList 
        user={user}
        textFormatters={[mentionsFormatter]}
      />
      <CometChatMessageComposer 
        user={user}
        textFormatters={[mentionsFormatter]}
      />
    </div>
  );
}

Step 4: Format existing messages

Apply formatting to raw message text:

const unformattedMessage = "<@uid:alice123> just shared a photo!";
const formattedMessage = mentionsFormatter.getFormattedText(unformattedMessage);
// Returns HTML with styled mention tokens

Complete Example

import { useEffect, useState } from "react";
import {
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
  CometChatMentionsFormatter,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import "@cometchat/chat-uikit-react/css-variables.css";

function MentionsChat() {
  const [group, setGroup] = useState<CometChat.Group>();
  const [members, setMembers] = useState<CometChat.GroupMember[]>([]);
  const [formatter, setFormatter] = useState<CometChatMentionsFormatter>();

  useEffect(() => {
    const init = async () => {
      // Get group
      const grp = await CometChat.getGroup("GROUP_GUID");
      setGroup(grp);

      // Get group members for mentions
      const membersRequest = new CometChat.GroupMembersRequestBuilder(grp.getGuid())
        .setLimit(100)
        .build();
      const membersList = await membersRequest.fetchNext();
      setMembers(membersList);

      // Initialize formatter with members
      const mentionsFormatter = new CometChatMentionsFormatter();
      mentionsFormatter.setCometChatUserGroupMembers(membersList);
      setFormatter(mentionsFormatter);
    };

    init();
  }, []);

  if (!group || !formatter) return <div>Loading...</div>;

  return (
    <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
      <CometChatMessageHeader group={group} />
      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList 
          group={group}
          textFormatters={[formatter]}
        />
      </div>
      <CometChatMessageComposer 
        group={group}
        textFormatters={[formatter]}
      />
    </div>
  );
}

export default MentionsChat;

Capabilities

Feature	Description
Mention formatting	Auto-formats <@uid:...> placeholders into styled tokens
Custom styles	Colors, fonts, and backgrounds for mention text
User and group mentions	Works with both individual users and group members
Suggestion list	Generates mention candidates from user input
Click handling	Listener interface for tap/click on rendered mentions

Common Issues

The formatter needs a list of users/members to generate suggestions. Make sure to call setCometChatUserGroupMembers() before using.

Issue	Solution
No suggestions appearing	Verify users are set via setCometChatUserGroupMembers()
Mentions not styled	Check formatter is passed to textFormatters prop
Wrong users in suggestions	Update user list when group membership changes

Next Steps

Shortcut Formatter

Add text expansion shortcuts

URL Formatter

Auto-link URLs in messages

Related Guides

Custom Formatters

Message Composer

Message List