> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-angular-v5-docs-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mentions Formatter

> Add @mentions with user suggestions and styled tokens in CometChat Flutter UI Kit.

<Accordion title="AI Agent Component Spec">
  | Field      | Value                                                                                                                                                                                                       |
  | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Package    | `cometchat_chat_uikit`                                                                                                                                                                                      |
  | Key class  | `CometChatMentionsFormatter` (extends `CometChatTextFormatter`)                                                                                                                                             |
  | Init       | `CometChatUIKit.init(uiKitSettings)` then `CometChatUIKit.login(uid)`                                                                                                                                       |
  | Purpose    | Add @mentions with user suggestions, styled tokens, and click handling                                                                                                                                      |
  | Sample app | [GitHub](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app)                                                                                                                           |
  | Related    | [Custom Text Formatter](/ui-kit/flutter/v5/custom-text-formatter-guide) · [Custom Mentions Formatter](/ui-kit/flutter/v5/custom-mentions-formatter-guide) · [All Guides](/ui-kit/flutter/v5/guide-overview) |
</Accordion>

## Overview

The `CometChatMentionsFormatter` class is a part of the CometChat UI Kit, a ready-to-use chat UI widget library for integrating CometChat into your Android applications. This class provides functionality to format mentions within text messages displayed in the chat interface. Mentions allow users to reference other users within a conversation, providing a convenient way to direct messages or involve specific participants.

<Tabs>
  <Tab title="Android">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/p231kj41ev7n6i2F/images/63a51e9f-mentions_features_cometchat_extension_cometchat-065eac6abd3a68ebd1e236672684de0b.png?fit=max&auto=format&n=p231kj41ev7n6i2F&q=85&s=674e68cdfe94a36c1f85de0c648cca8b" alt="Image" width="4500" height="3130" data-path="images/63a51e9f-mentions_features_cometchat_extension_cometchat-065eac6abd3a68ebd1e236672684de0b.png" />
  </Tab>

  <Tab title="iOS">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/hS2ODI36gzqSC7wJ/images/bc593411-mentions_features_cometchat_extension_cometchat-6dbeeaf67ee4c8ecf9bfbf7e19bc88c9.png?fit=max&auto=format&n=hS2ODI36gzqSC7wJ&q=85&s=d83aa273b48fa3ca9f512c4fc5fc439f" alt="Image" width="4508" height="3130" data-path="images/bc593411-mentions_features_cometchat_extension_cometchat-6dbeeaf67ee4c8ecf9bfbf7e19bc88c9.png" />
  </Tab>
</Tabs>

## Features

* **Mention Formatting**: Automatically formats mentions within text messages based on provided styles and settings.
* **Customizable Styles**: Allows customization of text styles for mentions, including colors, fonts, and background colors.
* **User and Group Member Mentions**: Supports mentions for both individual users and group members, providing flexibility in communication scenarios.
* **Mention List Generation**: Generates a list of suggested mentions based on user input, facilitating easy selection of recipients during message composition.
* **Mention Click Handling**: Provides a listener interface for handling click events on mentions, enabling custom actions to be performed when a mention is tapped by the user.

## Usage

To integrate the `CometChatMentionsFormatter` class into your application:

1. **Initialization**: Create an instance of the `CometChatMentionsFormatter` class and configure it with desired settings, such as mention text styles and limit settings.

2. **Set Mention Listeners**: Set listeners for handling mention click events (`setOnMentionClick`).

3. **Format Messages**: Use the `prepareLeftMessageBubbleSpan`, `prepareRightMessageBubbleSpan`, `prepareComposerSpan`, and `prepareConversationSpan` methods to format text messages with mentions appropriately for display in the chat interface.

4. **Customization**: Customize the appearance and behavior of mentions by adjusting the text styles, colors, and other formatting properties as needed.

