> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mentions Formatter

> Mentions Formatter — CometChat integration guide.

## Overview

The `CometChatMentionsFormatter` class is a part of the CometChat UI Kit, a ready-to-use chat UI component 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.

## 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 components such as [CometChatConversations](/ui-kit/android/v4/conversations), [CometChatMessageList](/ui-kit/android/v4/message-list), [CometChatMessageComposer](/ui-kit/android/v4/message-composer).

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    // Initialize CometChatMentionsFormatter
    CometChatMentionsFormatter mentionFormatter = new CometChatMentionsFormatter(requireContext());


    List<CometChatTextFormatter> textFormatters = new ArrayList<>();
    textFormatters.add(mentionFormatter);
    // This can be passed as an array of formatter in CometChatConversations, MessageList or Message Composer by using setTextFormatters method.
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
     // Initialize CometChatMentionsFormatter
     val mentionFormatter = CometChatMentionsFormatter(this)

    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    // This can be passed as an array of formatter in CometChatConversations, MessageList or Message Composer by using setTextFormatters method.
    ```
  </Tab>
</Tabs>

## Actions

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

##### setOnMentionClick

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.

**Example**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/Q-VZaihy61fy3D_G/images/20d4bdca-mentionsclickdemo-33a2542b9f458fbd28f592db377df8ff.png?fit=max&auto=format&n=Q-VZaihy61fy3D_G&q=85&s=56289064d2c346676a092693d3bf6486" width="9556" height="6820" data-path="images/20d4bdca-mentionsclickdemo-33a2542b9f458fbd28f592db377df8ff.png" />
</Frame>

<Tabs>
  <Tab title="Java">
    ```java theme={null}

    // Initialize CometChatMentionsFormatter
    CometChatMentionsFormatter mentionFormatter = new CometChatMentionsFormatter(context);

    // set callback for the mention click

      mentionFormatter.setOnMentionClick((context, user) -> {
            Toast.makeText(context, user.getName(), Toast.LENGTH_SHORT).show();
      });

    // This can be passed as an array of formatter in CometChatMessageComposer by using setTextFormatters method.
    List<CometChatTextFormatter> textFormatters = new ArrayList<>();
    textFormatters.add(mentionFormatter);
    messageComposer.setTextFormatters(textFormatters);
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}

    // Initialize CometChatMentionsFormatter
    val mentionFormatter = CometChatMentionsFormatter(context)

    // set callback for the mention click

    mentionFormatter.setOnMentionClick { context, user ->
    Toast.makeText(context, user.name, Toast.LENGTH_SHORT).show()
    }

    // This can be passed as an array of formatter in CometChatMessageComposer by using setTextFormatters method.
    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageComposer.setTextFormatters(textFormatters)
    ```
  </Tab>
</Tabs>

## Customization

| Methods                           | Description                                                                                                                                                                                                                                                                                                               | Code                                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **setMentionLimit**               | Sets the limit for the number of mentions allowed.                                                                                                                                                                                                                                                                        | `setMentionLimit(int limit)`                                                                                    |
| **setGroupMembersRequestBuilder** | Sets the builder for fetching group members.                                                                                                                                                                                                                                                                              | `.setGroupMembersRequestBuilder(group -> new GroupMembersRequest.GroupMembersRequestBuilder(group.getGuid()));` |
| **setUsersRequestBuilder**        | Sets the builder for fetching users.                                                                                                                                                                                                                                                                                      | `.setUsersRequestBuilder(new UsersRequest.UsersRequestBuilder().friendsOnly(true));`                            |
| **setMentionsType**               | Supports two types of mentions: `USERS` and `USERS_AND_GROUP_MEMBERS`. If set to `USERS`, only users can be mentioned in both one-on-one and group conversations. If set to `USERS_AND_GROUP_MEMBERS`, members of a specific group can be mentioned in group chats, while all users can be mentioned in one-on-one chats. | `.setMentionsType(UIKitConstants.MentionsType.USERS_AND_GROUP_MEMBERS)`                                         |
| **setMentionsVisibility**         | This method allows you to set the scope of mentions visibility within the app, choosing from `USERS_CONVERSATION_ONLY`, `GROUP_CONVERSATION_ONLY`, or `BOTH`. It lets you specify whether mentions are visible only in one-on-one conversations, only in group conversations, or in both.                                 | `.setMentionsVisibility(UIKitConstants.MentionsVisibility.BOTH);`                                               |
| **setOnMentionClick**             | Sets a listener for mention click in Message Bubbles events.                                                                                                                                                                                                                                                              | `mentionFormatter.setOnMentionClick((context, user) -> {` `// Add your implementation here` `});`               |

## Advance

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

### 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/android/v4/message-composer) refer to the below code snippet

**Example**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/LKT8U_07JOWQgTZK/images/0f71d059-composermentions-d46d794da2dbe940733fb59ba46d79e5.png?fit=max&auto=format&n=LKT8U_07JOWQgTZK&q=85&s=61183dc28b35cff0ed1d0256e0c0075c" width="7980" height="6240" data-path="images/0f71d059-composermentions-d46d794da2dbe940733fb59ba46d79e5.png" />
</Frame>

<Tabs>
  <Tab title="Java">
    ```java theme={null}

    // Initialize CometChatMentionsFormatter
    CometChatMentionsFormatter mentionFormatter = new CometChatMentionsFormatter(context);

    // set style to customize composer mention text
    mentionFormatter.setComposerMentionTextStyle(new MentionTextStyle()
                .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
                .setTextColor(Color.parseColor("#000000")));

    // This can be passed as an array of formatter in CometChatMessageComposer by using setTextFormatters method.
    List<CometChatTextFormatter> textFormatters = new ArrayList<>();
    textFormatters.add(mentionFormatter);
    messageComposer.setTextFormatters(textFormatters);
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}

    // Initialize CometChatMentionsFormatter
    val mentionFormatter = CometChatMentionsFormatter(context)
    // set style to customize composer mention text
    mentionFormatter.composerMentionTextStyle = MentionTextStyle()
    .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
    .setTextColor(Color.parseColor("#000000"))

    // This can be passed as an array of formatter in CometChatMessageComposer by using setTextFormatters method.
    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageComposer.setTextFormatters(textFormatters)
    ```
  </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/android/v4/message-list)

**Example**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/Xbd1mrZiWe1Pd3HE/images/8ebb56e7-mentionsconfigured-8e774733327d2a63df6bc3bf4ae5a2e8.png?fit=max&auto=format&n=Xbd1mrZiWe1Pd3HE&q=85&s=d57b72789d4afa602afbcffeb629d3f3" width="9556" height="6820" data-path="images/8ebb56e7-mentionsconfigured-8e774733327d2a63df6bc3bf4ae5a2e8.png" />
</Frame>

<Tabs>
  <Tab title="Java">
    ```java theme={null}

    // Initialize CometChatMentionsFormatter
    CometChatMentionsFormatter mentionFormatter = new CometChatMentionsFormatter(context);

    //set style to customize bubble mention text
    mentionFormatter.setRightBubbleMentionTextStyle(new MentionTextStyle()
                .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
                .setTextColor(Color.parseColor("#000000")));

    mentionFormatter.setLeftBubbleMentionTextStyle(new MentionTextStyle()
                .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
                .setTextColor(Color.parseColor("#000000")));

    // This can be passed as an array of formatter in CometChatMessageList by using setTextFormatters method.
    List<CometChatTextFormatter> textFormatters = new ArrayList<>();
    textFormatters.add(mentionFormatter);
    messageList.setTextFormatters(textFormatters);
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}

    // Initialize CometChatMentionsFormatter
    val mentionFormatter = CometChatMentionsFormatter(context)

    //set style to customize bubble mention text
     val mentionFormatter = CometChatMentionsFormatter(context)
        mentionFormatter.rightBubbleMentionTextStyle = MentionTextStyle()
            .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
            .setTextColor(Color.parseColor("#000000"))

        mentionFormatter.leftBubbleMentionTextStyle = MentionTextStyle()
            .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
            .setTextColor(Color.parseColor("#000000"))

    // This can be passed as an array of formatter in CometChatMessageList by using setTextFormatters method.
    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    messageList.setTextFormatters(textFormatters)
    ```
  </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/android/v4/conversations)

