> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Scrollable list of recent one-on-one and group conversations for the logged-in user.

<Accordion title="AI Agent Component Spec">
  ```json theme={null}
  {
    "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"
      }
    }
  }
  ```
</Accordion>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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'),
                      ),
              ),
            ],
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/mNTojjz_O28of40c/images/f2c77c5b-Conversation-ac41cc6650fbb941c64f389aee910dbc.png?fit=max&auto=format&n=mNTojjz_O28of40c&q=85&s=902e3c935963dec9f907348888829eab" width="1280" height="800" data-path="images/f2c77c5b-Conversation-ac41cc6650fbb941c64f389aee910dbc.png" />
</Frame>

***

## Minimal Render

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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(),
          ),
        );
      }
    }
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/mq8rEbFfi0JjKmkM/images/68da96e3-conversations-22a7ffeca154c79c33e12b924a516447.png?fit=max&auto=format&n=mq8rEbFfi0JjKmkM&q=85&s=204e9e3c7bb93a46da7cd6aac3cd01d2" width="720" height="1440" data-path="images/68da96e3-conversations-22a7ffeca154c79c33e12b924a516447.png" />
</Frame>

You can also launch it using `Navigator.push`:

```dart theme={null}
Navigator.push(
  context, 
  MaterialPageRoute(builder: (context) => const CometChatConversations())
);
```

***

## Filtering Conversations

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      conversationsRequestBuilder: ConversationsRequestBuilder()
        ..conversationType = "user"
        ..limit = 10,
    )
    ```
  </Tab>
</Tabs>

### 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](/sdk/flutter/retrieve-conversations) 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onItemTap: (conversation) {
        print("Selected: ${conversation.conversationId}");
      },
    )
    ```
  </Tab>
</Tabs>

#### onItemLongPress

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onItemLongPress: (conversation) {
        // Show custom context menu
      },
    )
    ```
  </Tab>
</Tabs>

#### onSelection

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      selectionMode: SelectionMode.multiple,
      onSelection: (selectedList) {
        print("Selected ${selectedList?.length ?? 0} conversations");
      },
    )
    ```
  </Tab>
</Tabs>

#### onError

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onError: (error) {
        print("CometChatConversations error: $error");
      },
    )
    ```
  </Tab>
</Tabs>

#### onBack

Fires when the back button is pressed.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      showBackButton: true,
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### onLoad

Fires when the conversation list is successfully loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onLoad: (list) {
        print("Loaded ${list.length} conversations");
      },
    )
    ```
  </Tab>
</Tabs>

#### onEmpty

Fires when the conversation list is empty.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      onEmpty: () {
        print("No conversations found");
      },
    )
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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}");
      }
    }
    ```
  </Tab>
</Tabs>

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/_MYSdWhXnUkTkjEH/images/46c507bf-conversation_listitem_view-ca293b2d4eacf61572e21f6fd399ff30.png?fit=max&auto=format&n=_MYSdWhXnUkTkjEH&q=85&s=fda146c9e9e15d3821095d8773ff4f61" width="2560" height="1600" data-path="images/46c507bf-conversation_listitem_view-ca293b2d4eacf61572e21f6fd399ff30.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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),
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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),
    )
    ```
  </Tab>
</Tabs>

### leadingView

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/le8ibYc8lBJsShSE/images/50dd219e-conversation_leading_view-65768f699fe3f064c14b0491f7ce0f91.png?fit=max&auto=format&n=le8ibYc8lBJsShSE&q=85&s=d7bba2e7d924eebd98fa5fbfee18701a" width="2560" height="1600" data-path="images/50dd219e-conversation_leading_view-65768f699fe3f064c14b0491f7ce0f91.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // 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
          },
        );
      }
    }
    ```
  </Tab>
</Tabs>

### titleView

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/G6Puyz_3Zlaowa9R/images/ca63e2f2-conversation_title_view-41ee32465c311e39b37abddf95bbf190.png?fit=max&auto=format&n=G6Puyz_3Zlaowa9R&q=85&s=44b52fa53ec6ae7eeb15277d2a46299c" width="2560" height="1600" data-path="images/ca63e2f2-conversation_title_view-41ee32465c311e39b37abddf95bbf190.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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))),
          ],
        );
      },
    )
    ```
  </Tab>
</Tabs>

### subtitleView

