> ## 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.
# Custom Text Formatter
> Extend CometChatTextFormatter to build custom inline text patterns with tracking characters and suggestion lists.
| Field | Value |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Package | `com.cometchat:chat-uikit-android` |
| Key class | `CometChatTextFormatter` (abstract base class for custom formatters) |
| Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")` |
| Purpose | Extend to create custom inline text patterns with tracking characters, suggestion lists, and span formatting |
| Features | Tracking character activation, suggestion list, span formatting per context (composer, bubbles, conversations), pre-send hooks |
| Sample app | [GitHub](https://github.com/cometchat/cometchat-uikit-android/tree/v5/sample-app-kotlin) |
| Related | [Mentions Formatter](/ui-kit/android/mentions-formatter-guide) \| [ShortCut Formatter](/ui-kit/android/shortcut-formatter-guide) \| [All Guides](/ui-kit/android/guide-overview) |
`CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, shortcuts, or any pattern triggered by a tracking character.
| Capability | Description |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| Tracking character | Activates the formatter when the user types a specific character (e.g., `#`, `!`) |
| Suggestion list | Populates a dropdown of `SuggestionItem` objects as the user types |
| Span formatting | Applies `SpannableStringBuilder` spans per context: composer, left/right bubbles, conversations |
| Pre-send hook | `handlePreMessageSend` lets you modify the message before it's sent |
| Component integration | Plugs into any component via `setTextFormatters()` |
***
## Steps
### 1. Create a class extending CometChatTextFormatter
Pass your tracking character to the superclass constructor.
```kotlin lines theme={null}
class HashTagFormatter : CometChatTextFormatter('#') {
private val suggestions: MutableList = ArrayList()
}
```
```java lines theme={null}
public class HashTagFormatter extends CometChatTextFormatter {
private List suggestions = new ArrayList<>();
public HashTagFormatter() {
super('#');
}
}
```
### 2. Override the search method
Called when the user types after the tracking character. Match input against your data and update the suggestion list.
```kotlin lines theme={null}
override fun search(context: Context, queryString: String?) {
suggestions.clear()
val query = "#${queryString ?: ""}"
// Match against your hashtag data source
val matchingTags = getMatchingTags(query)
for (tag in matchingTags) {
val item = SuggestionItem("", tag, null, null, tag, null, null)
item.isHideLeadingIcon = true
suggestions.add(item)
}
setSuggestionItemList(suggestions)
}
```
```java lines theme={null}
@Override
public void search(@NonNull Context context, @Nullable String queryString) {
suggestions.clear();
String query = "#" + (queryString != null ? queryString : "");
// Match against your hashtag data source
List matchingTags = getMatchingTags(query);
for (String tag : matchingTags) {
SuggestionItem item = new SuggestionItem("", tag, null, null, tag, null, null);
item.setHideLeadingIcon(true);
suggestions.add(item);
}
setSuggestionItemList(suggestions);
}
```
### 3. Override onScrollToBottom
Required by the base class. Implement pagination logic or leave empty.
```kotlin theme={null}
override fun onScrollToBottom() {
// Load more suggestions if needed
}
```
```java theme={null}
@Override
public void onScrollToBottom() {
// Load more suggestions if needed
}
```
### 4. Override span formatting methods (optional)
Customize how matched text renders in different contexts using `SpannableStringBuilder`.
```kotlin lines theme={null}
override fun prepareLeftMessageBubbleSpan(
context: Context, baseMessage: BaseMessage, spannable: SpannableStringBuilder
): SpannableStringBuilder? {
// Apply custom spans for incoming message bubbles
return applyHashTagSpans(spannable, Color.parseColor("#5dff05"))
}
override fun prepareRightMessageBubbleSpan(
context: Context, baseMessage: BaseMessage, spannable: SpannableStringBuilder
): SpannableStringBuilder? {
// Apply custom spans for outgoing message bubbles
return applyHashTagSpans(spannable, Color.parseColor("#30b3ff"))
}
```
```java lines theme={null}
@Override
public SpannableStringBuilder prepareLeftMessageBubbleSpan(
@NonNull Context context, @NonNull BaseMessage baseMessage, SpannableStringBuilder spannable) {
return applyHashTagSpans(spannable, Color.parseColor("#5dff05"));
}
@Override
public SpannableStringBuilder prepareRightMessageBubbleSpan(
@NonNull Context context, @NonNull BaseMessage baseMessage, SpannableStringBuilder spannable) {
return applyHashTagSpans(spannable, Color.parseColor("#30b3ff"));
}
```
### 5. Integrate with a component
```kotlin lines theme={null}
val textFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, messageComposer.additionParameter)
textFormatters.add(HashTagFormatter())
messageComposer.setTextFormatters(textFormatters)
```
```java lines theme={null}
List textFormatters = CometChatUIKit.getDataSource().getTextFormatters(this, messageComposer.getAdditionParameter());
textFormatters.add(new HashTagFormatter());
messageComposer.setTextFormatters(textFormatters);
```
Pass the same list to `CometChatMessageList` and `CometChatConversations` via their `setTextFormatters()` methods to apply formatting across all contexts.
***
## Methods Reference
| Method | Description |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `search(Context, String)` | Abstract — called when user types after the tracking character. Update the suggestion list here. |
| `onScrollToBottom()` | Abstract — called when the suggestion list scrolls to the bottom. Implement pagination or leave empty. |
| `onItemClick(Context, SuggestionItem, User, Group)` | Called when a suggestion item is selected. Override to customize insertion behavior. |
| `handlePreMessageSend(Context, BaseMessage)` | Called before a message is sent. Override to modify the message (e.g., add metadata). |
| `prepareLeftMessageBubbleSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in incoming message bubbles. |
| `prepareRightMessageBubbleSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in outgoing message bubbles. |
| `prepareComposerSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in the message composer. |
| `prepareConversationSpan(Context, BaseMessage, SpannableStringBuilder)` | Override to format text in the conversations list preview. |
| `setSuggestionItemList(List)` | Updates the suggestion dropdown with new items. |
| `setDisableSuggestions(boolean)` | Disables the suggestion dropdown entirely. (`protected` — accessible from subclasses only.) |
| `setInfoText(String)` | Sets informational text displayed above the suggestion list. |
| `setInfoVisibility(boolean)` | Toggles visibility of the info text. |
| `setShowLoadingIndicator(boolean)` | Shows/hides a loading spinner in the suggestion dropdown. |
| `getTrackingCharacter()` | Returns the tracking character passed to the constructor. |
***
## Next Steps
Built-in @mention formatting with styled tokens
Shortcut text expansion via the message-shortcuts extension
Browse all feature and formatter guides
Full working sample application on GitHub