Message List - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatMessageList`
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	Scrollable list of messages for a conversation with real-time updates, reactions, threaded replies, and message actions.
Data props	`user` · `group` · `messagesRequestBuilder` · `templates` · `addTemplate` · `parentMessageId` · `reactionsRequestBuilder`
Actions	`onError` · `onLoad` · `onEmpty` · `onThreadRepliesClick` · `addMoreReactionTap` · `onReactionClick` · `onReactionLongPress` · `onReactionListItemClick` — details
View slots	`headerView` · `footerView` · `loadingStateView` · `emptyStateView` · `errorStateView` · `emptyChatGreetingView` — details
Styling	`style` — the app `ThemeData` does not reach inside a kit widget, so scope colours here.
Layout	Fills its parent — place it in an `Expanded` (or a sized box) inside a `Column`, or layout throws an unbounded-height error at render.
Custom message types	Use `addTemplate:` — never `templates:`. `addTemplate` merges your `CometChatMessageTemplate` with the defaults and folds its type/category into the list’s fetch + realtime filter; `templates` replaces the default set and only registers the bubble, so a custom type sends fine and never appears, with no error. A hand-rolled `MessagesRequestBuilder` does not help — the list always overrides `uid`/`guid`/`types`/`categories` on it.
Stitching	Pair with `CometChatMessageHeader` and `CometChatMessageComposer`, passing the same `user` or `group` to all three.
Prerequisites	`CometChatUIKit` initialised and a user logged in.
Full props	89 props

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");
  },
)

`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
`onMessagePinned` / `onMessageUnpinned`	Restamps the message’s pin state in place
`onMessageSaved` / `onMessageUnsaved`	Restamps the message’s saved state (the logged-in user’s devices only)
Connection reconnected	Triggers silent sync to fetch missed messages

Functionality

