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
`showMarkAsUnreadOption`	`bool`	`false`	Show “Mark as Unread” in long-press options
`goToMessageId`	`int?`	`null`	Scroll to a specific message after load

* 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,
)

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

​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

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