Text Formatters - CometChat Docs

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

Dart

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

Dart

CometChatMessageList(
  user: user,
  textFormatters: [
    CometChatMentionsFormatter(),
    HashtagFormatter(),
  ],
)

Or on the message composer:

Dart

CometChatMessageComposer(
  user: user,
  textFormatters: [
    CometChatMentionsFormatter(),
    HashtagFormatter(),
  ],
)

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:

Dart

final defaults = MessageTemplateUtils.getDefaultTextFormatters();
// Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter]

Customizing the Mentions Formatter

Dart

final mentionsFormatter = CometChatMentionsFormatter();

CometChatMessageList(
  user: user,
  textFormatters: [mentionsFormatter],
)

See the Mentions Formatter Guide for detailed styling and behavior customization.

Mentions Formatter Guide — Built-in mentions formatter reference.
Shortcut Formatter Guide — Shortcut text replacement formatter.
Customization Overview — See all customization categories.

​CometChatTextFormatter

​Key Override Methods

​Suggestion System

​Example: Custom Hashtag Formatter

​Registering Formatters

​Built-in Formatters

​Default Formatters

​Customizing the Mentions Formatter

​Related