Property	Type	Default	Description
`user`	`User?`	`null`	User for 1-on-1 conversation
`group`	`Group?`	`null`	Group for group conversation
`messageListBloc`	`MessageListBloc?`	`null`	Optional external `MessageListBloc` instance.
`messagesRequestBuilder`	`MessagesRequestBuilder?`	`null`	Request builder used to fetch the message list. Note the widget always overrides `uid`, `guid`, `types` and `categories` on whatever builder you pass.
`templates`	`List<CometChatMessageTemplate>?`	`null`	REPLACES the default message templates. For a message type of your own use `addTemplate` instead — `templates` only registers the bubble and does not widen the fetch filter, so a custom type sends successfully and never appears.
`addTemplate`	`List<CometChatMessageTemplate>?`	`null`	Merges templates with the defaults. Each template’s type and category are also folded into the list’s fetch and realtime filter, which is what makes a custom message type actually render.
`parentMessageId`	`int?`	`null`	Parent message ID for thread replies
`withParent`	`bool`	`true`	Whether to include the parent message in thread results (default: false). Set to true for AI chat history where the parent message should appear in the list.
`hideDeletedMessages`	`bool`	`false`	Hide deleted messages entirely
`disableSoundForMessages`	`bool`	`false`	Disable message sounds
`disableReceipts`	`bool`	`false`	Disable read/delivery receipts
`hideReplies`	`bool`	`true`	Hide thread replies in main conversation
`headerView`	`HeaderFooterBuilder?`	`null`	Custom header view displayed above the message list. Validates: Requirements 13.2
`footerView`	`HeaderFooterBuilder?`	`null`	Custom footer view displayed below the message list. Validates: Requirements 13.2
`loadingStateView`	`WidgetBuilder?`	`null`	`loadingStateView` is a parameter used to show the loading state view in case of loading
`emptyStateView`	`WidgetBuilder?`	`null`	`emptyStateView` returns view fow empty state
`errorStateView`	`WidgetBuilder?`	`null`	`errorStateView` is a parameter used to show the error state view in case of any error
`emptyChatGreetingView`	`WidgetBuilder?`	`null`	View shown in an empty conversation, in place of the generic empty state.
`style`	`CometChatMessageListStyle?`	`null`	Style configuration for the message list.
`scrollController`	`ScrollController?`	`null`	Optional scroll controller
`alignment`	`ChatAlignment`	`ChatAlignment.standard`	Chat alignment setting
`onError`	`OnError?`	`null`	`onError` callback triggered in case any error happens when fetching data
`onLoad`	`OnLoad<BaseMessage>?`	`null`	Called once the first page of messages has loaded.
`onEmpty`	`OnEmpty?`	`null`	`onEmpty` callback triggered when the list is empty
`stateCallBack`	`Function(CometChatMessageListControllerProtocol controller)?`	`null`	Exposes the widget’s state so a host can drive it imperatively.
`controller`	`CometChatMessageListController?`	`null`	Lets the host jump the list to a message after it has mounted. See Jump to a message. Available since v6.1.1.
`customSoundForMessages`	`String?`	`null`	`customSoundForMessages` set custom sound for messages
`customSoundForMessagePackage`	`String?`	`null`	`customSoundForMessagePackage` package name to show icon from
`readIcon`	`Widget?`	`null`	`readIcon` widget visible when readAt != null in `BaseMessage`. If blank will load default readIcon
`deliveredIcon`	`Widget?`	`null`	`deliveredIcon` widget visible while deliveredAt != null in `BaseMessage`. If blank will load default deliveredIcon
`sentIcon`	`Widget?`	`null`	`sentIcon` widget visible while sentAt != null and deliveredAt is null in `BaseMessage`. If blank will load default sentIcon
`waitIcon`	`Widget?`	`null`	`waitIcon` widget visible while sentAt and deliveredAt is null in `BaseMessage`. If blank will load default waitIcon
`avatarVisibility`	`bool?`	`true`	Toggle avatar visibility
`enableMultipleAttachments`	`bool`	`true`	Render multi-attachment media messages as grouped per-type bubbles. See Multiple Attachments
`hideTimestamp`	`bool?`	`null`	Toggle timestamp visibility
`datePattern`	`String Function(BaseMessage message)?`	`null`	Builds the timestamp string shown on a bubble.
`dateSeparatorPattern`	`String Function(DateTime dateTime)?`	`null`	Builds the date string shown on the separator between days.
`dateSeparatorStyle`	`CometChatDateStyle?`	`null`	Style for the date separator shown between days.
`hideDateSeparator`	`bool?`	`false`	Hide date separators
`hideStickyDate`	`bool?`	`false`	Hide floating sticky date header
`onThreadRepliesClick`	`ThreadRepliesClick?`	`null`	Called when the thread-replies indicator on a bubble is tapped. Wire this to push your thread screen.
`hideThreadView`	`bool?`	`null`	When true, hides the thread-replies indicator on bubbles.
`receiptsVisibility`	`bool?`	`true`	Toggle read receipts
`disableReactions`	`bool?`	`false`	Toggle reactions
`addReactionIcon`	`Widget?`	`null`	`addReactionIcon` sets custom icon for adding reaction
`addMoreReactionTap`	`Function(BaseMessage message)?`	`null`	Called when the ‘add reaction’ affordance is tapped.
`favoriteReactions`	`List<String>?`	`null`	`favoriteReactions` is a list of frequently used reactions
`onReactionClick`	`Function(String? emoji, BaseMessage message)?`	`null`	Called when an existing reaction chip is tapped.
`onReactionLongPress`	`Function(String? emoji, BaseMessage message)?`	`null`	Called when an existing reaction chip is long-pressed.
`onReactionListItemClick`	`Function(String? reaction, BaseMessage? message)?`	`null`	Called when a row in the reaction list sheet is tapped.
`reactionsRequestBuilder`	`ReactionsRequestBuilder?`	`null`	Request builder used to fetch the reaction list for a message.
`textFormatters`	`List<CometChatTextFormatter>?`	`null`	`textFormatters` is a list of `CometChatTextFormatter` that can be used to format text
`additionalConfigurations`	`AdditionalConfigurations?`	`null`	Configuration passed down to the bubble views this list renders.
`disableMentions`	`bool?`	`null`	`disableMentions` disables mentions in the composer
`mentionAllLabel`	`String?`	`null`	`mentionAllLabel` is the label to display for @all mention (default: localized “Notify All”)
`mentionAllLabelId`	`String?`	`null`	`mentionAllLabelId` is the ID for @all mention (default: “all”)
`padding`	`EdgeInsetsGeometry?`	`null`	`padding` sets the padding for snackBar
`margin`	`EdgeInsetsGeometry?`	`null`	`margin` sets the margin for snackBar
`width`	`double?`	`null`	`width` provides width to the widget
`height`	`double?`	`null`	`height` provides height to the widget
`hideCopyMessageOption`	`bool?`	`false`	`hideCopyMessageOption` This prop defines whether a user can copy message or not.
`hideDeleteMessageOption`	`bool?`	`false`	`hideDeleteMessageOption` This prop defines whether Delete Message option should be visible or not.
`hideEditMessageOption`	`bool?`	`false`	`hideEditMessageOption` This prop defines whether Edit Message option should be visible or not.
`hideGroupActionMessages`	`bool?`	`false`	Hide group action messages
`hideMessageInfoOption`	`bool?`	`false`	`hideMessageInfoOption` This prop defines whether a user can fetch information about the message whether it’s received or not.
`hideMessagePrivatelyOption`	`bool?`	`false`	`hideMessagePrivatelyOption` This prop defines whether a user can privately message other member of the group or not.
`hideReactionOption`	`bool?`	`false`	`hideReactionOption` This prop defines whether Reaction option should be visible or not.
`hideReplyInThreadOption`	`bool?`	`false`	`hideReplyInThreadOption` This prop defines whether Reply In Thread option should be visible or not.
`hideReplyOption`	`bool?`	`false`	`hideReplyOption` This prop defines whether the inline Reply option should be visible or not.
`hideTranslateMessageOption`	`bool?`	`false`	`hideTranslateMessageOption` This prop defines whether Reply In Thread option should be visible or not.
`hideShareMessageOption`	`bool?`	`false`	`hideShareMessageOption` This prop defines whether share option should be visible or not.
`hideModerationView`	`bool?`	`null`	When true, hides the moderation affordance on bubbles.
`enableConversationStarters`	`bool?`	`false`	When true, shows AI conversation starters in an empty conversation.
`enableSmartReplies`	`bool?`	`false`	When true, shows AI smart replies beneath the list.
`smartRepliesDelayDuration`	`int?`	`10000`	Milliseconds to wait after the last message before smart replies appear.
`smartRepliesKeywords`	`List<String>?`	`const [ 'what', 'when', 'why', 'who', '…`	Keywords in the last message that trigger smart replies.
`suggestedMessages`	`List<String>?`	`null`	Suggested messages offered in an empty conversation.
`hideSuggestedMessages`	`bool?`	`false`	When true, suppresses the suggested messages.
`emptyStateText`	`String?`	`null`	`emptyStateText` text to be displayed when the list is empty
`errorStateText`	`String?`	`null`	`errorStateText` is a parameter used to show the error state text in case of any error
`dateTimeFormatterCallback`	`DateTimeFormatterCallback?`	`null`	`dateTimeFormatterCallback` is a callback that can be used to format the date and time
`enableSwipeToReply`	`bool`	`true`	Enable swipe-to-reply gesture
`goToMessageId`	`int?`	`null`	Scroll to a specific message after load
`showMarkAsUnreadOption`	`bool`	`false`	Show “Mark as Unread” in long-press options
`startFromUnreadMessages`	`bool`	`false`	Scroll to first unread on open
`hideFlagOption`	`bool`	`false`	Hide the Flag/Report option from message long-press actions
`flagReasonLocalizer`	`String Function(String reasonId)?`	`null`	Custom localizer that converts a flag-reason ID into a display string
`hideFlagRemarkField`	`bool`	`false`	Hide the optional remark/context text field in the flag dialog
`loadLastAgentConversation`	`bool`	`false`	Loads the most recent existing agent conversation on start

