Conversations - CometChat Docs

AI Agent Component Spec

{
  "component": "CometChatConversations",
  "package": "cometchat_chat_uikit",
  "import": "import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';",
  "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user.",
  "primaryOutput": {
    "prop": "onItemTap",
    "type": "Function(Conversation conversation)"
  },
  "props": {
    "data": {
      "conversationsRequestBuilder": {
        "type": "ConversationsRequestBuilder?",
        "default": "SDK default (30 per page)",
        "note": "Pass the builder, not the result of .build()"
      },
      "conversationsProtocol": {
        "type": "ConversationsBuilderProtocol?",
        "default": "null",
        "note": "Custom protocol for fetching conversations"
      },
      "scrollController": {
        "type": "ScrollController?",
        "default": "null",
        "note": "Custom scroll controller for the list"
      },
      "title": {
        "type": "String?",
        "default": "Chats",
        "note": "Title text for the app bar"
      },
      "controllerTag": {
        "type": "String?",
        "default": "null",
        "note": "Tag for controller management"
      },
      "mentionAllLabel": {
        "type": "String?",
        "default": "null",
        "note": "Custom label for @all mentions"
      },
      "mentionAllLabelId": {
        "type": "String?",
        "default": "null",
        "note": "Custom label ID for @all mentions"
      }
    },
    "callbacks": {
      "onItemTap": "Function(Conversation conversation)?",
      "onItemLongPress": "Function(Conversation conversation)?",
      "onSelection": "Function(List<Conversation>? list)?",
      "onBack": "VoidCallback?",
      "onError": "OnError?",
      "onLoad": "OnLoad<Conversation>?",
      "onEmpty": "OnEmpty?",
      "onSearchTap": "GestureTapCallback?",
      "datePattern": "String Function(Conversation conversation)?",
      "dateTimeFormatterCallback": "DateTimeFormatterCallback?"
    },
    "visibility": {
      "receiptsVisibility": { "type": "bool?", "default": true },
      "usersStatusVisibility": { "type": "bool?", "default": true },
      "groupTypeVisibility": { "type": "bool?", "default": true },
      "deleteConversationOptionVisibility": { "type": "bool?", "default": true },
      "hideAppbar": { "type": "bool?", "default": false },
      "hideError": { "type": "bool?", "default": false },
      "hideSearch": { "type": "bool?", "default": false },
      "showBackButton": { "type": "bool", "default": false },
      "dateBackgroundIsTransparent": { "type": "bool?", "default": null },
      "searchReadOnly": { "type": "bool", "default": false }
    },
    "sound": {
      "disableSoundForMessages": { "type": "bool?", "default": false },
      "customSoundForMessages": { "type": "String?", "default": "built-in" }
    },
    "selection": {
      "selectionMode": {
        "type": "SelectionMode?",
        "values": ["SelectionMode.single", "SelectionMode.multiple", "SelectionMode.none"],
        "default": "null"
      },
      "activateSelection": {
        "type": "ActivateSelection?",
        "values": ["ActivateSelection.onClick", "ActivateSelection.onLongClick"],
        "default": "null"
      }
    },
    "viewSlots": {
      "listItemView": "Widget Function(Conversation conversation)?",
      "leadingView": "Widget? Function(BuildContext context, Conversation conversation)?",
      "titleView": "Widget? Function(BuildContext context, Conversation conversation)?",
      "subtitleView": "Widget? Function(BuildContext context, Conversation conversation)?",
      "trailingView": "Widget? Function(Conversation conversation)?",
      "loadingStateView": "WidgetBuilder?",
      "emptyStateView": "WidgetBuilder?",
      "errorStateView": "WidgetBuilder?",
      "setOptions": "List<CometChatOption>? Function(Conversation, CometChatConversationsController, BuildContext)?",
      "addOptions": "List<CometChatOption>? Function(Conversation, CometChatConversationsController, BuildContext)?"
    },
    "formatting": {
      "textFormatters": {
        "type": "List<CometChatTextFormatter>?",
        "default": "default formatters from data source"
      },
      "typingIndicatorText": {
        "type": "String?",
        "default": "typing..."
      }
    },
    "icons": {
      "backButton": { "type": "Widget?", "default": "built-in back arrow" },
      "protectedGroupIcon": { "type": "Widget?", "default": "built-in lock icon" },
      "privateGroupIcon": { "type": "Widget?", "default": "built-in lock icon" },
      "readIcon": { "type": "Widget?", "default": "built-in read icon" },
      "deliveredIcon": { "type": "Widget?", "default": "built-in delivered icon" },
      "sentIcon": { "type": "Widget?", "default": "built-in sent icon" },
      "submitIcon": { "type": "Widget?", "default": "built-in check icon" },
      "searchBoxIcon": { "type": "Widget?", "default": "built-in search icon" }
    },
    "layout": {
      "datePadding": { "type": "EdgeInsets?", "default": "null" },
      "dateHeight": { "type": "double?", "default": "null" },
      "dateWidth": { "type": "double?", "default": "null" },
      "badgeWidth": { "type": "double?", "default": "null" },
      "badgeHeight": { "type": "double?", "default": "null" },
      "badgePadding": { "type": "EdgeInsetsGeometry?", "default": "null" },
      "avatarWidth": { "type": "double?", "default": "null" },
      "avatarHeight": { "type": "double?", "default": "null" },
      "avatarPadding": { "type": "EdgeInsetsGeometry?", "default": "null" },
      "avatarMargin": { "type": "EdgeInsetsGeometry?", "default": "null" },
      "statusIndicatorWidth": { "type": "double?", "default": "null" },
      "statusIndicatorHeight": { "type": "double?", "default": "null" },
      "statusIndicatorBorderRadius": { "type": "BorderRadiusGeometry?", "default": "null" },
      "searchPadding": { "type": "EdgeInsetsGeometry?", "default": "null" },
      "searchContentPadding": { "type": "EdgeInsetsGeometry?", "default": "null" }
    },
    "style": {
      "conversationsStyle": { "type": "CometChatConversationsStyle", "default": "CometChatConversationsStyle()" },
      "listItemStyle": { "type": "ListItemStyle?", "default": "null" },
      "appBarOptions": { "type": "List<Widget>?", "default": "null" }
    }
  },
  "events": [
    {
      "name": "CometChatConversationEvents.ccConversationDeleted",
      "payload": "Conversation",
      "description": "Conversation deleted from list"
    },
    {
      "name": "CometChatConversationEvents.ccUpdateConversation",
      "payload": "Conversation",
      "description": "Conversation updated"
    },
    {
      "name": "CometChatConversationEvents.ccMessageRead",
      "payload": "BaseMessage",
      "description": "Message marked as read"
    },
    {
      "name": "CometChatConversationEvents.ccMessageSent",
      "payload": "BaseMessage, MessageStatus",
      "description": "Message sent"
    }
  ],
  "sdkListeners": [
    "onTextMessageReceived",
    "onMediaMessageReceived",
    "onCustomMessageReceived",
    "onFormMessageReceived",
    "onCardMessageReceived",
    "onCustomInteractiveMessageReceived",
    "onSchedulerMessageReceived",
    "onTypingStarted",
    "onTypingEnded",
    "onMessagesDelivered",
    "onMessagesRead",
    "onMessagesDeliveredToAll",
    "onMessagesReadByAll",
    "onMessageEdited",
    "onMessageDeleted",
    "onUserOnline",
    "onUserOffline",
    "ccUserBlocked",
    "onGroupMemberJoined",
    "onGroupMemberLeft",
    "onGroupMemberKicked",
    "onGroupMemberBanned",
    "onGroupMemberUnbanned",
    "onGroupMemberScopeChanged",
    "onMemberAddedToGroup",
    "ccOwnershipChanged",
    "ccGroupLeft",
    "ccGroupDeleted",
    "ccGroupMemberAdded",
    "onIncomingCallReceived",
    "onOutgoingCallAccepted",
    "onOutgoingCallRejected",
    "onIncomingCallCancelled",
    "onCallEndedMessageReceived",
    "onConnected"
  ],
  "compositionExample": {
    "description": "Sidebar conversations wired to message view",
    "components": [
      "CometChatConversations",
      "CometChatMessages",
      "CometChatMessageHeader",
      "CometChatMessageList",
      "CometChatMessageComposer"
    ],
    "flow": "onItemTap emits Conversation -> extract User/Group via conversationWith -> pass to CometChatMessages or individual MessageHeader, MessageList, MessageComposer"
  },
  "types": {
    "CometChatOption": {
      "id": "String?",
      "title": "String?",
      "icon": "String?",
      "iconWidget": "Widget?",
      "onClick": "VoidCallback?"
    },
    "SelectionMode": {
      "single": "SelectionMode.single",
      "multiple": "SelectionMode.multiple",
      "none": "SelectionMode.none"
    },
    "ActivateSelection": {
      "onClick": "ActivateSelection.onClick",
      "onLongClick": "ActivateSelection.onLongClick"
    }
  }
}

