Skip to main content
Version: v5

Message List

Overview​

MessageList 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.

MessageList 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.

Image

Usage​

Integration​

You can launch CometChatMessageList directly using Navigator.push, or you can define it as a widget within the build method of your State class.

1. Using Navigator to Launch CometChatMessageList​
Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatMessageList())); // A user or group object is required to launch this widget.
warning

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.

2. Embedding CometChatMessageList as a Widget in the build Method​
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';

class MessageList extends StatefulWidget {
  const MessageList({super.key});

  @override
  State<MessageList> createState() => _MessageListState();
}

class _MessageListState extends State<MessageList> {

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body: SafeArea(
            child: CometChatMessageList() // A user or group object is required to launch this widget.
        )
    );
  }
}

Actions​

Actions dictate how a widget functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the widget to fit your specific needs.

onThreadRepliesClick​

onThreadRepliesClick is triggered when you click on the threaded message bubble. The onThreadRepliesClick action doesn't have a predefined behavior. You can override this action using the following code snippet.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  onThreadRepliesClick: (message, context, {template}) { {
    // TODO("Not yet implemented")
  },
)
onError​

You can customize this behavior by using the provided code snippet to override the onError and improve error handling.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  onError: (e) {
    // TODO("Not yet implemented")
  },
)
onLoad​

Invoked when the list is successfully fetched and loaded, helping track component readiness.

CometChatMessageList(
     onLoad: (list) {
          // print("messages loaded: ${list.length}");
        },
)
onEmpty​

Called when the list is empty, enabling custom handling such as showing a placeholder message.

CometChatMessageList(
      onEmpty: () {
          // print("Groups empty");
        },
)
onReactionLongPress​

Function triggered when a user long presses on a reaction pill, allowing developers to override the default behavior.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget
  onReactionLongPress: (emoji, message) {
    // print("onReactionClick");
  },
)
addMoreReactionTap​

Function triggered when a user clicks on the 'Add More Reactions' button, allowing developers to handle this action.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget
  addMoreReactionTap: (message) {
    // print("addMoreReactionTap");
  },
)
onReactionClick​

The listener to be set for reacting to a message.Pass a non-null instance of onReactionClick to enable it.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget
  onReactionClick: (emoji, message) {
    // print("onReactionClick");
  },
)
onReactionListItemClick​

Function triggered when a reaction list item is clicked, allowing developers to override its behavior in CometChatReactionsList.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget
  onReactionListItemClick: (reaction, message) {
    // print("onReactionListItemClick");
  },
)

Filters​

You can adjust the MessagesRequestBuilder in the MessageList Widget to customize your message list. Numerous options are available to alter the builder to meet your specific needs. For additional details on MessagesRequestBuilder, please visit MessagesRequestBuilder.

In the example below, we are applying a filter to the messages based on a search substring and for a specific user. This means that only messages that contain the search term and are associated with the specified user will be displayed

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  messagesRequestBuilder: MessagesRequestBuilder()
    ..uid = user.uid
    ..searchKeyword = "searchKeyword"
)
info

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

  1. UID
  2. GUID
  3. types
  4. categories

Events​

Events are emitted by a Widget. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed.

The MessageList Widget does not emit any events of its own.

Customization​

To fit your app's design requirements, you can customize the appearance of the conversation widget. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

Style​

Using Style you can customize the look and feel of the widget in your app, These parameters typically control elements such as the color, size, shape, and fonts used within the widget.

1. MessageList Style​

You can set the style to the CometChatMessageList Widget to customize the styling.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  style: CometChatMessageListStyle(
     backgroundColor: Color(0xFFFEEDE1),
     outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(
          backgroundColor: Color(0xFFF76808),
     )
  )
)
Image

Learn more about CometChatMessageListStyle.

2. Avatar Style​

To apply customized styles to the Avatar widget in the CometChatGroups widget, you can use the following code snippet. For further insights on Avatar Styles refer

CometChatMessageList(
                    user: user, // A user or group object is required to launch this widget.
                    style: CometChatMessageListStyle(
                      avatarStyle: CometChatAvatarStyle(
                          border: Border.all(width: 5),
                          borderRadius: 20,
                          backgroundColor: Colors.red
                      ),
                    ),
                  ),

Functionality​

These are a set of small functional customizations that allow you to fine-tune the overall experience of the widget. With these, you can change text, set custom icons, and toggle the visibility of UI elements.

Image
CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  readIcon: Icon(Icons.mark_chat_read, color: Colors.white),
)

