Message List - CometChat Docs

CometChatMessageList renders a scrollable list of messages for a conversation with real-time updates for new messages, edits, deletions, reactions, and threaded replies.

Where It Fits

CometChatMessageList is a message display component. It requires either a User or Group object to fetch and render messages. Wire it with CometChatMessageHeader and CometChatMessageComposer to build a complete messaging layout.

Dart

CometChatMessageList(
  user: user,
)

Quick Start

Using Navigator:

Dart

Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatMessageList(user: user)));

Embedding as a widget:

Dart

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: CometChatMessageList(
        user: user, // or group: group
      ),
    ),
  );
}

Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the UI Kit dependency added.

Simply adding the MessageList component to the layout will only display the loading indicator. You must supply a User or Group object to fetch messages.

Filtering

Pass a MessagesRequestBuilder to control what loads:

Dart

CometChatMessageList(
  user: user,
  messagesRequestBuilder: MessagesRequestBuilder()
    ..uid = user.uid
    ..searchKeyword = "hello"
    ..limit = 30,
)

The following parameters in MessagesRequestBuilder will always be altered inside the message list: UID, GUID, types, categories.

Actions and Events

Callback Methods

`onThreadRepliesClick`

Fires when a user taps a threaded message bubble.

Dart

CometChatMessageList(
  user: user,
  onThreadRepliesClick: (message, context, {template}) {
    // Navigate to thread view
  },
)

`onError`

Fires on internal errors.

Dart

CometChatMessageList(
  user: user,
  onError: (e) {
    debugPrint("Error: ${e.message}");
  },
)

`onLoad`

Fires when the list is successfully fetched and loaded.

Dart

CometChatMessageList(
  user: user,
  onLoad: (messages) {
    debugPrint("Loaded ${messages.length}");
  },
)

`onEmpty`

Fires when the list is empty after loading.

Dart

CometChatMessageList(
  user: user,
  onEmpty: () {
    debugPrint("No messages");
  },
)

`onReactionClick`

Fires when a reaction pill is tapped.

Dart

CometChatMessageList(
  user: user,
  onReactionClick: (emoji, message) {
    // Handle reaction click
  },
)

`onReactionLongPress`

Fires when a reaction pill is long-pressed.

Dart

CometChatMessageList(
  user: user,
  onReactionLongPress: (emoji, message) {
    // Handle reaction long press
  },
)

SDK Events (Real-Time, Automatic)

The component listens to SDK message events internally. No manual setup needed.

SDK Listener	Internal behavior
`onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`	Inserts new message with animation
`onMessageEdited`	Updates message in-place
`onMessageDeleted`	Removes or marks message as deleted
`onMessagesDelivered` / `onMessagesRead`	Updates receipt status via ValueNotifier
`onTypingStarted` / `onTypingEnded`	Updates typing indicator
`onMessageReactionAdded` / `onMessageReactionRemoved`	Updates reaction counts
Connection reconnected	Triggers silent sync to fetch missed messages

Functionality

Property	Type	Default	Description
`user`	`User?`	required*	User for 1-on-1 conversation
`group`	`Group?`	required*	Group for group conversation
`parentMessageId`	`int?`	`null`	Parent message ID for thread replies
`alignment`	`ChatAlignment`	`standard`	Chat alignment setting
`hideDeletedMessages`	`bool`	`false`	Hide deleted messages entirely
`disableReceipts`	`bool`	`false`	Disable read/delivery receipts
`disableSoundForMessages`	`bool`	`false`	Disable message sounds
`hideReplies`	`bool`	`true`	Hide thread replies in main conversation
`hideGroupActionMessages`	`bool?`	`false`	Hide group action messages
`hideTimestamp`	`bool?`	`null`	Toggle timestamp visibility
`hideDateSeparator`	`bool?`	`false`	Hide date separators
`hideStickyDate`	`bool?`	`false`	Hide floating sticky date header
`avatarVisibility`	`bool?`	`true`	Toggle avatar visibility
`receiptsVisibility`	`bool?`	`true`	Toggle read receipts
`disableReactions`	`bool?`	`false`	Toggle reactions
`enableSwipeToReply`	`bool`	`true`	Enable swipe-to-reply gesture
`startFromUnreadMessages`	`bool`	`false`	Scroll to first unread on open
`loadLastAgentConversation`	`bool`	`false`	Loads the most recent existing agent conversation on start
`showMarkAsUnreadOption`	`bool`	`false`	Show “Mark as Unread” in long-press options
`goToMessageId`	`int?`	`null`	Scroll to a specific message after load
`hideFlagOption`	`bool`	`false`	Hide the Flag/Report option from message long-press actions
`hideFlagRemarkField`	`bool`	`false`	Hide the optional remark/context text field in the flag dialog
`flagReasonLocalizer`	`String Function(String reasonId)?`	`null`	Custom localizer that converts a flag-reason ID into a display string