Where It Fits

CometChatConversations is a sidebar list widget. It renders recent conversations and emits the selected Conversation via onItemTap. Wire it to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer to build a standard two-panel chat layout.

Dart

import 'package:flutter/material.dart';
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

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

  @override
  State<ChatApp> createState() => _ChatAppState();
}

class _ChatAppState extends State<ChatApp> {
  User? selectedUser;
  Group? selectedGroup;

  void handleItemTap(Conversation conversation) {
    final entity = conversation.conversationWith;
    setState(() {
      if (entity is User) {
        selectedUser = entity;
        selectedGroup = null;
      } else if (entity is Group) {
        selectedGroup = entity;
        selectedUser = null;
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Row(
        children: [
          SizedBox(
            width: 400,
            child: CometChatConversations(
              onItemTap: handleItemTap,
            ),
          ),
          Expanded(
            child: selectedUser != null || selectedGroup != null
                ? CometChatMessages(
                    user: selectedUser,
                    group: selectedGroup,
                  )
                : const Center(
                    child: Text('Select a conversation'),
                  ),
          ),
        ],
      ),
    );
  }
}

Minimal Render

Dart

import 'package:flutter/material.dart';
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

class ConversationsDemo extends StatelessWidget {
  const ConversationsDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: SafeArea(
        child: CometChatConversations(),
      ),
    );
  }
}

You can also launch it using Navigator.push:

Navigator.push(
  context, 
  MaterialPageRoute(builder: (context) => const CometChatConversations())
);

Filtering Conversations

Pass a ConversationsRequestBuilder to conversationsRequestBuilder. Pass the builder instance — not the result of .build().

Dart

CometChatConversations(
  conversationsRequestBuilder: ConversationsRequestBuilder()
    ..conversationType = "user"
    ..limit = 10,
)

Filter Recipes

Recipe	Code
Only user conversations	`ConversationsRequestBuilder()..conversationType = "user"`
Only group conversations	`ConversationsRequestBuilder()..conversationType = "group"`
Limit to 10 per page	`ConversationsRequestBuilder()..limit = 10`
With specific tags	`ConversationsRequestBuilder()..tags = ["vip"]`
With user and group tags	`ConversationsRequestBuilder()..withUserAndGroupTags = true`
Include blocked users	`ConversationsRequestBuilder()..includeBlockedUsers = true`
Search conversations	`ConversationsRequestBuilder()..searchKeyword = "hello"`
Unread only	`ConversationsRequestBuilder()..unread = true`

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