CometChatMessageList Properties

Below is a list of customizations along with corresponding code snippets:

PropertyData TypeDescription
userUser?User object for the user message list.
groupGroup?Group object for the group message list.
messagesRequestBuilderMessagesRequestBuilder?Custom request builder passed to CometChat's SDK.
styleCometChatMessageListStyle?Sets style for the message list.
scrollControllerScrollController?Controller for the message list.
emptyStateTextString?Text to display when the list is empty.
errorStateTextString?Text to display when an error occurs.
loadingStateViewWidgetBuilder?View for the loading state.
emptyStateViewWidgetBuilder?View for the empty state.
errorStateViewWidgetBuilder?View for the error state behind the dialog.
stateCallBackFunction(CometChatMessageListController controller)?Access controller functions from the parent.
disableSoundForMessagesbool?Disables sound for sent/received messages.
customSoundForMessagesString?URL for the custom sound for outgoing messages.
customSoundForMessagePackageString?Package name if the sound URL is from another package.
readIconWidget?Custom read icon for message receipt.
deliveredIconWidget?Custom delivered icon for message receipt.
sentIconWidget?Custom sent icon for message receipt.
waitIconWidget?Custom wait icon for message receipt.
alignmentChatAlignmentChat alignment setting.
avatarVisibilitybool?Toggle visibility of avatars.
datePatternString Function(BaseMessage message)?Custom date pattern visible in message receipts.
hideTimestampbool?Toggle visibility of timestamps.
templatesList<CometChatMessageTemplate>?Templates for the message list.
onThreadRepliesClickThreadRepliesClick?Callback for clicking on the thread indicator.
headerViewWidget? Function(BuildContext, {User? user, Group? group, int? parentMessageId})?Custom header view.
footerViewWidget? Function(BuildContext, {User? user, Group? group, int? parentMessageId})?Custom footer view.
dateSeparatorPatternString Function(DateTime)?Pattern for the date separator.
onErrorOnError?Callback triggered when an error occurs.
receiptsVisibilitybool?Controls visibility of read receipts.
dateSeparatorStyleCometChatDateStyle?Style for the date separator.
disableReactionsbool?Toggle visibility of reactions.
addReactionIconWidget?Custom icon for adding a reaction.
addMoreReactionTapFunction(BaseMessage message)?Custom onTap for adding reactions.
favoriteReactionsList<String>?List of frequently used reactions.
textFormattersList<CometChatTextFormatter>?List of text formatters for text messages.
disableMentionsbool?Disables formatting of mentions.
paddingEdgeInsetsGeometry?Sets padding for the message list.
marginEdgeInsetsGeometry?Sets margin for the message list.
widthdouble?Sets the width of the message list.
heightdouble?Sets the height of the message list.
reactionsRequestBuilderReactionsRequestBuilder?Fetches reactions for a specific message.
onLoadOnLoad<BaseMessage>?Callback triggered when the list is loaded.
onEmptyOnEmpty?Callback triggered when the list is empty.
onReactionClickFunction(String? emoji, BaseMessage message)?Custom action for clicking on a reaction pill.
onReactionLongPressFunction(String? emoji, BaseMessage message)?Custom action for long pressing on a reaction pill.
onReactionListItemClickFunction(String? reaction, BaseMessage? message)?Custom action for clicking on a reaction list item.
hideStickyDatebool?Hide the date separator.
hideReplyInThreadOptionbool?Hide the "Reply in Thread" option.
hideTranslateMessageOptionbool?Hide the "Translate Message" option.
hideEditMessageOptionbool?Hide the "Edit Message" option.
hideDeleteMessageOptionbool?Hide the "Delete Message" option.
hideReactionOptionbool?Hide the "Reaction" option.
hideMessagePrivatelyOptionbool?Hide the "Message Privately" option.
hideCopyMessageOptionbool?Hide the "Copy Message" option.
hideMessageInfoOptionbool?Hide the "Message Info" option.
hideGroupActionMessagesbool?Hide group action messages.
enableConversationStartersbool?Enables conversation starters in new conversations.
enableSmartRepliesbool?Enables smart replies in the chat.
hideShareMessageOptionbool?Hide the "Share Message" option.
smartRepliesDelayDurationint?Delay in milliseconds before triggering Smart Replies.
smartRepliesKeywordsList<String>?Keywords that trigger Smart Replies.
addTemplateList<CometChatMessageTemplate>?Add custom message templates to the existing templates.

Advance​

