Skip to main content
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

MethodPurpose
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/MethodDescription
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

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);
  }
}

​
Registering Formatters

Register formatters on a component using textFormatters: 
CometChatMessageList(
  user: user,
  textFormatters: [
    CometChatMentionsFormatter(),
    HashtagFormatter(),
  ],
)
Or on the message composer: 
CometChatMessageComposer(
  user: user,
  textFormatters: [
    CometChatMentionsFormatter(),
    HashtagFormatter(),
  ],
)

​
Built-in Formatters

The UI Kit includes several built-in formatters:
FormatterTracking CharacterDescription
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: 
final defaults = MessageTemplateUtils.getDefaultTextFormatters();
// Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter]

​
Customizing the Mentions Formatter

final mentionsFormatter = CometChatMentionsFormatter();

CometChatMessageList(
  user: user,
  textFormatters: [mentionsFormatter],
)
See the Mentions Formatter Guide for detailed styling and behavior customization.