cometchat-flutter-v5-messages

name	cometchat-flutter-v5-messages
description	Use when working with CometChat Flutter UIKit v5 message components. Triggers on CometChatMessageList, CometChatMessageComposer, CometChatCompactMessageComposer, CometChatMessageHeader, threads.
license	MIT
compatibility	cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3
metadata	{"author":"CometChat","version":"3.0.0","tags":"cometchat flutter v5 messages list composer header bubbles threads compact"}

Ground truth: cometchat_chat_uikit: ^5.2 (legacy/maintenance-only; calls via raw cometchat_calls_sdk ^5.0.2) — pub-cache source + ui-kit/flutter/v5. Official docs: https://www.cometchat.com/docs/ui-kit/flutter/v5/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

CometChat Flutter UIKit v5 — Messages

Components for displaying, sending, and managing messages.

CometChatMessageList

Displays messages in a conversation.

Key Props

Prop	Type	Default	Description
user	User?	—	User for 1-on-1 chat (one of user/group required)
group	Group?	—	Group for group chat
messagesRequestBuilder	MessagesRequestBuilder?	—	Custom message fetch builder
style	CometChatMessageListStyle?	—	Visual styling
alignment	ChatAlignment	standard	standard or leftAligned
onThreadRepliesClick	ThreadRepliesClick?	—	Thread reply tap callback
templates	List<CometChatMessageTemplate>?	—	Custom message templates
textFormatters	List<CometChatTextFormatter>?	—	Custom text formatters
receiptsVisibility	bool	true	Show read receipts
avatarVisibility	bool	true	Show avatars
disableReactions	bool	false	Disable reactions
disableMentions	bool?	—	Disable @mentions
messageId	int?	—	Scroll to specific message
startFromUnreadMessages

Usage

CometChatMessageList(
  user: user,
  textFormatters: [
    CometChatEmailFormatter(),
    CometChatPhoneNumberFormatter(),
    CometChatUrlFormatter(),
    CometChatMentionsFormatter(user: user),
  ],
  receiptsVisibility: true,
  hideReplyInThreadOption: false,
  hideEditMessageOption: false,
  hideDeleteMessageOption: false,
)

CometChatMessageComposer

Full-featured message input with attachments, voice recording, mentions, and AI features.

Key Props

Prop	Type	Default	Description
user	User?	—	Target user (one of user/group required)
group	Group?	—	Target group
messageComposerStyle	CometChatMessageComposerStyle?	—	Visual styling
parentMessageId	int	0	Thread parent message ID
placeholderText	String?	—	Input placeholder
textFormatters	List<CometChatTextFormatter>?	—	Text formatters
disableTypingEvents	bool	false	Disable typing indicators
disableMentions	bool?	—	Disable @mentions
disableMentionAll	bool	false	Disable @all mentions
hideVoiceRecordingButton	bool?	—	Hide voice recording
hideAttachmentButton	bool?	—	Hide attachment button
hideSendButton	bool?	—	Hide send button
hideStickersButton	bool?	—	Hide stickers
hideImageAttachmentOption	bool?	—	Hide image attachment
hideVideoAttachmentOption

CometChatCompactMessageComposer

Compact variant with rounded pill-shaped input, inline rich text toolbar, and modern minimal aesthetic. Use it explicitly in your widget tree when you want this look — there is no global Layout toggle that swaps composers automatically.

Props unique to Compact (not in regular composer)

Prop	Type	Default	Description
compactMessageComposerStyle	CometChatCompactMessageComposerStyle?	—	Visual styling
enableRichTextFormatting	bool	true	Enable rich text (master switch)
showRichTextFormattingOptions	bool	true	Show toolbar above composer
showTextSelectionMenuItems	bool	true	Formatting in text selection menu
hideRichTextFormattingOptions	Set<FormatType>?	—	Hide specific format types
richTextToolbarStyle	CometChatRichTextToolbarStyle?	—	Toolbar styling
enterKeyBehavior	EnterKeyBehavior	newLine	Enter key: sendMessage or newLine

