Message List - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatMessageList",
  "package": "cometchat_chat_uikit",
  "import": "import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';",
  "description": "A composite widget that displays a list of messages with real-time operations. Includes various message types such as Text Messages, Media Messages, Stickers, and more.",
  "primaryOutput": {
    "prop": "onThreadRepliesClick",
    "type": "void Function(BaseMessage, BuildContext, {CometChatMessageTemplate?})?"
  },
  "props": {
    "data": {
      "user": {
        "type": "User?",
        "default": "null",
        "note": "User object for user message list (one of user or group is required)"
      },
      "group": {
        "type": "Group?",
        "default": "null",
        "note": "Group object for group message list (one of user or group is required)"
      },
      "messagesRequestBuilder": {
        "type": "MessagesRequestBuilder?",
        "default": "null",
        "note": "Custom request builder for filtering messages"
      },
      "templates": {
        "type": "List<CometChatMessageTemplate>?",
        "default": "null",
        "note": "Message templates for the list"
      }
    },
    "callbacks": {
      "onThreadRepliesClick": "void Function(BaseMessage, BuildContext, {CometChatMessageTemplate?})?",
      "onError": "OnError?",
      "onLoad": "OnLoad<BaseMessage>?",
      "onEmpty": "OnEmpty?",
      "onReactionClick": "Function(String?, BaseMessage)?",
      "onReactionLongPress": "Function(String?, BaseMessage)?",
      "onReactionListItemClick": "Function(String?, BaseMessage?)?"
    },
    "visibility": {
      "hideTimestamp": { "type": "bool?", "default": null },
      "avatarVisibility": { "type": "bool?", "default": true },
      "receiptsVisibility": { "type": "bool?", "default": true },
      "disableReactions": { "type": "bool?", "default": false },
      "hideStickyDate": { "type": "bool?", "default": false },
      "hideReplyInThreadOption": { "type": "bool?", "default": false },
      "hideEditMessageOption": { "type": "bool?", "default": false },
      "hideDeleteMessageOption": { "type": "bool?", "default": false },
      "hideGroupActionMessages": { "type": "bool?", "default": false }
    },
    "sound": {
      "disableSoundForMessages": { "type": "bool?", "default": null },
      "customSoundForMessages": { "type": "String?", "default": null }
    },
    "viewSlots": {
      "loadingStateView": "WidgetBuilder?",
      "emptyStateView": "WidgetBuilder?",
      "errorStateView": "WidgetBuilder?",
      "headerView": "Widget? Function(BuildContext, {User?, Group?, int?})?",
      "footerView": "Widget? Function(BuildContext, {User?, Group?, int?})?"
    },
    "formatting": {
      "alignment": { "type": "ChatAlignment", "default": "ChatAlignment.standard" },
      "datePattern": { "type": "String Function(BaseMessage)?", "default": null },
      "dateSeparatorPattern": { "type": "String Function(DateTime)?", "default": null }
    }
  },
  "events": [],
  "sdkListeners": [
    "onMessageReceived",
    "onMessageEdited",
    "onMessageDeleted",
    "onTypingStarted",
    "onTypingEnded"
  ],
  "compositionExample": {
    "description": "CometChatMessageList is typically used within CometChatMessages, paired with CometChatMessageHeader and CometChatMessageComposer",
    "components": ["CometChatMessageHeader", "CometChatMessageComposer", "CometChatMessages"],
    "flow": "User/Group → MessageList displays messages → Real-time updates via SDK listeners"
  },
  "types": {
    "CometChatMessageListStyle": {
      "backgroundColor": "Color?",
      "border": "BoxBorder?",
      "borderRadius": "BorderRadiusGeometry?",
      "incomingMessageBubbleStyle": "CometChatIncomingMessageBubbleStyle?",
      "outgoingMessageBubbleStyle": "CometChatOutgoingMessageBubbleStyle?",
      "avatarStyle": "CometChatAvatarStyle?"
    }
  }
}

Where It Fits

CometChatMessageList is a Composite Widget that displays a list of messages and effectively manages real-time operations. It includes various types of messages such as Text Messages, Media Messages, Stickers, and more. CometChatMessageList is primarily a list of the base widget MessageBubble. The MessageBubble Widget is utilized to create different types of chat bubbles depending on the message type.

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

// CometChatMessageList is typically used within CometChatMessages
// or as part of a custom messaging screen
class MessagingScreen extends StatelessWidget {
  final User user;
  
  const MessagingScreen({required this.user});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          CometChatMessageHeader(user: user),
          Expanded(child: CometChatMessageList(user: user)),
          CometChatMessageComposer(user: user),
        ],
      ),
    );
  }
}