ConversationsRequestBuilder Properties

Property	Description	Code
`limit`	Number of conversations to fetch per request. Maximum 50.	`..limit = 30`
`conversationType`	Filter by conversation type: `"user"` or `"group"`. If not set, returns both.	`..conversationType = "user"`
`withTags`	Include tags associated with conversations. Default `false`.	`..withTags = true`
`tags`	Filter conversations by specific tags.	`..tags = ["archived", "vip"]`
`withUserAndGroupTags`	Include user/group tags in the Conversation object. Default `false`.	`..withUserAndGroupTags = true`
`includeBlockedUsers`	Include conversations with blocked users. Default `false`.	`..includeBlockedUsers = true`
`withBlockedInfo`	Include blocked info in the ConversationWith object. Default `false`.	`..withBlockedInfo = true`
`searchKeyword`	Search conversations by user or group name. Requires Advanced plan.	`..searchKeyword = "John"`
`unread`	Fetch only unread conversations. Requires Advanced plan.	`..unread = true`
`build()`	Builds and returns a `ConversationsRequest` object.	`.build()`

Refer to ConversationsRequestBuilder for the full builder API.

Actions and Events

Callback Props

onItemTap

Fires when a conversation row is tapped. Primary navigation hook — set the active conversation and render the message view.

Dart

CometChatConversations(
  onItemTap: (conversation) {
    print("Selected: ${conversation.conversationId}");
  },
)

onItemLongPress

Fires when a conversation row is long-pressed. Useful for showing context menus or custom actions.

Dart

CometChatConversations(
  onItemLongPress: (conversation) {
    // Show custom context menu
  },
)

onSelection

Fires when conversations are selected in multi-select mode. Requires selectionMode to be set.

Dart

CometChatConversations(
  selectionMode: SelectionMode.multiple,
  onSelection: (selectedList) {
    print("Selected ${selectedList?.length ?? 0} conversations");
  },
)

onError

Fires on internal errors (network failure, auth issue, SDK exception).

Dart

CometChatConversations(
  onError: (error) {
    print("CometChatConversations error: $error");
  },
)

onBack

Fires when the back button is pressed.

Dart

CometChatConversations(
  showBackButton: true,
  onBack: () {
    Navigator.pop(context);
  },
)

onLoad

Fires when the conversation list is successfully loaded.

Dart

CometChatConversations(
  onLoad: (list) {
    print("Loaded ${list.length} conversations");
  },
)

onEmpty

Fires when the conversation list is empty.

Dart

CometChatConversations(
  onEmpty: () {
    print("No conversations found");
  },
)

Global UI Events

CometChatConversationEvents emits events subscribable from anywhere in the application. Add a listener in initState and remove it in dispose.

Event	Fires when	Payload
`ccConversationDeleted`	A conversation is deleted from the list	`Conversation`

When to use: sync external UI with conversation state changes. For example, update an unread count badge in a tab bar when a conversation is deleted.

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

class _YourScreenState extends State<YourScreen> with CometChatConversationEventListener {

  @override
  void initState() {
    super.initState();
    CometChatConversationEvents.addConversationListListener("listenerId", this);
  }

  @override
  void dispose() {
    CometChatConversationEvents.removeConversationListListener("listenerId");
    super.dispose();
  }

  @override
  void ccConversationDeleted(Conversation conversation) {
    print("Deleted: ${conversation.conversationId}");
  }
}

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

SDK Listener	Internal behavior
`onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`	Moves conversation to top, updates last message preview and unread count
`onTypingStarted` / `onTypingEnded`	Shows/hides typing indicator in the subtitle
`onMessagesDelivered` / `onMessagesRead`	Updates receipt ticks (unless `receiptsVisibility: false`)
`onUserOnline` / `onUserOffline`	Updates online/offline status dot (unless `usersStatusVisibility: false`)
`onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` / `onMemberAddedToGroup`	Updates group conversation metadata

Automatic: new messages, typing indicators, receipts, user presence, group membership changes.

Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a conversation parameter receive the Conversation object for that row.

Slot	Signature	Replaces
`listItemView`	`Widget Function(Conversation)`	Entire list item row
`leadingView`	`Widget? Function(BuildContext, Conversation)`	Avatar / left section
`titleView`	`Widget? Function(BuildContext, Conversation)`	Name / title text
`subtitleView`	`Widget? Function(BuildContext, Conversation)`	Last message preview
`trailingView`	`Widget? Function(Conversation)`	Timestamp / badge / right section
`loadingStateView`	`WidgetBuilder`	Loading spinner
`emptyStateView`	`WidgetBuilder`	Empty state
`errorStateView`	`WidgetBuilder`	Error state
`setOptions`	`List<CometChatOption>? Function(Conversation, Controller, BuildContext)`	Context menu actions (replaces default)
`addOptions`	`List<CometChatOption>? Function(Conversation, Controller, BuildContext)`	Context menu actions (adds to default)

listItemView

Replace the entire list item row.

Dart

CometChatConversations(
  listItemView: (conversation) {
    final entity = conversation.conversationWith;
    final name = entity is User ? entity.name : (entity as Group).name;
    
    return CometChatListItem(
      avatarName: name,
      avatarURL: entity is User ? entity.avatar : (entity as Group).icon,
      title: name,
      avatarStyle: CometChatAvatarStyle(
        borderRadius: BorderRadius.circular(8),
      ),
    );
  },
)

For a more complete custom list item with status indicator and date:

Dart

