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

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

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)

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

CometChatThreadedHeader

Displays the parent message for threaded conversations.

Key Props

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()