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

# Text Formatters

> Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API.

Text formatters let you process message text with tracking characters, suggestion lists, and rich text transformations. Use them to add hashtag detection, custom mentions, link previews, or any text pattern processing.

## CometChatTextFormatter

The `CometChatTextFormatter` abstract class is the base for all formatters. Its constructor takes a `String trackingCharacter` that triggers the formatter when typed in the composer (e.g., `@` for mentions, `#` for hashtags).

### Key Override Methods

| Method                                                               | Purpose                                                                                             |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `search(String query)`                                               | Called when the user types after the tracking character. Use this to fetch and display suggestions. |
| `onScrollToBottom()`                                                 | Called when the user scrolls to the bottom of the suggestion list. Use for pagination.              |
| `buildInputSpan(BuildContext, BaseMessage)`                          | Apply rich text formatting in the message composer.                                                 |
| `buildMessageBubbleSpan(BuildContext, BaseMessage, BubbleAlignment)` | Apply rich text formatting in message bubbles.                                                      |
| `buildConversationSpan(BuildContext, BaseMessage)`                   | Apply formatting in the conversations list last message preview.                                    |
| `handlePreMessageSend(BaseMessage)`                                  | Modify a message before it's sent (attach metadata, transform text).                                |

## Suggestion System

The formatter provides a built-in suggestion dropdown:

| Property/Method                              | Description                                            |
| -------------------------------------------- | ------------------------------------------------------ |
| `setSuggestionItems(List<SuggestionItem>)`   | Set the list of suggestions to display                 |
| `setShowLoadingIndicator(bool)`              | Show/hide a loading spinner in the suggestion dropdown |
| `onItemClick(SuggestionItem, User?, Group?)` | Called when the user selects a suggestion item         |

## Example: Custom Hashtag Formatter

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class HashtagFormatter extends CometChatTextFormatter {
      HashtagFormatter() : super(trackingCharacter: '#');

      @override
      void search(String query) {
        // Fetch hashtag suggestions based on query
        final suggestions = fetchHashtags(query);
        setSuggestionItems(suggestions);
      }

      @override
      void onScrollToBottom() {
        // Load more suggestions
      }

      @override
      InlineSpan? buildMessageBubbleSpan(
        BuildContext context,
        BaseMessage message,
        BubbleAlignment alignment,
      ) {
        // Apply blue color to #hashtags in message bubbles
        return _applyHashtagSpans(message.text);
      }

      @override
      InlineSpan? buildConversationSpan(
        BuildContext context,
        BaseMessage message,
      ) {
        return _applyHashtagSpans(message.text);
      }
    }
    ```
  </Tab>
</Tabs>

## Registering Formatters

Register formatters on a component using `textFormatters`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageList(
      user: user,
      textFormatters: [
        CometChatMentionsFormatter(),
        HashtagFormatter(),
      ],
    )
    ```
  </Tab>
</Tabs>

Or on the message composer:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatMessageComposer(
      user: user,
      textFormatters: [
        CometChatMentionsFormatter(),
        HashtagFormatter(),
      ],
    )
    ```
  </Tab>
</Tabs>

## Built-in Formatters

The UI Kit includes several built-in formatters:

| Formatter                       | Tracking Character | Description                                                                |
| ------------------------------- | ------------------ | -------------------------------------------------------------------------- |
| `CometChatMentionsFormatter`    | `@`                | Handles @mention detection, user suggestion lists, and styled highlighting |
| `CometChatEmailFormatter`       | —                  | Detects and links email addresses                                          |
| `CometChatPhoneNumberFormatter` | —                  | Detects and links phone numbers                                            |
| `MarkdownTextFormatter`         | —                  | Renders markdown formatting (bold, italic, code, etc.)                     |

### Default Formatters

`MessageTemplateUtils.getDefaultTextFormatters()` returns the default set of formatters used by all components:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    final defaults = MessageTemplateUtils.getDefaultTextFormatters();
    // Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter]
    ```
  </Tab>
</Tabs>

## Customizing the Mentions Formatter

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    final mentionsFormatter = CometChatMentionsFormatter();

    CometChatMessageList(
      user: user,
      textFormatters: [mentionsFormatter],
    )
    ```
  </Tab>
</Tabs>

See the [Mentions Formatter Guide](/ui-kit/flutter/mentions-formatter-guide) for detailed styling and behavior customization.

## Related

* [Mentions Formatter Guide](/ui-kit/flutter/mentions-formatter-guide) — Built-in mentions formatter reference.
* [Shortcut Formatter Guide](/ui-kit/flutter/shortcut-formatter-guide) — Shortcut text replacement formatter.
* [Customization Overview](/ui-kit/flutter/customization-overview) — See all customization categories.