Widget getCustomListItem(Conversation conversation, BuildContext context) {
  User? conversationWithUser;
  Group? conversationWithGroup;
  
  if (conversation.conversationWith is User) {
    conversationWithUser = conversation.conversationWith as User;
  } else {
    conversationWithGroup = conversation.conversationWith as Group;
  }

  // Get status indicator
  StatusIndicatorUtils statusIndicatorUtils = StatusIndicatorUtils.getStatusIndicatorFromParams(
    context: context,
    user: conversationWithUser,
    group: conversationWithGroup,
    onlineStatusIndicatorColor: Color(0xFF09C26F),
  );

  // Build tail view with date
  final lastMessageTime = conversation.lastMessage?.sentAt ?? DateTime.now();
  Widget tail = CometChatDate(
    date: lastMessageTime,
    padding: EdgeInsets.zero,
    style: CometChatDateStyle(
      backgroundColor: Colors.transparent,
      textStyle: TextStyle(color: Color(0xFF727272), fontSize: 12),
      border: Border.all(width: 0, color: Colors.transparent),
    ),
    pattern: DateTimePattern.dayDateTimeFormat,
  );

  return CometChatListItem(
    avatarHeight: 48,
    avatarWidth: 48,
    id: conversation.conversationId,
    avatarName: conversationWithUser?.name ?? conversationWithGroup?.name,
    avatarURL: conversationWithUser?.avatar ?? conversationWithGroup?.icon,
    avatarStyle: CometChatAvatarStyle(
      borderRadius: BorderRadius.circular(8),
      backgroundColor: Color(0xFFAA9EE8),
    ),
    title: conversationWithUser?.name ?? conversationWithGroup?.name,
    tailView: tail,
    statusIndicatorColor: statusIndicatorUtils.statusIndicatorColor,
    statusIndicatorIcon: statusIndicatorUtils.icon,
    statusIndicatorStyle: CometChatStatusIndicatorStyle(
      border: Border.all(width: 2, color: Colors.white),
    ),
    hideSeparator: true,
    style: ListItemStyle(
      background: Colors.transparent,
      titleStyle: TextStyle(
        overflow: TextOverflow.ellipsis,
        fontSize: 16,
        fontWeight: FontWeight.w500,
        color: Color(0xFF141414),
      ),
      padding: EdgeInsets.symmetric(horizontal: 16, vertical: 12),
    ),
  );
}

// Usage:
CometChatConversations(
  listItemView: (conversation) => getCustomListItem(conversation, context),
)

leadingView

Replace the avatar / left section. Typing-aware avatar example.

Dart

// In your StatefulWidget, use the MessageListener mixin:
class _ConversationsScreenState extends State<ConversationsScreen> with MessageListener {
  Map<String, TypingIndicator> typingMap = {};

  @override
  void initState() {
    super.initState();
    CometChat.addMessageListener("typing_listener", this);
  }

  @override
  void dispose() {
    CometChat.removeMessageListener("typing_listener");
    super.dispose();
  }

  @override
  void onTypingStarted(TypingIndicator typingIndicator) {
    setTypingIndicator(typingIndicator, true);
  }

  @override
  void onTypingEnded(TypingIndicator typingIndicator) {
    setTypingIndicator(typingIndicator, false);
  }