Replace the last message preview text.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/7a4hqm7gLVRmX34O/images/00017e69-conversation_subtitleview-da365aba84e7c1ecec9234912eb1a7db.png?fit=max&auto=format&n=7a4hqm7gLVRmX34O&q=85&s=aa7a39f8a5d1b7a47314547351d6e14c" width="2560" height="1600" data-path="images/00017e69-conversation_subtitleview-da365aba84e7c1ecec9234912eb1a7db.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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));
      },
    )
    ```
  </Tab>
</Tabs>

### trailingView

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/JSRiWiPGBHsJZFCg/images/9c92115a-conversation_trailing_view-15ca261b8d20291c19b48c7f7af81976.png?fit=max&auto=format&n=JSRiWiPGBHsJZFCg&q=85&s=e18b00799b31bda3718d96045bae2676" width="2560" height="1600" data-path="images/9c92115a-conversation_trailing_view-15ca261b8d20291c19b48c7f7af81976.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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)),
              ],
            ),
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### setOptions

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

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/mkn0UqPQ5BXljCV1/images/9415d47d-conversation_set_option-42a75eb50360de67a9bfab69beefbda3.png?fit=max&auto=format&n=mkn0UqPQ5BXljCV1&q=85&s=cedd3a76dcfc73494e2651818ff49ef1" width="1280" height="800" data-path="images/9415d47d-conversation_set_option-42a75eb50360de67a9bfab69beefbda3.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      setOptions: (conversation, controller, context) {
        return [
          CometChatOption(
            id: "delete",
            title: "Delete",
            icon: AssetConstants.delete,
            onClick: () {
              // Delete conversation
            },
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

### addOptions

Add to the existing context menu actions without removing defaults.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/ubfBSdV1t6rmjxeA/images/88283fe5-conversation_add_options-c0f407ccc43b5f040d9ab9147e17def0.png?fit=max&auto=format&n=ubfBSdV1t6rmjxeA&q=85&s=05aa1266da3006611bef12d50ab50e0f" width="1280" height="800" data-path="images/88283fe5-conversation_add_options-c0f407ccc43b5f040d9ab9147e17def0.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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
            },
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

### appBarOptions

Add custom widgets to the app bar.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/Gp90C5sdVtuRR4t7/images/835761c9-conversation_menu-e4a2a88888d75b51127bf7d5b7644332.png?fit=max&auto=format&n=Gp90C5sdVtuRR4t7&q=85&s=b6561a13798e8e353a611c2119ca58cc" width="2560" height="1600" data-path="images/835761c9-conversation_menu-e4a2a88888d75b51127bf7d5b7644332.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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
          },
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

For a more complete popup menu with styling:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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
      },
    )
    ```
  </Tab>
</Tabs>

***

## Styling

Set `CometChatConversationsStyle` to customize the appearance.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatConversations(
      conversationsStyle: CometChatConversationsStyle(
        backgroundColor: Colors.white,
        titleTextColor: Color(0xFF141414),
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        badgeStyle: CometChatBadgeStyle(
          backgroundColor: Color(0xFFF76808),
        ),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/xIG5VBdyNJ5cYSqE/images/d0ef0279-conversation_styling-22ac86dbef32a65c2320f06f70301560.png?fit=max&auto=format&n=xIG5VBdyNJ5cYSqE&q=85&s=caace7bc1cc67736578711bf53e87f3e" width="2560" height="1600" data-path="images/d0ef0279-conversation_styling-22ac86dbef32a65c2320f06f70301560.png" />
</Frame>

### 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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.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"),
              ),
            ],
          ),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Hide all chrome — minimal list

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    CometChatConversations(
      receiptsVisibility: false,
      usersStatusVisibility: false,
      groupTypeVisibility: false,
      deleteConversationOptionVisibility: false,
      hideAppbar: true,
    )
    ```
  </Tab>
</Tabs>

### Conversations with search

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    CometChatConversations(
      hideSearch: false,
      onSearchTap: () {
        // Handle search tap - navigate to search screen
      },
    )
    ```
  </Tab>
</Tabs>

### Custom date pattern

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/TO10Bmu50bb5qPTI/images/2edb1799-conversation_date_pattern-3ed51f58de4a22b26c555c101b3c7f50.png?fit=max&auto=format&n=TO10Bmu50bb5qPTI&q=85&s=ad241e0d5ee06d509c165030e5f5b695" width="2560" height="1600" data-path="images/2edb1799-conversation_date_pattern-3ed51f58de4a22b26c555c101b3c7f50.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
    import 'package:intl/intl.dart';

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

### Text formatters

Configure text formatters for the conversation subtitle. See [CometChatMentionsFormatter](/ui-kit/flutter/v5/mentions-formatter-guide) for mention formatting.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/3EDM5JvI4mnAULac/images/74b20b0e-mentions_styling-8e36e26282f4facd7920dc23ca98b832.png?fit=max&auto=format&n=3EDM5JvI4mnAULac&q=85&s=6a69c1f7c114bdba127dc912e0936aca" width="2560" height="1680" data-path="images/74b20b0e-mentions_styling-8e36e26282f4facd7920dc23ca98b832.png" />
</Frame>

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    CometChatConversations(
      textFormatters: [
        CometChatMentionsFormatter(
          style: CometChatMentionsStyle(
            mentionSelfTextBackgroundColor: Color(0xFFF76808),
            mentionTextBackgroundColor: Colors.white,
            mentionTextColor: Colors.black,
            mentionSelfTextColor: Colors.white,
          ),
        ),
      ],
    )
    ```
  </Tab>
</Tabs>

***

## 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](/ui-kit/flutter/v5/mentions-formatter-guide) 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)` |

***

<CardGroup cols={2}>
  <Card title="Users" icon="users" href="/ui-kit/flutter/v5/users">
    Display and select from a list of users
  </Card>

  <Card title="Groups" icon="user-group" href="/ui-kit/flutter/v5/groups">
    Display and select from a list of groups
  </Card>

  <Card title="Message List" icon="comments" href="/ui-kit/flutter/v5/message-list">
    Display messages in a conversation
  </Card>

  <Card title="Theming" icon="palette" href="/ui-kit/flutter/v5/theme-introduction">
    Customize the look and feel of components
  </Card>
</CardGroup>