Minimal Render

The simplest way to render CometChatMessageList:

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

// For a user conversation
CometChatMessageList(
  user: user,
)

// For a group conversation
CometChatMessageList(
  group: group,
)

Simply adding the MessageList component to the layout will only display the loading indicator. To fetch messages for a specific entity, you need to supplement it with User or Group Object.

Filtering CometChatMessageList

Use the messagesRequestBuilder prop to filter which messages appear in the list.

Filter Recipes

Recipe	Code
Limit messages	`MessagesRequestBuilder()..limit = 30`
Search messages	`MessagesRequestBuilder()..searchKeyword = "keyword"`
Filter by type	`MessagesRequestBuilder()..types = ["text"]`
Filter by category	`MessagesRequestBuilder()..categories = ["message"]`

Dart

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

The following parameters in messageRequestBuilder will always be altered inside the message list:

UID
GUID
types
categories

For the full MessagesRequestBuilder API, see the SDK documentation.

Actions and Events

Callback Props

Component-level callbacks that fire on specific user interactions:

Callback	Signature	Fires When
`onThreadRepliesClick`	`void Function(BaseMessage, BuildContext, {CometChatMessageTemplate?})?`	User clicks on thread indicator
`onError`	`OnError?`	An error occurs while fetching messages
`onLoad`	`OnLoad<BaseMessage>?`	List is successfully fetched and loaded
`onEmpty`	`OnEmpty?`	List is empty
`onReactionClick`	`Function(String?, BaseMessage)?`	User clicks on a reaction pill
`onReactionLongPress`	`Function(String?, BaseMessage)?`	User long presses on a reaction pill
`onReactionListItemClick`	`Function(String?, BaseMessage?)?`	User clicks on a reaction list item
`addMoreReactionTap`	`Function(BaseMessage)?`	User clicks “Add More Reactions” button

Dart

CometChatMessageList(
  user: user,
  onThreadRepliesClick: (message, context, {template}) {
    // Handle thread replies click
  },
  onError: (e) {
    // Handle error
  },
  onLoad: (list) {
    print("Messages loaded: ${list.length}");
  },
  onEmpty: () {
    print("No messages");
  },
  onReactionClick: (emoji, message) {
    // Handle reaction click
  },
)

SDK Events (Real-Time, Automatic)

The component automatically handles these SDK listeners for real-time updates:

SDK Listener	Handled Automatically
`onMessageReceived`	Adds new message to the list
`onMessageEdited`	Updates edited message in the list
`onMessageDeleted`	Removes deleted message from the list
`onTypingStarted`	Shows typing indicator
`onTypingEnded`	Hides typing indicator

Custom View Slots

Customize the appearance of CometChatMessageList by replacing default views with your own widgets.

Slot	Signature	Replaces
`loadingStateView`	`WidgetBuilder?`	Loading spinner
`emptyStateView`	`WidgetBuilder?`	Empty state display
`errorStateView`	`WidgetBuilder?`	Error state display
`headerView`	`Widget? Function(BuildContext, {User?, Group?, int?})?`	Header section
`footerView`	`Widget? Function(BuildContext, {User?, Group?, int?})?`	Footer section
`emptyChatGreetingView`	`WidgetBuilder?`	Empty chat greeting for AI
`newMessageIndicatorView`	`WidgetBuilder?`	New message indicator

Example: Custom Header View

Dart

CometChatMessageList(
  user: user,
  headerView: (context, {group, parentMessageId, user}) {
    return Container(
      width: double.maxFinite,
      color: Color(0xFFEDEAFA),
      padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8),
      child: Row(
        children: [
          Icon(Icons.notes_outlined, color: Color(0xFF6852D6)),
          SizedBox(width: 8),
          Text('Notes', style: TextStyle(color: Color(0xFF6852D6))),
        ],
      ),
    );
  },
)

Dart

CometChatMessageList(
  user: user,
  footerView: (context, {group, parentMessageId, user}) {
    return Container(
      width: double.maxFinite,
      color: Color(0xFFEDEAFA),
      padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8),
      child: Row(
        children: [
          Icon(Icons.sunny, color: Color(0xFF6852D6)),
          SizedBox(width: 8),
          Text('Ice Breakers', style: TextStyle(color: Color(0xFF6852D6))),
        ],
      ),
    );
  },
)

Example: Custom Loading State View

Dart

CometChatMessageList(
  user: user,
  loadingStateView: (context) {
    return Center(
      child: CircularProgressIndicator(),
    );
  },
)

Example: Custom Empty State View

Dart