  void setTypingIndicator(TypingIndicator typingIndicator, bool isTypingStarted) {
    final id = typingIndicator.receiverType == ReceiverTypeConstants.user
        ? typingIndicator.sender.uid
        : typingIndicator.receiverId;
    
    setState(() {
      if (isTypingStarted) {
        typingMap[id] = typingIndicator;
      } else {
        typingMap.remove(id);
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return CometChatConversations(
      leadingView: (context, conversation) {
        final entity = conversation.conversationWith;
        final id = entity is User ? entity.uid : (entity as Group).guid;
        
        if (typingMap.containsKey(id)) {
          return Container(
            decoration: BoxDecoration(
              border: Border.all(color: Color(0xFFF76808), width: 2),
              borderRadius: BorderRadius.circular(8),
            ),
            child: Image.asset("assets/typing_icon.png", height: 40, width: 40),
          );
        }
        return null; // Use default avatar
      },
    );
  }
}

titleView

Replace the name / title text. Inline user status example.

Dart

CometChatConversations(
  titleView: (context, conversation) {
    final entity = conversation.conversationWith;
    final name = entity is User ? entity.name : (entity as Group).name;
    final statusMessage = entity is User ? entity.statusMessage : null;
    
    return Row(
      children: [
        Text(name ?? "", style: TextStyle(fontWeight: FontWeight.w500)),
        if (statusMessage != null)
          Text(" · $statusMessage", style: TextStyle(color: Color(0xFF6852D6))),
      ],
    );
  },
)

subtitleView

Replace the last message preview text.

Dart

CometChatConversations(
  subtitleView: (context, conversation) {
    final entity = conversation.conversationWith;
    String subtitle;
    
    if (entity is User) {
      final dateTime = entity.lastActiveAt ?? DateTime.now();
      subtitle = "Last Active: ${DateFormat('dd/MM/yyyy, HH:mm').format(dateTime)}";
    } else {
      final dateTime = (entity as Group).createdAt ?? DateTime.now();
      subtitle = "Created: ${DateFormat('dd/MM/yyyy, HH:mm').format(dateTime)}";
    }
    
    return Text(subtitle, style: TextStyle(color: Color(0xFF727272), fontSize: 14));
  },
)

trailingView

Replace the timestamp / badge / right section. Relative time badge example.

Dart

CometChatConversations(
  trailingView: (conversation) {
    final timestamp = conversation.updatedAt?.millisecondsSinceEpoch ?? 0;
    final now = DateTime.now();
    final lastSeen = DateTime.fromMillisecondsSinceEpoch(timestamp * 1000);
    final diffInMinutes = now.difference(lastSeen).inMinutes;
    final diffInHours = now.difference(lastSeen).inHours;

    String timeText;
    String label;
    Color cardColor;

    if (diffInMinutes < 60) {
      timeText = "$diffInMinutes";
      label = "Min ago";
      cardColor = Color(0x666852D6);
    } else if (diffInHours < 10) {
      timeText = "$diffInHours";
      label = "Hr ago";
      cardColor = Color(0x66FFAB00);
    } else {
      timeText = "$diffInHours";
      label = "Hr ago";
      cardColor = Color(0x66F44649);
    }

    return Card(
      color: cardColor,
      child: Padding(
        padding: EdgeInsets.all(4),
        child: Column(
          children: [
            Text(timeText, style: TextStyle(fontWeight: FontWeight.bold)),
            Text(label, style: TextStyle(fontSize: 12)),
          ],
        ),
      ),
    );
  },
)

setOptions

Replace the context menu / long-press actions on each conversation item.

Dart

CometChatConversations(
  setOptions: (conversation, controller, context) {
    return [
      CometChatOption(
        id: "delete",
        title: "Delete",
        icon: AssetConstants.delete,
        onClick: () {
          // Delete conversation
        },
      ),
    ];
  },
)

addOptions

Add to the existing context menu actions without removing defaults.

Dart

CometChatConversations(
  addOptions: (conversation, controller, context) {
    return [
      CometChatOption(
        id: "archive",
        title: "Archive",
        iconWidget: Icon(Icons.archive_outlined),
        onClick: () {
          // Archive conversation
        },
      ),
      CometChatOption(
        id: "pin",
        title: "Pin",
        iconWidget: Icon(Icons.push_pin_outlined),
        onClick: () {
          // Pin conversation
        },
      ),
      CometChatOption(
        id: "mark_unread",
        title: "Mark as unread",
        iconWidget: Icon(Icons.mark_chat_unread_outlined),
        onClick: () {
          // Mark conversation as unread
        },
      ),
    ];
  },
)

appBarOptions

Add custom widgets to the app bar.

Dart

CometChatConversations(
  showBackButton: false,
  appBarOptions: [
    PopupMenuButton(
      icon: CometChatAvatar(
        image: CometChatUIKit.loggedInUser?.avatar,
        name: CometChatUIKit.loggedInUser?.name,
      ),
      itemBuilder: (context) => [
        PopupMenuItem(value: 'create', child: Text("Create Conversation")),
        PopupMenuItem(value: 'logout', child: Text("Logout")),
      ],
      onSelected: (value) {
        // Handle menu selection
      },
    ),
  ],
)

For a more complete popup menu with styling:

Dart

CometChatConversations(
  showBackButton: false,
  appBarOptions: [
    PopupMenuButton(
      shape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(8),
        side: BorderSide(color: Color(0xFFF5F5F5), width: 1),
      ),
      color: Colors.white,
      elevation: 4,
      menuPadding: EdgeInsets.zero,
      padding: EdgeInsets.zero,
      icon: Padding(
        padding: EdgeInsets.only(left: 12, right: 16),
        child: CometChatAvatar(
          width: 40,
          height: 40,
          image: CometChatUIKit.loggedInUser?.avatar,
          name: CometChatUIKit.loggedInUser?.name,
        ),
      ),
      onSelected: (value) {
        switch (value) {
          case '/create':
            // Navigate to create conversation
            break;
          case '/logout':
            CometChatUIKit.logout();
            break;
        }
      },
      position: PopupMenuPosition.under,
      itemBuilder: (BuildContext context) {
        return [
          PopupMenuItem(
            height: 44,
            padding: EdgeInsets.all(16),
            value: '/create',
            child: Row(
              children: [
                Padding(
                  padding: EdgeInsets.only(right: 8),
                  child: Icon(Icons.add_comment_outlined, color: Color(0xFFA1A1A1), size: 24),
                ),
                Text("Create Conversation", style: TextStyle(fontSize: 14, color: Color(0xFF141414))),
              ],
            ),
          ),
          PopupMenuItem(
            height: 44,
            padding: EdgeInsets.all(16),
            value: '/name',
            child: Row(
              children: [
                Padding(
                  padding: EdgeInsets.only(right: 8),
                  child: Icon(Icons.account_circle_outlined, color: Color(0xFFA1A1A1), size: 24),
                ),
                Text(CometChatUIKit.loggedInUser?.name ?? "", style: TextStyle(fontSize: 14, color: Color(0xFF141414))),
              ],
            ),
          ),
          PopupMenuItem(
            height: 44,
            padding: EdgeInsets.all(16),
            value: '/logout',
            child: Row(
              children: [
                Padding(
                  padding: EdgeInsets.only(right: 8),
                  child: Icon(Icons.logout, color: Colors.red, size: 24),
                ),
                Text("Logout", style: TextStyle(fontSize: 14, color: Colors.red)),
              ],
            ),
          ),
        ];
      },
    ),
  ],
  onItemTap: (conversation) {
    User? user;
    Group? group;
    if (conversation.conversationWith is User) {
      user = conversation.conversationWith as User;
    } else {
      group = conversation.conversationWith as Group;
    }
    // Navigate to messages
  },
)

Styling

Set CometChatConversationsStyle to customize the appearance.

Dart

CometChatConversations(
  conversationsStyle: CometChatConversationsStyle(
    backgroundColor: Colors.white,
    titleTextColor: Color(0xFF141414),
    avatarStyle: CometChatAvatarStyle(
      borderRadius: BorderRadius.circular(8),
      backgroundColor: Color(0xFFFBAA75),
    ),
    badgeStyle: CometChatBadgeStyle(
      backgroundColor: Color(0xFFF76808),
    ),
  ),
)

Style Properties

Property	Type	Description
`backgroundColor`	`Color`	Background color of the component
`border`	`Border`	Border for the widget
`borderRadius`	`BorderRadiusGeometry`	Border radius for the widget
`titleTextColor`	`Color`	Color of the header title
`titleTextStyle`	`TextStyle`	Style for the header title
`backIconColor`	`Color`	Back button icon color
`searchBackgroundColor`	`Color`	Background color of search box
`searchBorder`	`BorderSide`	Border for search box
`searchBorderRadius`	`BorderRadius`	Border radius for search box
`searchPlaceHolderTextColor`	`Color`	Placeholder text color in search
`searchPlaceHolderTextStyle`	`TextStyle`	Placeholder text style in search
`searchIconColor`	`Color`	Search icon color
`separatorColor`	`Color`	Color of list item separators
`separatorHeight`	`double`	Height of list item separators
`emptyStateTextColor`	`Color`	Text color for empty state title
`emptyStateTextStyle`	`TextStyle`	Text style for empty state title
`emptyStateSubTitleTextColor`	`Color`	Text color for empty state subtitle
`emptyStateSubTitleTextStyle`	`TextStyle`	Text style for empty state subtitle
`errorStateTextColor`	`Color`	Text color for error state title
`errorStateTextStyle`	`TextStyle`	Text style for error state title
`errorStateSubTitleTextColor`	`Color`	Text color for error state subtitle
`errorStateSubTitleTextStyle`	`TextStyle`	Text style for error state subtitle
`itemTitleTextColor`	`Color`	Text color for conversation item title
`itemTitleTextStyle`	`TextStyle`	Text style for conversation item title
`itemSubtitleTextColor`	`Color`	Text color for conversation item subtitle
`itemSubtitleTextStyle`	`TextStyle`	Text style for conversation item subtitle
`messageTypeIconColor`	`Color`	Icon color for message type indicators
`avatarStyle`	`CometChatAvatarStyle`	Style for avatars
`badgeStyle`	`CometChatBadgeStyle`	Style for unread badges
`receiptStyle`	`CometChatMessageReceiptStyle`	Style for message receipts
`statusIndicatorStyle`	`CometChatStatusIndicatorStyle`	Style for online status indicator
`dateStyle`	`CometChatDateStyle`	Style for date/time display
`typingIndicatorStyle`	`CometChatTypingIndicatorStyle`	Style for typing indicator
`mentionsStyle`	`CometChatMentionsStyle`	Style for @mentions
`deleteConversationDialogStyle`	`CometChatConfirmDialogStyle`	Style for delete confirmation dialog
`privateGroupIconBackground`	`Color`	Background color for private group icon
`protectedGroupIconBackground`	`Color`	Background color for protected group icon
`submitIconColor`	`Color`	Color for submit icon in selection mode
`checkBoxBackgroundColor`	`Color`	Background color for selection checkbox
`checkBoxCheckedBackgroundColor`	`Color`	Background color when checkbox is checked
`checkBoxBorder`	`BorderSide`	Border for selection checkbox
`checkBoxBorderRadius`	`BorderRadiusGeometry`	Border radius for selection checkbox
`checkboxSelectedIconColor`	`Color`	Icon color when checkbox is selected
`listItemSelectedBackgroundColor`	`Color`	Background color for selected list items

Common Patterns

Custom empty state with CTA

Dart

CometChatConversations(
  emptyStateView: (context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Text("No conversations yet"),
          SizedBox(height: 16),
          ElevatedButton(
            onPressed: () {
              // Navigate to contacts
            },
            child: Text("Start a conversation"),
          ),
        ],
      ),
    );
  },
)

