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
`enableMultipleAttachments`	`bool`	`true`	Render multi-attachment media messages as grouped per-type bubbles. See Multiple Attachments
`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.

Multiple Attachments

A media message carrying several attachments renders with a dedicated per-type bubble: a media grid for images and videos, inline player rows for audio files, and a connected card stack for documents.

Message type	Bubble	Rendering
`image`	`CometChatImagesBubble`	Grid — 1, 2, 3 or 2×2, with a `+N` tile past 4
`video`	`CometChatVideosBubble`	Grid with poster frames, a play badge and an `m:ss` chip
`audio` (files)	`CometChatAudiosBubble`	Stacked player rows; collapses past 4
`audio` (voice note)	`CometChatAudioBubble`	The classic waveform player
`file`	`CometChatFilesBubble`	Connected card stack with a “+N more” toggle

Tapping any image/video cell opens the full-screen media viewer, paged across the message’s image, video and audio attachments.

A voice note always renders as the classic single audio bubble, whatever the flag below — it is single by nature. Only picked audio files use the multi-attachment bubble.

A message always carries attachments of a single kind, so each one renders with the bubble for that kind. Picking a mix — say three photos and a PDF — sends an image message and a file message: the photos render as a grid, the PDF as a card. They share a batchId and group as described below.

Grouping

Messages produced by one send share batchId, batchIndex and batchSize metadata, and the list presents them as one block:

the avatar and sender name appear on the first message only
the timestamp and receipt appear on the last message only
reactions stay attached to their individual message
the caption rides on the last message of the batch

Deleting one message of a batch takes it out of the group: it renders as a standalone delete bubble, and its neighbours treat it as a batch boundary.

Enable or disable

Dart

CometChatMessageList(
  user: user,
  enableMultipleAttachments: true, // default
)

Set it to false to render the classic single-attachment bubbles (CometChatImageBubble, CometChatVideoBubble, CometChatAudioBubble, CometChatFileBubble) instead. Those bubbles are deprecated and remain only for that path. You can also drive it per-template through AdditionalConfigurations:

Dart

AdditionalConfigurations(enableMultipleAttachments: false)

Styling

Each bubble has its own style class:

Bubble	Style
`CometChatImagesBubble`	`CometChatImagesBubbleStyle`
`CometChatVideosBubble`	`CometChatVideosBubbleStyle`
`CometChatAudiosBubble`	`CometChatAudiosBubbleStyle`
`CometChatFilesBubble`	`CometChatFilesBubbleStyle`

Where a property has an equivalent on the old singular bubble it keeps the same name (playIconColor, titleTextStyle, backgroundColor…), so migrating is a rename of the class, not of every field. Grid-only knobs — tileBorderRadius, gridSpacing, overflowScrimColor, captionTextStyle, the duration chip and the “+N more” toggle — have no old counterpart.

These bubbles are styled only through theme extensions. The per-message-list slots — AdditionalConfigurations.imageBubbleStyle and CometChatIncoming/OutgoingMessageBubbleStyle.imageBubbleStyle — still target the deprecated singular bubbles and are ignored while enableMultipleAttachments is true. Move that styling into the theme.

Dart

MaterialApp(
  theme: ThemeData(
    extensions: const [
      CometChatImagesBubbleStyle(gridSpacing: 3, tileBorderRadius: 8),
      CometChatVideosBubbleStyle(showVideoDuration: true),
      CometChatFilesBubbleStyle(titleTextStyle: TextStyle(fontSize: 15)),
    ],
  ),
)

To stage and send multiple attachments, see Message Composer.

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

​Multiple Attachments

​Grouping

​Enable or disable

​Styling

​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

Multiple Attachments

Grouping

Enable or disable

Styling

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