**Example**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/dDWpooIQ48haNjyU/images/7abd65f9-conversationsmentions-17bdf4c7b26ff9fedef5bf8ae4678e98.png?fit=max&auto=format&n=dDWpooIQ48haNjyU&q=85&s=f6c3a10b6a18716dabeaeea18ac46cc6" width="8018" height="6240" data-path="images/7abd65f9-conversationsmentions-17bdf4c7b26ff9fedef5bf8ae4678e98.png" />
</Frame>

<Tabs>
  <Tab title="Java">
    ```java theme={null}

    // Initialize CometChatMentionsFormatter
    CometChatMentionsFormatter mentionFormatter = new CometChatMentionsFormatter(context);

    //set style to customize conversation mention text
    mentionFormatter.setConversationsMentionTextStyle(new MentionTextStyle()
                .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
                .setTextColor(Color.parseColor("#000000")));

    // This can be passed as an array of formatter in CometChatConversations by using setTextFormatters method.
    List<CometChatTextFormatter> textFormatters = new ArrayList<>();
    textFormatters.add(mentionFormatter);
    cometChatConversations.setTextFormatters(textFormatters);
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}

    // Initialize CometChatMentionsFormatter
    val mentionFormatter = CometChatMentionsFormatter(context)
    //set style to customize conversation mention text
    mentionFormatter.conversationsMentionTextStyle = MentionTextStyle()
    .setLoggedInUserTextStyle(Typeface.defaultFromStyle(Typeface.BOLD))
    .setTextColor(Color.parseColor("#000000"))

    // This can be passed as an array of formatter in CometChatConversations by using setTextFormatters method.
    val textFormatters: MutableList<CometChatTextFormatter> = ArrayList()
    textFormatters.add(mentionFormatter)
    cometChatConversations.setTextFormatters(textFormatters)
    ```
  </Tab>
</Tabs>