Hide all chrome — minimal list

Dart

CometChatConversations(
  receiptsVisibility: false,
  usersStatusVisibility: false,
  groupTypeVisibility: false,
  deleteConversationOptionVisibility: false,
  hideAppbar: true,
)

Conversations with search

Dart

CometChatConversations(
  hideSearch: false,
  onSearchTap: () {
    // Handle search tap - navigate to search screen
  },
)

Custom date pattern

Dart

CometChatConversations(
  datePattern: (conversation) {
    final date = conversation.lastMessage?.sentAt ?? DateTime.now();
    return DateFormat('d MMM, hh:mm a').format(date);
  },
)

Text formatters

Configure text formatters for the conversation subtitle. See CometChatMentionsFormatter for mention formatting.

Dart

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

Accessibility

The component renders a scrollable list of interactive items. Each conversation row is tappable and responds to both tap and long-press gestures. The context menu (options) is accessible via long-press. The unread badge count is exposed as text content. Avatar images include the conversation name for accessibility. For screen readers, the conversation list is rendered as a semantic list using Flutter’s built-in accessibility features. Status indicators (online/offline, group type icons) use visual icons — consider providing custom Semantics widgets via leadingView if screen reader descriptions are needed for these visual indicators. When using selection mode, checkboxes are rendered with proper accessibility labels. The component respects system accessibility settings including text scaling and high contrast modes.

Props

All props are optional. Sorted alphabetically.

activateSelection

Controls when selection mode activates.


Type	`ActivateSelection`
Default	`null`

Values: ActivateSelection.onClick, ActivateSelection.onLongClick

addOptions

Adds to the current list of actions available on long press.


Type	`List<CometChatOption>? Function(Conversation, CometChatConversationsController, BuildContext)`
Default	`null`

appBarOptions

List of widgets to display in the app bar.


Type	`List<Widget>`
Default	`null`

backButton

Custom back button widget.


Type	`Widget`
Default	Built-in back arrow

conversationsRequestBuilder

Controls which conversations load and in what order.


Type	`ConversationsRequestBuilder`
Default	SDK default (30 per page)

Pass the builder instance, not the result of .build().

conversationsProtocol