Below is an example demonstrating how to use the `CometChatMentionsFormatter` class in widgets such as [CometChatConversations](/ui-kit/flutter/v5/conversations), [CometChatMessageList](/ui-kit/flutter/v5/message-list), [CometChatMessageComposer](/ui-kit/flutter/v5/message-composer).

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    textFormatters: [
        CometChatMentionsFormatter(
          messageBubbleTextStyle: (theme, alignment,{forConversation = false}) => 
            TextStyle(
                color: alignment==BubbleAlignment.left? Colors.orange : Colors.pink,
                fontSize: 14,
                fontWeight: FontWeight.bold
            ),
        )
    ]
    ```
  </Tab>
</Tabs>

***

## Actions

[Actions](/ui-kit/flutter/v5/components-overview#actions) dictate how a widget functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the widget to fit your specific needs.

##### onMentionTap

Setting a listener for mention-click events in Message Bubbles enhances interactivity within the chat. This listener is activated when a mention is clicked, returning the corresponding user object. This feature transforms mentions into interactive links, enabling more in-depth and contextual engagement with the user associated with the clicked mention.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessages(
      user: user,
      messageListConfiguration: MessageListConfiguration(
          textFormatters: [
            CometChatMentionsFormatter(
              onMentionTap: (mention, mentionedUser, {message}) {
                final snackBar = SnackBar(
                  content: const Text('Tap on Mentioned User', style: TextStyle(color: Colors.lightBlueAccent)),
                  action: SnackBarAction(
                    label: 'Undo',
                    onPressed: () {
                      // TODO("Not yet implemented")
                    },
                  ),
                );
                ScaffoldMessenger.of(context).showSnackBar(snackBar);
              },
              messageBubbleTextStyle: (theme, alignment,{forConversation = false}) => TextStyle(
                  color: alignment==BubbleAlignment.left? Colors.orange : Colors.greenAccent,
                  fontSize: 14,
                  fontWeight: FontWeight.bold
              ),
            )
          ]
      ),
    )
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Android">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/7FrH1XBoyJH8fE7_/images/e0eef750-mentions_formatter_on_tap_cometchat_screens-b0c3aee12dd33935a7b03b11ccf6b084.png?fit=max&auto=format&n=7FrH1XBoyJH8fE7_&q=85&s=e3ffb452f634d09861c88d309a1e1bce" alt="Image" width="4498" height="3121" data-path="images/e0eef750-mentions_formatter_on_tap_cometchat_screens-b0c3aee12dd33935a7b03b11ccf6b084.png" />
  </Tab>

  <Tab title="iOS">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/QcHXltXFKjSg4WPo/images/d2225e4b-mentions_formatter_on_tap_cometchat_screens-35f6be714492b2ddd2dfc5ef544a3d0b.png?fit=max&auto=format&n=QcHXltXFKjSg4WPo&q=85&s=137901526d88625ab62f1a1cf93c58cd" alt="Image" width="4498" height="3121" data-path="images/d2225e4b-mentions_formatter_on_tap_cometchat_screens-35f6be714492b2ddd2dfc5ef544a3d0b.png" />
  </Tab>
</Tabs>

***

## Customization

| **Property**                   | **Description**                                                | **Code**                                                 |
| ------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------- |
| **trackingCharacter**          | The character that triggers the mention search.                | `String? trackingCharacter`                              |
| **pattern**                    | The regex pattern to identify mentions.                        | `RegExp? pattern`                                        |
| **showLoadingIndicator**       | Whether to show a loading indicator during mention search.     | `bool? showLoadingIndicator`                             |
| **onSearch**                   | Callback function to perform search when mention is triggered. | `void Function(String)? onSearch`                        |
| **onError**                    | Callback function to handle errors during mention search.      | `void Function(String)? onError`                         |
| **message**                    | The message in which mentions are to be formatted.             | `String? message`                                        |
| **messageBubbleTextStyle**     | The text style for the message bubble.                         | `TextStyle? messageBubbleTextStyle`                      |
| **messageInputTextStyle**      | The text style for the message input.                          | `TextStyle? messageInputTextStyle`                       |
| **composerId**                 | The unique identifier for the composer.                        | `String? composerId`                                     |
| **suggestionListEventSink**    | The event sink for the suggestion list.                        | `EventSink<List<User>>? suggestionListEventSink`         |
| **previousTextEventSink**      | The event sink for the previous text before mention.           | `EventSink<String>? previousTextEventSink`               |
| **user**                       | The user to be mentioned.                                      | `User? user`                                             |
| **group**                      | The group in which mentions are to be formatted.               | `Group? group`                                           |
| **groupMembersRequestBuilder** | The request builder for fetching group members to mention.     | `GroupMembersRequestBuilder? groupMembersRequestBuilder` |
| **usersRequestBuilder**        | The request builder for fetching users to mention.             | `UsersRequestBuilder? usersRequestBuilder`               |
| **mentionsType**               | The type of mentions (e.g., user, group).                      | `MentionsType? mentionsType`                             |
| **onMentionTap**               | Callback function to handle mention tap actions.               | `void Function(User)? onMentionTap`                      |
| **visibleIn**                  | Defines where the mentions are visible.                        | `Set<ComposerMentionVisibility>? visibleIn`              |
| **style**                      | Style configuration for customizing mention appearance.        | `CometChatMentionsStyle? style`                          |
| **disableMentions**            | Disables mentions in the composer (default: false).            | `bool disableMentions`                                   |
| **disableMentionAll**          | Controls whether @all mention is enabled (default: false).     | `bool disableMentionAll`                                 |
| **mentionAllLabel**            | Custom label to display for @all mention.                      | `String? mentionAllLabel`                                |
| **mentionAllLabelId**          | Custom ID for @all mention (default: "all").                   | `String? mentionAllLabelId`                              |

***

## Advance

For advanced-level customization, you can set the style of the Mentions formatters. This lets you tailor each aspect of the widget to fit your exact needs and application aesthetics. You can create and define your formatters style.

### Custom Mentions Formatter

For deeper customization — such as filtering who appears in the suggestion list, transforming suggestions before they reach the UI, or handling mention taps with custom logic — you can extend `CometChatMentionsFormatter` and override its behavior. See the [Custom Mentions Formatter](/ui-kit/flutter/v5/custom-mentions-formatter-guide) guide for a full walkthrough.

### @all Mention Feature

The `CometChatMentionsFormatter` supports mentioning all members in a group using the @all feature. When enabled, users can type `@` followed by "all" (or a custom label) to notify everyone in the group.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessages(
      group: group,
      messageComposerConfiguration: MessageComposerConfiguration(
        textFormatters: [
          CometChatMentionsFormatter(
            disableMentionAll: false, // Enable @all mention (default)
            mentionAllLabel: "everyone", // Custom label (optional)
            mentionAllLabelId: "all", // Custom ID (optional)
          )
        ]
      ),
    )
    ```
  </Tab>