All other props (user, group, parentMessageId, hide* options, textFormatters, etc.) are the same as CometChatMessageComposer.

Usage

// ✅ CORRECT — compact composer with thread support
CometChatCompactMessageComposer(
  user: user,
  parentMessageId: parentMessage.id,
  disableTypingEvents: false,
  disableMentions: false,
  hideVoiceRecordingButton: false,
)

CometChatMessageHeader

Displays user/group info. Implements PreferredSizeWidget for use as appBar.

Key Props

Prop	Type	Description
user	User?	User to display
group	Group?	Group to display
messageHeaderStyle	CometChatMessageHeaderStyle?	Visual styling
subtitleView	Widget? Function(Group?, User?, BuildContext)?	Custom subtitle
listItemView	Widget Function(Group?, User?, BuildContext)?	Custom list item
showBackButton	bool?	Show back button (default: true)
onBack	VoidCallback?	Back button callback
hideVideoCallButton	bool?	Hide video call button
hideVoiceCallButton	bool?	Hide voice call button
usersStatusVisibility	bool	Show online status (default: true)
options	Function(User?, Group?, BuildContext)?	Custom header options menu

CometChatThreadedHeader

Displays the parent message for threaded conversations.

Key Props

Prop	Type	Description
parentMessage	BaseMessage	The parent message (required)
loggedInUser	User	Current logged-in user (NON-nullable; pass CometChatUIKit.loggedInUser!)
template	CometChatMessageTemplate?	Message template
receiptsVisibility	bool?	Show receipts
height	double?	Header height
width	double?	Header width
messageActionView	Function(BaseMessage, BuildContext)?	Builder for a custom action view in the header
style	CometChatThreadedHeaderStyle?	Visual style
textFormatters	List<CometChatTextFormatter>?	Custom text formatters

Threaded Messages Pattern

Scaffold(
  body: Column(
    children: [
      CometChatThreadedHeader(
        parentMessage: parentMessage,
        loggedInUser: CometChatUIKit.loggedInUser!,
      ),
      Expanded(
        child: CometChatMessageList(
          user: user,
          messagesRequestBuilder: MessagesRequestBuilder()
            ..parentMessageId = parentMessage.id,
        ),
      ),
      CometChatMessageComposer(
        user: user,
        parentMessageId: parentMessage.id,
      ),
    ],
  ),
)

Sending Messages Programmatically

Use CometChatUIKit static methods (not CometChat directly) to ensure UIKit events fire:

// ✅ CORRECT
CometChatUIKit.sendTextMessage(message, onSuccess: ..., onError: ...);

// ❌ WRONG — bypasses UIKit events (ccMessageSent won't fire)
CometChat.sendMessage(message, onSuccess: ...);

Golden Path — Messages Screen

class MessagesScreen extends StatelessWidget {
  final User? user;
  final Group? group;
  const MessagesScreen({super.key, this.user, this.group});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: CometChatMessageHeader(
        user: user,
        group: group,
        onBack: () => Navigator.pop(context),
      ),
      body: Column(
        children: [
          Expanded(child: CometChatMessageList(user: user, group: group)),
          CometChatMessageComposer(user: user, group: group),
        ],
      ),
    );
  }
}

Anti-Patterns

// ❌ WRONG — passing two NON-null targets at the same time
CometChatMessageList(user: aUser, group: aGroup) // ambiguous — kit ignores group
// ✅ At any moment, exactly one of user/group must be non-null.
// Passing both fields with one null (e.g. `user: user, group: null`) is fine
// and is what the chat-builder sample app does to switch between contexts.

// ❌ WRONG — using CometChat.sendMessage instead of CometChatUIKit
CometChat.sendMessage(message, onSuccess: ...);

Checklist — Messages Screen

• Only one of user or group passed to each component
• Same user/group passed to Header, List, and Composer
• Thread replies use parentMessageId on both List and Composer
• Messages sent via CometChatUIKit.sendTextMessage()