CometChatMessageList(
  user: user,
  emptyStateView: (context) {
    return Center(
      child: Text("No messages yet. Start the conversation!"),
    );
  },
)

Example: Custom Error State View

Dart

CometChatMessageList(
  user: user,
  errorStateView: (context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Text("Couldn't load messages"),
          ElevatedButton(
            onPressed: () {
              // Retry logic
            },
            child: Text("Retry"),
          ),
        ],
      ),
    );
  },
)

Styling

Customize the appearance of CometChatMessageList using CometChatMessageListStyle.

Style Properties

Property	Type	Description
`backgroundColor`	`Color?`	Background color of the message list
`border`	`BoxBorder?`	Border of the message list
`borderRadius`	`BorderRadiusGeometry?`	Border radius of the message list
`avatarStyle`	`CometChatAvatarStyle?`	Style for avatar in message bubble
`emptyStateTextStyle`	`TextStyle?`	Style for empty state text
`emptyStateTextColor`	`Color?`	Color for empty state text
`emptyStateSubtitleStyle`	`TextStyle?`	Style for empty state subtitle
`emptyStateSubtitleColor`	`Color?`	Color for empty state subtitle
`errorStateTextStyle`	`TextStyle?`	Style for error state text
`errorStateTextColor`	`Color?`	Color for error state text
`errorStateSubtitleStyle`	`TextStyle?`	Style for error state subtitle
`errorStateSubtitleColor`	`Color?`	Color for error state subtitle
`incomingMessageBubbleStyle`	`CometChatIncomingMessageBubbleStyle?`	Style for incoming message bubble
`outgoingMessageBubbleStyle`	`CometChatOutgoingMessageBubbleStyle?`	Style for outgoing message bubble
`messageInformationStyle`	`CometChatMessageInformationStyle?`	Style for message information
`messageOptionSheetStyle`	`CometChatMessageOptionSheetStyle?`	Style for message option sheet
`mentionsStyle`	`CometChatMentionsStyle?`	Style for mentions
`actionBubbleStyle`	`CometChatActionBubbleStyle?`	Style for group action bubbles
`reactionListStyle`	`CometChatReactionListStyle?`	Style for reaction list
`reactionsStyle`	`CometChatReactionsStyle?`	Style for reactions
`aiSmartRepliesStyle`	`CometChatAISmartRepliesStyle?`	Style for smart replies
`aiConversationStarterStyle`	`CometChatAIConversationStarterStyle?`	Style for conversation starter
`aiConversationSummaryStyle`	`CometChatAIConversationSummaryStyle?`	Style for conversation summary
`aiAssistantSuggestedMessageTextStyle`	`TextStyle?`	Text style for AI suggested messages
`aiAssistantSuggestedMessageTextColor`	`Color?`	Text color for AI suggested messages
`aiAssistantSuggestedMessageBorder`	`Border?`	Border for AI suggested messages
`aiAssistantSuggestedMessageBorderRadius`	`BorderRadius?`	Border radius for AI suggested messages
`aiAssistantSuggestedMessageBackgroundColor`	`Color?`	Background color for AI suggested messages
`aiAssistantSuggestedMessageIconColor`	`Color?`	Icon color for AI suggested messages
`emptyChatGreetingTitleTextColor`	`Color?`	Text color for empty chat greeting title
`emptyChatGreetingTitleTextStyle`	`TextStyle?`	Text style for empty chat greeting title
`emptyChatGreetingSubtitleTextColor`	`Color?`	Text color for empty chat greeting subtitle
`emptyChatGreetingSubtitleTextStyle`	`TextStyle?`	Text style for empty chat greeting subtitle
`flagMessageStyle`	`CometchatFlagMessageStyle?`	Style for flag message dialog
`newMessageIndicatorStyle`	`CometChatNewMessageIndicatorStyle?`	Style for new message indicator

Example: Custom Styling

Dart

CometChatMessageList(
  user: user,
  style: CometChatMessageListStyle(
    backgroundColor: Color(0xFFFEEDE1),
    outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(
      backgroundColor: Color(0xFFF76808),
    ),
  ),
)

Example: Custom Avatar Style

Dart

CometChatMessageList(
  user: user,
  style: CometChatMessageListStyle(
    avatarStyle: CometChatAvatarStyle(
      border: Border.all(width: 5),
      borderRadius: 20,
      backgroundColor: Colors.red,
    ),
  ),
)

Example: Custom Mentions Style

Dart

CometChatMessageList(
  user: user,
  textFormatters: [
    CometChatMentionsFormatter(
      style: CometChatMentionsStyle(
        mentionSelfTextBackgroundColor: Color(0xFFF76808),
        mentionTextBackgroundColor: Colors.white,
        mentionTextColor: Colors.black,
        mentionSelfTextColor: Colors.white,
      ),
    ),
  ],
)