For advanced-level customization, you can set custom views to the widget. This lets you tailor each aspect of the widget to fit your exact needs and application aesthetics. You can create and define your own widget and then incorporate those into the widget.

Template​

CometChatMessageTemplate is a pre-defined structure for creating message views that can be used as a starting point or blueprint for creating message views often known as message bubbles. For more information, you can refer to CometChatMessageTemplate.

You can set message Templates to MessageList by using the following code snippet

CometChatMessageList(
                      user: user, // A user or group object is required to launch this widget.
                      templates: [], // Replace this placeholder with your custom widget.
                  ),

Example

Here is the complete example for reference:

getTemplate()
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,
          fontFamily: "PlaywritePL"
        ),
      ),
    );
  };

  // Creating an audio template
  CometChatMessageTemplate audioTemplate = ChatConfigurator.getDataSource().getAudioMessageTemplate();

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

  // custom list of templates
  List<CometChatMessageTemplate> messageTypes = [
    textTemplate,
    audioTemplate,
    customMessageTemplate
  ];

  return messageTypes;
}
CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  templates: getTemplate(),
)
Image

DateSeparatorPattern​

You can modify the date pattern of the message list date separator to your requirement using setDateSeparatorPattern(). This method accepts a function with a return type String. Inside the function, you can create your own pattern and return it as a String.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  dateSeparatorPattern: (DateTime dateTime) {
    return ""; //Replace this empty string with your custom date time pattern.
  },
)

Example

Here is the complete example for reference:

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  dateSeparatorPattern: (DateTime dateTime) {
    return DateFormat("dd/MM/yyyy").format(dateTime);
  },
)
Image

SetDatePattern​

You can modify the date pattern to your requirement using .setDatePattern. This method accepts a function with a return type String. Inside the function, you can create your own pattern and return it as a String.

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  datePattern: (message) {
    return DateFormat('YOUR_PATTERN').format(message.sentAt!);
  },
)

Example

Here is the complete example for reference:

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  datePattern: (message) {
    return DateFormat('EEE, M/d/y').format(message.sentAt!);
  },
)
Image

loadingStateView​

Customizes the loading indicator when messages are being fetched.

Use Cases:

  • Show a spinner or skeleton loader for smooth UX.
  • Display a "Fetching messages..." text.
CometChatMessageList(
    loadingStateView: (context) {
       // return leading view
    },
)

emptyStateView​

Defines a custom view to be displayed when no messages are available.

Use Cases:

  • Show a friendly message like "No messages yet. Start the conversation!".
CometChatMessageList(
    emptyStateView: (context) {
       // return empty view
    },
)

errorStateView​

Custom error state view displayed when fetching messages fails.

Use Cases:

  • Show a retry button when an error occurs.
  • Display a friendly message like "Couldn't load messages. Check your connection.".
CometChatMessageList(
    errorStateView: (context) {
       // return error view
    },
)

TextFormatters​

Assigns the list of text formatters. If the provided list is not null, it sets the list. Otherwise, it assigns the default text formatters retrieved from the data source. To configure the existing Mentions look and feel check out MentionsFormatter Guide

Here is the complete example for reference:

CometChatMessageList(
  user: user, // A user or group object is required to launch this widget.
  textFormatters: [
       CometChatMentionsFormatter(
              style: CometChatMentionsStyle(
                     mentionSelfTextBackgroundColor: Color(0xFFF76808),
                     mentionTextBackgroundColor: Colors.white,
                     mentionTextColor: Colors.black,
                     mentionSelfTextColor: Colors.white,
                    )
          )
    ],
)
Image

HeaderView​

Allows developers to set a custom widget as the header of the message list. It provides context and access to user, group, and parentMessageId, enabling tailored designs for different use cases, such as displaying user details or group information.

CometChatMessageList(
    user: user, // A user or group object is required to launch this widget.
    headerView: (context, {group, parentMessageId, user}) => 
      MessageListHeader(
        backgroundColor: const Color(0XFFEDEAFA),
        color: const Color(0XFF6852D6),
      ),
)
Image

FooterView​

Enables developers to add a custom widget to the footer of the message list. Like headerView, it supports user, group, and parentMessageId for context, offering flexibility to add components like timestamps, typing indicators, or action buttons.

CometChatMessageList(
    user: user, // A user or group object is required to launch this widget.
    footerView: (context, {group, parentMessageId, user}) => 
      MessageListFooter(
        backgroundColor: const Color(0XFFEDEAFA),
        color: const Color(0XFF6852D6),
      ),
)
Image