* 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”
`hidePinMessageOption`	`false`	Hide “Pin message” (shown while the message is unpinned). Available since v6.1.1.
`hideUnpinMessageOption`	`false`	Hide “Unpin message” (shown while the message is pinned). Available since v6.1.1.
`hideSaveMessageOption`	`false`	Hide “Save message” (shown while the message is unsaved). Available since v6.1.1.
`hideUnsaveMessageOption`	`false`	Hide “Unsave message” (shown while the message is saved). Available since v6.1.1.
`hideThreadSubscriptionOption`	`false`	Hide “Subscribe to thread” / “Unsubscribe from thread”. Only shown when `UIKitSettings.enableThreadSubscription` is on — see the Thread Subscription guide. Available since v6.1.1.
`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;
    }
  },
)

Pin or save a message

Available since v6.1.1 With the features enabled, the action menu offers Pin message / Unpin message and Save message / Unsave message, the label following the message’s current state. They are wired to the SDK’s Pin A Message and Save A Message APIs — no setup is needed:

The options appear on any sent, non-deleted message, thread replies included. They are withheld from deleted messages, messages not yet sent or still pending moderation, your own messages that moderation disapproved, and group action messages, and they hide themselves when CometChat.isPinMessageEnabled() / CometChat.isSaveMessageEnabled() returns false.
Pin permission is enforced by the server, not the UI Kit. The Pin / Unpin option is shown to every participant; a user who lacks permission gets a “You don’t have permission to perform this action.” toast when they tap it. Save has no role gate.
All four actions apply immediately, without a confirmation, and show a toast (“Message pinned”, “Message saved”, …). Hitting a cap shows “You can pin up to N messages in this conversation.” or “You can save up to N messages.”, with N taken from the server’s error.
A pinned message shows a pin glyph, and a message the user saved shows a bookmark glyph, before the bubble’s timestamp. The glyphs update live, including for pins made by other members and saves made on the user’s other devices.

Each state has its own flag, because the menu shows Pin or Unpin depending on the message. Hiding pinning entirely takes hidePinMessageOption and hideUnpinMessageOption; save works the same way.

Dart

CometChatMessageList(
  user: user,
  // both flags per feature — one per rendered state
  hidePinMessageOption: true,
  hideUnpinMessageOption: true,
  hideSaveMessageOption: true,
  hideUnsaveMessageOption: true,
)

Jump to a message

Available since v6.1.1 goToMessageId is read once when the list mounts, so it cannot re-aim a list that is already on screen — the case you hit when a pinned or saved row is tapped and the conversation is already open. CometChatMessageListController covers that. Create it in your State, pass it as controller, and call jumpToMessage: the list scrolls to the message and highlights it, fetching the page around it first when it is not loaded yet.

Dart

final _controller = CometChatMessageListController();

CometChatMessageList(
  user: user,
  controller: _controller,
)

// later — e.g. from CometChatPinnedMessages.onItemTap
await _controller.jumpToMessage(message.id);

It attaches on mount and detaches on dispose. Calls made while no list is attached return false rather than throwing, and isAttached reports the current state.

A different class of the same name existed in v5, where it exposed list state. That one is replaced by MessageListBloc — see Upgrading from v5. The v6 CometChatMessageListController does only imperative jumps.

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

​Pin or save a message

​Jump to 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

Pin or save a message

Jump to 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