Advanced

Message Templates

CometChatMessageTemplate is a pre-defined structure for creating message views that can be used as a starting point or blueprint for creating message bubbles.

Dart

List<CometChatMessageTemplate> getTemplate() {
  // Creating a text template
  CometChatMessageTemplate textTemplate = ChatConfigurator.getDataSource().getTextMessageTemplate();
  textTemplate.contentView = (BaseMessage baseMessage, BuildContext buildContext, BubbleAlignment alignment, {AdditionalConfigurations? additionalConfigurations}) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: Text(
        (baseMessage as TextMessage).text,
        style: TextStyle(
          color: alignment == BubbleAlignment.left ? Colors.deepPurple : Colors.yellow,
          fontSize: 14,
          fontWeight: FontWeight.bold,
        ),
      ),
    );
  };

  // Creating a custom message template
  CometChatMessageTemplate customMessageTemplate = CometChatMessageTemplate(
    type: 'custom_template',
    category: 'custom_category',
    bubbleView: (message, context, alignment) => const Text('Custom message'),
  );

  return [textTemplate, customMessageTemplate];
}

// Usage
CometChatMessageList(
  user: user,
  templates: getTemplate(),
)

Android
iOS

Date Separator Pattern

Customize the date separator pattern:

Dart

CometChatMessageList(
  user: user,
  dateSeparatorPattern: (DateTime dateTime) {
    return DateFormat("dd/MM/yyyy").format(dateTime);
  },
)

Android
iOS

Date Pattern

Customize the date pattern for message receipts:

Dart

CometChatMessageList(
  user: user,
  datePattern: (message) {
    return DateFormat('EEE, M/d/y').format(message.sentAt!);
  },
)

Android
iOS

Props Reference

