AI Agent Component Spec
AI Agent Component Spec
| Field | Value |
|---|---|
| Package | cometchat_chat_uikit |
| Key class | CometChatMentionsFormatter (from cometchat_uikit_shared) |
| Init | CometChatUIKit.init(uiKitSettings) then CometChatUIKit.login(uid) |
| Purpose | Customize @mention suggestion behavior — filter who appears, style mentions, handle taps |
| Version | v5.2.13 |
| Sample app | GitHub |
| Related | Mentions Formatter · Custom Text Formatter · All Guides |
CometChatMentionsFormatter to control the @mention suggestion behavior inside the message composer — letting you filter who appears in the suggestion list, customize mention styling, and handle tap interactions. This works with both CometChatMessageComposer and CometChatCompactMessageComposer.
Setup
Before implementing a custom mentions formatter, integrate the CometChat Flutter UI Kit into your application. Follow the official Flutter UI Kit integration guide to:- Create a CometChat account and obtain your App ID, Region, and Auth Key
- Add the
cometchat_chat_uikitdependency to yourpubspec.yaml - Initialize the SDK with
CometChatUIKit.init()and log in a user withCometChatUIKit.login()
Use Case
Filter the logged-in user out of the@mention suggestion list so users don’t see themselves when typing @. The same pattern applies to any custom filtering, styling, or tap-handling logic you need.
How It Works
The key idea: wrap thesuggestionListEventSink with a filtering proxy so every suggestion list emitted by the base class is automatically transformed before reaching the UI.
Steps
1. Create the Formatter Class
Create a new filelib/utils/custom_mentions_formatter.dart. Your class extends CometChatMentionsFormatter and wraps the suggestion sink before the parent starts using it.
- custom_mentions_formatter.dart
2. Create the Filtering Sink
In the same file, add a privateStreamSink wrapper. This is the piece that actually filters the suggestions — in this example it removes the logged-in user.
- Dart
3. Use It in the Composer Widgets
Your custom formatter works with both composer widgets via thetextFormatters parameter.
When the UI Kit detects a custom subclass of
CometChatMentionsFormatter in textFormatters, it automatically removes the default one so they don’t conflict. You don’t need to manually disable the built-in formatter.- CometChatMessageComposer
- CometChatCompactMessageComposer
- Switching at Runtime
Key Concepts
| Concept | What It Means |
|---|---|
CometChatMentionsFormatter | The base class that handles @mention behavior. Extend this to customize. |
CometChatTextFormatter | The parent of CometChatMentionsFormatter. All text formatters (email, phone, mentions) extend this. |
CometChatMessageComposer | The standard (normal) message composer widget. Accepts textFormatters. |
CometChatCompactMessageComposer | A slimmer composer with rich text editing. Also accepts textFormatters in the same way. |
textFormatters | A list of formatters passed to either composer. Both composers handle custom mentions formatters identically. |
suggestionListEventSink | A StreamSink that receives the suggestion list data. Wrapping it lets you filter/transform suggestions. |
SuggestionListItem | Each item in the mention suggestion dropdown. Has an id field you can use for filtering. |
trackingCharacter | The character that triggers the suggestion list. Defaults to @. |
onMentionTap | Callback fired when a user taps on a mention in a message bubble. |
Common Customization Ideas
Filter by Role
You can filter based on thedata map attached to each SuggestionListItem. For example, if user metadata includes a role:
Limit Suggestion Count
Custom Mention Styling
Troubleshooting
| Problem | Solution |
|---|---|
| Suggestions still show the logged-in user | Make sure you’re passing CustomMentionsFormatter (not the base class) in textFormatters. |
| Suggestion list doesn’t appear at all | Check that disableMentions is not set to true. Verify the user or group parameter is provided. |
onMentionTap not firing | Ensure you’re passing the callback when constructing the formatter, not on a separate default formatter. |
| Two suggestion lists appearing | You may be passing both a custom and default CometChatMentionsFormatter. The UI Kit handles deduplication automatically, but double-check your textFormatters list. |
Next Steps
Mentions Formatter
Configure the built-in mentions formatter.
Custom Text Formatter
Build custom inline text patterns with regex.
Message Composer
Customize the standard message input component.
Compact Message Composer
Customize the compact message input component.