Text Formatters - CometChat Docs

Text formatters detect patterns in message text and transform them into formatted HTML for display in bubbles. They run as a pipeline — each formatter receives the output of the previous one, sorted by priority (lower number = runs first). The Text plugin provides three built-in formatters, and you can add your own.

Built-in Formatters

Formatter	Priority	Detects	Output
`CometChatMarkdownFormatter`	10	`bold`, `_italic_`, `code`, `> quote`, lists, links	HTML tags (`<b>`, `<i>`, `<code>`, etc.)
`CometChatMentionsFormatter`	50	`<@uid:xxx>` tokens	Styled `@DisplayName` chips
`CometChatUrlFormatter`	100	`https://...`, `www.`	Clickable `<a>` links

Raw text: "Hey **@Alice**, check https://example.com"
  ↓ MarkdownFormatter (priority 10)
"Hey <b>@Alice</b>, check https://example.com"
  ↓ MentionsFormatter (priority 50)
"Hey <b><span class="mention">@Alice</span></b>, check https://example.com"
  ↓ UrlFormatter (priority 100)
"Hey <b><span class="mention">@Alice</span></b>, check <a href="...">https://example.com</a>"

The Formatter Interface

All formatters extend the abstract CometChatTextFormatter class:

abstract class CometChatTextFormatter {
  /** Unique identifier. */
  abstract readonly id: string;

  /** Priority in the pipeline (lower = runs first). Default: 100. */
  priority: number;

  /** Regex pattern for detecting formattable content. */
  abstract getRegex(): RegExp;

  /** Transform the input text. Must store originalText, apply changes, return formattedText. */
  abstract format(text: string): string;

  /** Whether this formatter should process the given text. Override to skip conditionally. */
  shouldFormat(text: string, message?: BaseMessage): boolean;

  /** Reset internal state. */
  reset(): void;
}

Creating a Custom Formatter

Here’s a hashtag formatter that wraps #word patterns in a styled span:

src/formatters/HashtagFormatter.ts

import { CometChatTextFormatter } from "@cometchat/chat-uikit-react";

export class HashtagFormatter extends CometChatTextFormatter {
  readonly id = "hashtag-formatter";
  override priority = 90; // After mentions (50), before URLs (100)

  private hashtags: string[] = [];

  getRegex(): RegExp {
    return /(#\w+)/g;
  }

  format(text: string): string {
    if (!text) {
      this.originalText = "";
      this.formattedText = "";
      this.hashtags = [];
      return "";
    }

    this.originalText = text;
    this.hashtags = [];

    this.formattedText = text.replace(this.getRegex(), (match) => {
      this.hashtags.push(match);
      return `<span class="cometchat-hashtag" style="color: #6851FF; font-weight: 500;">${match}</span>`;
    });

    this.metadata = { hashtags: this.hashtags };
    return this.formattedText;
  }

  /** Get detected hashtags from the last format() call. */
  getHashtags(): string[] {
    return [...this.hashtags];
  }

  override reset(): void {
    super.reset();
    this.hashtags = [];
  }
}

Registering Custom Formatters

Custom formatters are registered by creating a custom text plugin that provides them:

src/plugins/CustomTextPlugin.ts

import { CometChatTextPlugin } from "@cometchat/chat-uikit-react";
import type { CometChatTextFormatter } from "@cometchat/chat-uikit-react";
import {
  CometChatMarkdownFormatter,
  CometChatMentionsFormatter,
  CometChatUrlFormatter,
} from "@cometchat/chat-uikit-react";
import { HashtagFormatter } from "../formatters/HashtagFormatter";

export const CustomTextPlugin = {
  ...CometChatTextPlugin,
  id: "custom-text",

  getTextFormatters(): CometChatTextFormatter[] {
    return [
      new CometChatMarkdownFormatter(),   // priority 10
      new CometChatMentionsFormatter(),   // priority 50
      new HashtagFormatter(),             // priority 90
      new CometChatUrlFormatter(),        // priority 100
    ];
  },
};

Then pass it in your provider’s plugins prop:

import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { CustomTextPlugin } from "./plugins/CustomTextPlugin";

<CometChatProvider plugins={[CustomTextPlugin]}>
  <MyChatApp />
</CometChatProvider>

Since user plugins are prepended before the defaults in the registry, your custom text plugin takes precedence over the built-in one (first match wins)

Formatter Details

CometChatMarkdownFormatter

Converts markdown syntax to HTML. Runs first (priority 10) so subsequent formatters operate on HTML output.

**bold** → bold
_italic_ → italic
__underline__ or ++underline++ → underline
~~strikethrough~~ → <s>strikethrough</s>
`inline code` → <code>inline code</code>
```code block``` → <pre><code>code block</code></pre>
> blockquote → <blockquote>blockquote</blockquote>
[text](url) → <a href="url">text</a>
1. item → ordered list; • item / - item → unordered list

CometChatMentionsFormatter

Resolves SDK mention tokens (<@uid:xxx> and <@all:label>) into styled mention chips. Requires the mentioned-users list from the message to resolve UIDs to display names.

CometChatUrlFormatter

Detects bare URLs (https://... and www.) and wraps them in clickable <a> tags with target="_blank" and rel="noopener noreferrer". Protects existing markdown links and <a> tags from double-processing.

Tips

Priority matters — markdown must run before mentions/URLs so it doesn’t break HTML tags
Protect code blocks — formatters should skip content inside <code> and <pre> tags
Keep it fast — formatters run on every text message render; avoid expensive operations
Use shouldFormat() — override to skip formatting for specific messages
Store metadata — use this.metadata to expose extracted data (URLs, hashtags, mentions) to consumers

​Built-in Formatters

​The Formatter Interface

​Creating a Custom Formatter

​Registering Custom Formatters

​Formatter Details

​CometChatMarkdownFormatter

​CometChatMentionsFormatter

​CometChatUrlFormatter

​Tips