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

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

Register formatters on a component using textFormatters:

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.

Related

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