Custom protocol for fetching conversations.


Type	`ConversationsBuilderProtocol`
Default	`null`

Use this for advanced customization of how conversations are fetched.

conversationsStyle

Style configuration for the component.


Type	`CometChatConversationsStyle`
Default	`CometChatConversationsStyle()`

customSoundForMessages

Path to a custom audio file for incoming message notifications.


Type	`String`
Default	Built-in sound

datePattern

Custom date format function for conversation timestamps.


Type	`String Function(Conversation)`
Default	Built-in date formatting

deleteConversationOptionVisibility

Controls visibility of delete option in context menu.


Type	`bool`
Default	`true`

deliveredIcon

Custom icon for delivered message receipts.


Type	`Widget`
Default	Built-in delivered icon

disableSoundForMessages

Disables notification sound for incoming messages.


Type	`bool`
Default	`false`

emptyStateView

Custom widget displayed when there are no conversations.


Type	`WidgetBuilder`
Default	Built-in empty state

errorStateView

Custom widget displayed when an error occurs.


Type	`WidgetBuilder`
Default	Built-in error state

Hidden when hideError: true.

groupTypeVisibility

Controls visibility of group type icon (public/private/password).


Type	`bool`
Default	`true`

hideAppbar

Hides the entire app bar.


Type	`bool`
Default	`false`

hideError

Hides the default and custom error views.


Type	`bool`
Default	`false`

hideSearch

Hides the search bar in the app bar.


Type	`bool`
Default	`false`

leadingView

Custom renderer for the avatar / left section.


Type	`Widget? Function(BuildContext, Conversation)`
Default	Built-in avatar

Return null to use the default avatar.

listItemView

Custom renderer for the entire list item row.


Type	`Widget Function(Conversation)`
Default	Built-in list item

loadingStateView

Custom widget displayed during loading state.


Type	`WidgetBuilder`
Default	Built-in shimmer

mentionAllLabel

Custom label for group mentions (@channel, @everyone).


Type	`String`
Default	`null`

mentionAllLabelId

Custom label ID for group mentions.


Type	`String`
Default	`null`

onBack

Callback fired when the back button is pressed.


Type	`VoidCallback`
Default	`null`

onEmpty

Callback fired when the conversation list is empty.


Type	`OnEmpty`
Default	`null`

onError

Callback fired when the component encounters an error.


Type	`OnError`
Default	`null`

onItemLongPress

Callback fired when a conversation row is long-pressed.


Type	`Function(Conversation)`
Default	`null`

onItemTap

Callback fired when a conversation row is tapped.


Type	`Function(Conversation)`
Default	`null`

onLoad

Callback fired when the conversation list is loaded.


Type	`OnLoad<Conversation>`
Default	`null`

onSearchTap

Callback fired when the search box is tapped.


Type	`GestureTapCallback`
Default	`null`

Requires searchReadOnly: true to work properly.

onSelection

Callback fired when conversations are selected/deselected.


Type	`Function(List<Conversation>?)`
Default	`null`

Requires selectionMode to be set.

privateGroupIcon

Custom icon for private group indicator.


Type	`Widget`
Default	Built-in lock icon

protectedGroupIcon

Custom icon for password-protected group indicator.


Type	`Widget`
Default	Built-in lock icon

readIcon

Custom icon for read message receipts.


Type	`Widget`
Default	Built-in read icon

receiptsVisibility

Controls visibility of message read/delivery receipts.


Type	`bool`
Default	`true`

scrollController

Custom scroll controller for the list.


Type	`ScrollController`
Default	`null`

searchBoxIcon

Custom prefix icon for the search box.


Type	`Widget`
Default	Built-in search icon

searchContentPadding

Padding for search box content.


Type	`EdgeInsetsGeometry`
Default	`null`

searchPadding

Padding for the search box.


Type	`EdgeInsetsGeometry`
Default	`null`

searchReadOnly

Makes the search box read-only (tap only).


Type	`bool`
Default	`false`

selectionMode

Enables single or multi-select mode.


Type	`SelectionMode`
Default	`null`

Values: SelectionMode.single, SelectionMode.multiple, SelectionMode.none Must pair with onSelection to capture selections.

sentIcon

Custom icon for sent message receipts.


Type	`Widget`
Default	Built-in sent icon

setOptions

Replaces the list of actions available on long press.


Type	`List<CometChatOption>? Function(Conversation, CometChatConversationsController, BuildContext)`
Default	`null`

showBackButton

Shows the back button in the app bar.


Type	`bool`
Default	`false`

subtitleView

Custom renderer for the last message preview.


Type	`Widget? Function(BuildContext, Conversation)`
Default	Built-in subtitle

textFormatters

Custom text formatters for the conversation subtitle.


Type	`List<CometChatTextFormatter>`
Default	Default formatters from data source

See CometChatMentionsFormatter for mention formatting.

title

Custom title text for the app bar.


Type	`String`
Default	”Chats”

titleView

Custom renderer for the name / title text.


Type	`Widget? Function(BuildContext, Conversation)`
Default	Built-in title

trailingView

Custom renderer for the timestamp / badge / right section.


Type	`Widget? Function(Conversation)`
Default	Built-in trailing view

typingIndicatorText

Custom text shown when a user is typing.


Type	`String`
Default	”typing…“

usersStatusVisibility

Controls visibility of online/offline status indicator.


Type	`bool`
Default	`true`

avatarHeight

Height for user/group avatars.


Type	`double`
Default	`null`

avatarWidth

Width for user/group avatars.


Type	`double`
Default	`null`

avatarPadding

Padding for user/group avatars.


Type	`EdgeInsetsGeometry`
Default	`null`

avatarMargin

Margin for user/group avatars.


Type	`EdgeInsetsGeometry`
Default	`null`