Prop	Type	Default	Description
`user`	`User?`	`null`	User object for user message list
`group`	`Group?`	`null`	Group object for group message list
`messagesRequestBuilder`	`MessagesRequestBuilder?`	`null`	Custom request builder for filtering
`style`	`CometChatMessageListStyle?`	-	Sets style for message list
`scrollController`	`ScrollController?`	-	Controller for the message list
`emptyStateText`	`String?`	-	Text when list is empty
`errorStateText`	`String?`	-	Text when error occurs
`loadingStateView`	`WidgetBuilder?`	-	View for loading state
`emptyStateView`	`WidgetBuilder?`	-	View for empty state
`errorStateView`	`WidgetBuilder?`	-	View for error state
`disableSoundForMessages`	`bool?`	`null`	Disables sound for messages
`customSoundForMessages`	`String?`	`null`	Custom sound URL
`readIcon`	`Widget?`	-	Custom read icon
`deliveredIcon`	`Widget?`	-	Custom delivered icon
`sentIcon`	`Widget?`	-	Custom sent icon
`waitIcon`	`Widget?`	-	Custom wait icon
`alignment`	`ChatAlignment`	`standard`	Chat alignment setting
`avatarVisibility`	`bool?`	`true`	Toggle avatar visibility
`datePattern`	`String Function(BaseMessage)?`	-	Custom date pattern
`hideTimestamp`	`bool?`	`null`	Toggle timestamp visibility
`templates`	`List<CometChatMessageTemplate>?`	-	Message templates
`onThreadRepliesClick`	`ThreadRepliesClick?`	-	Thread replies callback
`headerView`	`Widget? Function(...)?`	-	Custom header view
`footerView`	`Widget? Function(...)?`	-	Custom footer view
`dateSeparatorPattern`	`String Function(DateTime)?`	-	Date separator pattern
`onError`	`OnError?`	-	Error callback
`receiptsVisibility`	`bool?`	`true`	Toggle read receipts
`dateSeparatorStyle`	`CometChatDateStyle?`	-	Date separator style
`disableReactions`	`bool?`	`false`	Toggle reactions
`addReactionIcon`	`Widget?`	-	Custom add reaction icon
`favoriteReactions`	`List<String>?`	-	Frequently used reactions
`textFormatters`	`List<CometChatTextFormatter>?`	-	Text formatters
`disableMentions`	`bool?`	`null`	Disable mentions
`padding`	`EdgeInsetsGeometry?`	-	Padding for message list
`margin`	`EdgeInsetsGeometry?`	-	Margin for message list
`width`	`double?`	-	Width of message list
`height`	`double?`	-	Height of message list
`onLoad`	`OnLoad<BaseMessage>?`	-	Load callback
`onEmpty`	`OnEmpty?`	-	Empty callback
`onReactionClick`	`Function(String?, BaseMessage)?`	-	Reaction click callback
`onReactionLongPress`	`Function(String?, BaseMessage)?`	-	Reaction long press callback
`hideStickyDate`	`bool?`	`false`	Hide sticky date
`hideReplyInThreadOption`	`bool?`	`false`	Hide reply in thread option
`hideTranslateMessageOption`	`bool?`	`false`	Hide translate option
`hideEditMessageOption`	`bool?`	`false`	Hide edit option
`hideDeleteMessageOption`	`bool?`	`false`	Hide delete option
`hideReactionOption`	`bool?`	`false`	Hide reaction option
`hideMessagePrivatelyOption`	`bool?`	`false`	Hide message privately option
`hideCopyMessageOption`	`bool?`	`false`	Hide copy option
`hideMessageInfoOption`	`bool?`	`false`	Hide message info option
`hideGroupActionMessages`	`bool?`	`false`	Hide group action messages
`enableConversationStarters`	`bool?`	`false`	Enable conversation starters
`enableSmartReplies`	`bool?`	`false`	Enable smart replies
`hideShareMessageOption`	`bool?`	`false`	Hide share option
`smartRepliesDelayDuration`	`int?`	`10000`	Smart replies delay (ms)
`smartRepliesKeywords`	`List<String>?`	-	Smart replies keywords
`addTemplate`	`List<CometChatMessageTemplate>?`	-	Add custom templates
`dateTimeFormatterCallback`	`DateTimeFormatterCallback?`	-	Date time formatter
`hideModerationView`	`bool?`	`null`	Hide moderation view
`hideThreadView`	`bool?`	`null`	Hide thread view
`suggestedMessages`	`List<String>?`	-	AI assistant suggestions
`hideSuggestedMessages`	`bool?`	`false`	Hide suggested messages
`emptyChatGreetingView`	`WidgetBuilder?`	-	Empty chat greeting view
`setAiAssistantTools`	`Map<String, Function(String?)>?`	-	AI assistant tools
`streamingSpeed`	`int?`	-	AI streaming speed
`hideDateSeparator`	`bool?`	`false`	Hide date separator
`mentionAllLabel`	`String?`	-	Group mention label
`mentionAllLabelId`	`String?`	-	Group mention label ID
`hideFlagOption`	`bool?`	`false`	Hide report option
`hideFlagRemarkField`	`bool?`	`false`	Hide flag remark field
`startFromUnreadMessages`	`bool?`	`false`	Start from unread messages
`showMarkAsUnreadOption`	`bool?`	`false`	Show mark as unread option
`newMessageIndicatorView`	`WidgetBuilder?`	-	New message indicator view
`enableConversationSummary`	`bool?`	`false`	Enable conversation summary
`generateConversationSummary`	`bool?`	`false`	Generate conversation summary
`hideReplyOption`	`bool?`	`false`	Hide reply option
`flagReasonLocalizer`	`String Function(String)?`	-	Flag reason localizer
`reactionsRequestBuilder`	`ReactionsRequestBuilder?`	-	Request builder for reactions
`stateCallBack`	`Function(CometChatMessageListController)?`	-	Callback to access controller
`customSoundForMessagePackage`	`String?`	-	Package name for custom sound
`messageId`	`int?`	-	Specific message ID to scroll to

Message Header

Display user or group details in the header

Message Composer

Compose and send messages

Message Template

Customize message bubble templates

Theming

Learn how to customize the look and feel

​Where It Fits

​Minimal Render

​Filtering CometChatMessageList

​Filter Recipes

​Actions and Events

​Callback Props

​SDK Events (Real-Time, Automatic)

​Custom View Slots

​Example: Custom Header View

​Example: Custom Footer View

​Example: Custom Loading State View

​Example: Custom Empty State View

​Example: Custom Error State View

​Styling

​Style Properties

​Example: Custom Styling

​Example: Custom Avatar Style

​Example: Custom Mentions Style

​Advanced

​Message Templates

​Date Separator Pattern

​Date Pattern

​Props Reference

Message Header

Message Composer

Message Template

Theming

Where It Fits

Minimal Render

Filtering CometChatMessageList

Filter Recipes

Actions and Events

Callback Props

SDK Events (Real-Time, Automatic)

Custom View Slots

Example: Custom Header View

Example: Custom Footer View

Example: Custom Loading State View

Example: Custom Empty State View

Example: Custom Error State View

Styling

Style Properties

Example: Custom Styling

Example: Custom Avatar Style

Example: Custom Mentions Style

Advanced

Message Templates

Date Separator Pattern

Date Pattern

Props Reference