* One of user or group is required.

Custom View Slots

Header View

Custom view displayed at the top of the message list.

Dart

CometChatMessageList(
  user: user,
  headerView: (context, {user, group, parentMessageId}) {
    return Container(
      padding: EdgeInsets.all(8),
      child: Text("Pinned Messages"),
    );
  },
)

Custom view displayed at the bottom of the message list.

Dart

CometChatMessageList(
  user: user,
  footerView: (context, {user, group, parentMessageId}) {
    return Container(
      padding: EdgeInsets.all(8),
      child: Text("End of messages"),
    );
  },
)

State Views

Dart

CometChatMessageList(
  user: user,
  emptyStateView: (context) => Center(child: Text("No messages yet")),
  errorStateView: (context) => Center(child: Text("Something went wrong")),
  loadingStateView: (context) => Center(child: CircularProgressIndicator()),
  emptyChatGreetingView: (context) => Center(child: Text("Say hello!")),
)

Text Formatters (Mentions)

Dart

CometChatMessageList(
  user: user,
  textFormatters: [
    CometChatMentionsFormatter(),
  ],
)

Message Templates

Override or extend message bubble rendering:

Dart

// Replace all templates
CometChatMessageList(
  user: user,
  templates: getCustomTemplates(),
)

// Add/override specific templates (merged with defaults)
CometChatMessageList(
  user: user,
  addTemplate: [
    CometChatMessageTemplate(
      type: MessageTypeConstants.text,
      category: MessageCategoryConstants.message,
      contentView: (message, context, alignment, {additionalConfigurations}) {
        return Text((message as TextMessage).text,
          style: TextStyle(color: Colors.red));
      },
    ),
  ],
)

See Message Template for the full template structure.

Message Option Visibility

Property	Default	Description
`hideCopyMessageOption`	`false`	Hide “Copy Message”
`hideDeleteMessageOption`	`false`	Hide “Delete Message”
`hideEditMessageOption`	`false`	Hide “Edit Message”
`hideMessageInfoOption`	`false`	Hide “Message Info”
`hideMessagePrivatelyOption`	`false`	Hide “Message Privately”
`hideReactionOption`	`false`	Hide “Reaction”
`hideReplyInThreadOption`	`false`	Hide “Reply in Thread”
`hideTranslateMessageOption`	`false`	Hide “Translate Message”
`hideShareMessageOption`	`false`	Hide “Share Message”
`hideModerationView`	`null`	Hide moderation view

Common Patterns

Thread replies view

Dart

CometChatMessageList(
  user: user,
  parentMessageId: parentMessage.id,
)

Jump to a specific message

Dart

CometChatMessageList(
  user: user,
  goToMessageId: 12345,
)

Start from unread messages

Dart

CometChatMessageList(
  user: user,
  startFromUnreadMessages: true,
)

Load last agent conversation

Resume the most recent AI agent conversation on start:

Dart

CometChatMessageList(
  user: user,
  loadLastAgentConversation: true,
)

Flag / Report a message

Flag/report is available by default from the message long-press menu. Toggle its visibility and customize the dialog:

Dart

CometChatMessageList(
  user: user,
  // hide the Flag option entirely
  hideFlagOption: false,
  // hide the optional "Remark" text field in the flag dialog
  hideFlagRemarkField: false,
  // localize reason IDs to your own display strings
  flagReasonLocalizer: (reasonId) {
    switch (reasonId) {
      case 'spam':
        return 'Spam or unsolicited';
      case 'inappropriate':
        return 'Inappropriate content';
      default:
        return reasonId;
    }
  },
)

Mark a message as unread

Expose the “Mark as Unread” option in the long-press menu:

Dart

CometChatMessageList(
  user: user,
  showMarkAsUnreadOption: true,
)

Advanced

BLoC Access

Provide a custom MessageListBloc to override behavior:

Dart

CometChatMessageList(
  user: user,
  messageListBloc: CustomMessageListBloc(user: user),
)

Extending MessageListBloc

MessageListBloc uses the ListBase<BaseMessage> mixin with override hooks:

Dart

class CustomMessageListBloc extends MessageListBloc {
  CustomMessageListBloc({required User user}) : super(user: user);

  @override
  void onItemAdded(BaseMessage item, List<BaseMessage> updatedList) {
    // Custom logic when a message is added
    super.onItemAdded(item, updatedList);
  }
}

For ListBase override hooks (onItemAdded, onItemRemoved, onItemUpdated, onListCleared, onListReplaced), see BLoC & Data — ListBase Hooks.