badgeWidth

Width for unread message badge.


Type	`double`
Default	`null`

badgeHeight

Height for unread message badge.


Type	`double`
Default	`null`

badgePadding

Padding for unread message badge.


Type	`EdgeInsetsGeometry`
Default	`null`

controllerTag

Tag for controller management. When passed, parent is responsible for closing.


Type	`String`
Default	`null`

dateBackgroundIsTransparent

Controls whether the date background is transparent.


Type	`bool`
Default	`null`

dateHeight

Height for the conversation date display.


Type	`double`
Default	`null`

datePadding

Padding for the conversation date display.


Type	`EdgeInsets`
Default	`null`

dateTimeFormatterCallback

Callback for custom date and time formatting.


Type	`DateTimeFormatterCallback`
Default	`null`

dateWidth

Width for the conversation date display.


Type	`double`
Default	`null`

listItemStyle

Style configuration for list items.


Type	`ListItemStyle`
Default	`null`

searchContentPadding

Padding for search box content.


Type	`EdgeInsetsGeometry`
Default	`null`

searchPadding

Padding for the search box.


Type	`EdgeInsetsGeometry`
Default	`null`

statusIndicatorBorderRadius

Border radius for the status indicator.


Type	`BorderRadiusGeometry`
Default	`null`

statusIndicatorHeight

Height for the status indicator.


Type	`double`
Default	`null`

statusIndicatorWidth

Width for the status indicator.


Type	`double`
Default	`null`

submitIcon

Custom submit icon for selection mode.


Type	`Widget`
Default	Built-in check icon

Events

Event	Payload	Fires when
`CometChatConversationEvents.ccConversationDeleted`	`Conversation`	Conversation deleted from list
`CometChatConversationEvents.ccUpdateConversation`	`Conversation`	Conversation updated (last message change, metadata update)

Subscribe using CometChatConversationEvents.addConversationListListener() and unsubscribe with removeConversationListListener().

Customization Matrix

What to change	Where	Property/API	Example
Override behavior on user interaction	Widget props	`on<Event>` callbacks	`onItemTap: (c) => setActive(c)`
Filter which conversations appear	Widget props	`conversationsRequestBuilder`	`conversationsRequestBuilder: ConversationsRequestBuilder()..limit = 10`
Toggle visibility of UI elements	Widget props	`<feature>Visibility` boolean props	`receiptsVisibility: false`
Replace a section of the list item	Widget props	`<slot>View` render props	`listItemView: (conversation) => CustomWidget()`
Change colors, fonts, spacing	Widget props	`conversationsStyle`	`conversationsStyle: CometChatConversationsStyle(backgroundColor: Colors.white)`

Users

Display and select from a list of users

Groups

Display and select from a list of groups

Message List

Display messages in a conversation

Theming

Customize the look and feel of components

​Where It Fits

​Minimal Render

​Filtering Conversations

​Filter Recipes

​ConversationsRequestBuilder Properties

​Actions and Events

​Callback Props

​onItemTap

​onItemLongPress

​onSelection

​onError

​onBack

​onLoad

​onEmpty

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Custom View Slots

​listItemView

​leadingView

​titleView

​subtitleView

​trailingView

​setOptions

​addOptions

​appBarOptions

​Styling

​Style Properties

​Common Patterns

​Custom empty state with CTA

​Hide all chrome — minimal list

​Conversations with search

​Custom date pattern

​Text formatters

​Accessibility

​Props

​activateSelection

​addOptions

​appBarOptions

​backButton

​conversationsRequestBuilder

​conversationsProtocol

​conversationsStyle

​customSoundForMessages

​datePattern

​deleteConversationOptionVisibility

​deliveredIcon

​disableSoundForMessages

​emptyStateView

​errorStateView

​groupTypeVisibility

​hideAppbar

​hideError

​hideSearch

​leadingView

​listItemView

​loadingStateView

​mentionAllLabel

​mentionAllLabelId

​onBack

​onEmpty

​onError

​onItemLongPress

​onItemTap

​onLoad

​onSearchTap

​onSelection

​privateGroupIcon

​protectedGroupIcon

​readIcon

​receiptsVisibility

​scrollController

​searchBoxIcon

​searchContentPadding

​searchPadding

​searchReadOnly

​selectionMode

​sentIcon

​setOptions

​showBackButton

​subtitleView

Where It Fits

Minimal Render

Filtering Conversations

Filter Recipes

ConversationsRequestBuilder Properties

Actions and Events

Callback Props

onItemTap

onItemLongPress

onSelection

onError

onBack

onLoad

onEmpty

Global UI Events

SDK Events (Real-Time, Automatic)

Custom View Slots

listItemView

leadingView

titleView

subtitleView

trailingView

setOptions

addOptions

appBarOptions

Styling

Style Properties

Common Patterns

Custom empty state with CTA

Hide all chrome — minimal list

Conversations with search

Custom date pattern

Text formatters

Accessibility

Props

activateSelection

addOptions

appBarOptions

backButton

conversationsRequestBuilder

conversationsProtocol

conversationsStyle

customSoundForMessages

datePattern

deleteConversationOptionVisibility

deliveredIcon

disableSoundForMessages

emptyStateView

errorStateView

groupTypeVisibility

hideAppbar

hideError

hideSearch

leadingView

listItemView

loadingStateView

mentionAllLabel

mentionAllLabelId

onBack

onEmpty

onError

onItemLongPress

onItemTap

onLoad

onSearchTap

onSelection

privateGroupIcon

protectedGroupIcon

readIcon

receiptsVisibility

scrollController

searchBoxIcon

searchContentPadding

searchPadding

searchReadOnly

selectionMode

sentIcon

setOptions

showBackButton

subtitleView