</Tabs>

To disable the @all mention feature:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMentionsFormatter(
      disableMentionAll: true, // Disable @all mention
    )
    ```
  </Tab>
</Tabs>

***

### Composer Mention Text Style

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel for [CometChatMessageComposer](/ui-kit/flutter/v5/message-composer) refer to the below code snippet

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessages(
        user: user,
        messageComposerConfiguration: MessageComposerConfiguration(
            textFormatters: [
                CometChatMentionsFormatter(
                    messageInputTextStyle: (theme) {
                        return const TextStyle(
                        color: Colors.lightBlueAccent,
                        fontSize: 14,
                        fontWeight: FontWeight.bold
                    );
                },
            )
            ]
        )
    )
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Android">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/xB2gtIZtet1FaUV2/images/3b0ae319-mentions_formatter_message_composer_cometchat_screens-225442e8b99831fa34150f8e6976b1af.png?fit=max&auto=format&n=xB2gtIZtet1FaUV2&q=85&s=6f69e067a8431e5b8995d00fe7205cd1" alt="Image" width="4498" height="3121" data-path="images/3b0ae319-mentions_formatter_message_composer_cometchat_screens-225442e8b99831fa34150f8e6976b1af.png" />
  </Tab>

  <Tab title="iOS">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/xHWe3as1OGB4Vmrv/images/955611c2-mentions_formatter_message_composer_cometchat_screens-4aaaa8b78cbf94fe36b780639f56a209.png?fit=max&auto=format&n=xHWe3as1OGB4Vmrv&q=85&s=8937d772875a8c750dbba7c4c7c8008a" alt="Image" width="4498" height="3121" data-path="images/955611c2-mentions_formatter_message_composer_cometchat_screens-4aaaa8b78cbf94fe36b780639f56a209.png" />
  </Tab>
</Tabs>

***

### Message Bubble Mention Text Style

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel for [CometChatMessageList](/ui-kit/flutter/v5/message-list)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessages(
      user: user,
      messageListConfiguration: MessageListConfiguration(
          textFormatters: [
            CometChatMentionsFormatter(
              messageBubbleTextStyle: (theme, alignment,{forConversation = false}) => TextStyle(
                  color: alignment==BubbleAlignment.left? Colors.orange : Colors.greenAccent,
                  fontSize: 14,
                  fontWeight: FontWeight.bold
              ),
            )
          ]
      ),
    )
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Android">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/6IESCr-kzBV6qAKP/images/830f8752-mentions_formatter_message_bubble_cometchat_screens-3d700b5134e1acc33b5c2525b057b905.png?fit=max&auto=format&n=6IESCr-kzBV6qAKP&q=85&s=671c699f82eb15d2c6bba347628e5f48" alt="Image" width="4498" height="3121" data-path="images/830f8752-mentions_formatter_message_bubble_cometchat_screens-3d700b5134e1acc33b5c2525b057b905.png" />
  </Tab>

  <Tab title="iOS">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/ZgtHsaNQApHuht0z/images/c55bc1bc-mentions_formatter_message_bubble_cometchat_screens-14191f03bb8ea1f631005f4a2f145cfe.png?fit=max&auto=format&n=ZgtHsaNQApHuht0z&q=85&s=8f07bf404d1599516c4576282f12ef65" alt="Image" width="4498" height="3121" data-path="images/c55bc1bc-mentions_formatter_message_bubble_cometchat_screens-14191f03bb8ea1f631005f4a2f145cfe.png" />
  </Tab>
</Tabs>

***

### Conversations Mention Text Style

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel for [CometChatConversations](/ui-kit/flutter/v5/conversations)

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      textFormatters: [
        CometChatMentionsFormatter(
          messageBubbleTextStyle: (theme, alignment,{forConversation = false}) =>
              const TextStyle(
                  color: Colors.lightBlueAccent,
                  fontSize: 14,
                  fontWeight: FontWeight.bold
              ),
        )
      ],
    )
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Android">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/h7P8UchGUEpy8xCu/images/aa8703ea-mentions_formatter_conversation_list_cometchat_screens-3cda45abc5c4a4f83cc8b03501543f47.png?fit=max&auto=format&n=h7P8UchGUEpy8xCu&q=85&s=46ceefc677679f3b44cee1226ae51623" alt="Image" width="4498" height="3121" data-path="images/aa8703ea-mentions_formatter_conversation_list_cometchat_screens-3cda45abc5c4a4f83cc8b03501543f47.png" />
  </Tab>

  <Tab title="iOS">
    <img src="https://mintcdn.com/cometchat-22654f5b-docs-angular-v5-docs-update/pnzgsGg7Vjogofic/images/8ef084fe-mentions_formatter_conversation_list_cometchat_screens-46aa09e75e520ab3f38f446cfee8abd3.png?fit=max&auto=format&n=pnzgsGg7Vjogofic&q=85&s=7ec2be9b9a37034ace55de4a0d02c758" alt="Image" width="4498" height="3121" data-path="images/8ef084fe-mentions_formatter_conversation_list_cometchat_screens-46aa09e75e520ab3f38f446cfee8abd3.png" />
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Mentions Formatter" href="/ui-kit/flutter/v5/custom-mentions-formatter-guide">
    Build a custom mentions formatter with filtered suggestions.
  </Card>

  <Card title="Custom Text Formatter" href="/ui-kit/flutter/v5/custom-text-formatter-guide">
    Build custom inline text patterns with regex.
  </Card>

  <Card title="Message Composer" href="/ui-kit/flutter/v5/message-composer">
    Customize the standard message input component.
  </Card>

  <Card title="All Guides" href="/ui-kit/flutter/v5/guide-overview">
    Browse all feature and formatter guides.
  </Card>
</CardGroup>