Public BLoC Events

Event	Description
`LoadMessages(conversationWith, conversationType)`	Load initial messages
`LoadOlderMessages()`	Load older messages (scroll up)
`LoadNewerMessages()`	Load newer messages (scroll down)
`RefreshMessages()`	Refresh from the latest
`SyncMessages()`	Silently sync missed messages
`JumpToMessage(messageId)`	Jump to a specific message
`AddReaction(message, reaction)`	Add a reaction
`RemoveReaction(message, reaction)`	Remove a reaction
`MarkMessageAsRead(message)`	Mark a message as read
`MarkMessageAsUnread(...)`	Mark a message as unread
`LoadFromUnread(conversationWith, conversationType)`	Load from first unread message

Public BLoC Methods

O(1) Lookup Methods

Method	Returns	Description
`findMessageIndex(messageId)`	`int?`	Find message index by ID
`findMessageIndexByMuid(muid)`	`int?`	Find message index by muid (pending messages)
`findMessage(messageId)`	`BaseMessage?`	Get message by ID
`findMessageByMuid(muid)`	`BaseMessage?`	Get message by muid

ValueNotifier Accessors (Isolated Rebuilds)

Method	Returns	Description
`getReceiptNotifier(messageId)`	`ValueNotifier<MessageReceiptStatus>`	Per-message receipt status notifier
`getReceiptNotifierForMessage(message)`	`ValueNotifier<MessageReceiptStatus>`	Receipt notifier handling both ID and muid
`getTypingNotifier(conversationId)`	`ValueNotifier<List<TypingIndicator>>`	Per-conversation typing notifier
`getThreadReplyCountNotifier(parentMessageId)`	`ValueNotifier<int>`	Per-message thread reply count notifier

MessageReceiptStatus Enum

Value	Description
`sending`	Message is being sent (id = 0)
`sent`	Message has been sent to server
`delivered`	Message has been delivered to recipient
`read`	Message has been read by recipient
`error`	Message failed to send

Operations Stream

The BLoC exposes an operationsStream consumed by CometChatAnimatedMessageList for smooth animations:

Operation	Description
`MessageOperation.insert(message, index)`	Insert a single message
`MessageOperation.insertAll(messages, index)`	Insert a batch of messages
`MessageOperation.update(oldMessage, newMessage, index)`	Replace a message in-place
`MessageOperation.remove(message, index)`	Remove a message
`MessageOperation.set(messages)`	Replace the entire list

Style

Dart

CometChatMessageList(
  user: user,
  style: CometChatMessageListStyle(
    backgroundColor: Color(0xFFFEEDE1),
    outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(
      backgroundColor: Color(0xFFF76808),
    ),
    incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle(
      backgroundColor: Colors.white,
    ),
  ),
)

See Component Styling and Message Bubble Styling for the full reference.

Next Steps

Message Header

Display user/group info in the app bar

Message Composer

Rich input for sending messages

Message Template

Customize message bubble structure

Component Styling

Detailed styling reference

​Where It Fits

​Quick Start

​Filtering

​Actions and Events

​Callback Methods

​onThreadRepliesClick

​onError

​onLoad

​onEmpty

​onReactionClick

​onReactionLongPress

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​Header View

​Footer View

​State Views

​Text Formatters (Mentions)

​Message Templates

​Message Option Visibility

​Common Patterns

​Thread replies view

​Jump to a specific message

​Start from unread messages

​Load last agent conversation

​Flag / Report a message

​Mark a message as unread

​Advanced

​BLoC Access

​Extending MessageListBloc

​Public BLoC Events

​Public BLoC Methods

​O(1) Lookup Methods

​ValueNotifier Accessors (Isolated Rebuilds)

​MessageReceiptStatus Enum

​Operations Stream

​Style

​Next Steps

Message Header

Message Composer

Message Template

Component Styling

Where It Fits

Quick Start

Filtering

Actions and Events

Callback Methods

`onThreadRepliesClick`

`onError`

`onLoad`

`onEmpty`

`onReactionClick`

`onReactionLongPress`

SDK Events (Real-Time, Automatic)

Functionality

Custom View Slots

Header View

Footer View

State Views

Text Formatters (Mentions)

Message Templates

Message Option Visibility

Common Patterns

Thread replies view

Jump to a specific message

Start from unread messages

Load last agent conversation

Flag / Report a message

Mark a message as unread

Advanced

BLoC Access

Extending MessageListBloc

Public BLoC Events

Public BLoC Methods

O(1) Lookup Methods

ValueNotifier Accessors (Isolated Rebuilds)

MessageReceiptStatus Enum

Operations Stream

Style

Next Steps