Conversations - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatConversations`
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	Display CometChat Flutter UI Kit conversations with real-time updates for messages, typing indicators, read receipts, and presence.
Data props	`conversationsRequestBuilder`
Actions	`onSelection` · `onBack` · `onItemTap` · `onItemLongPress` · `onLoad` · `onEmpty` · `onError` · `onSearchTap` — details
View slots	`subtitleView` · `listItemView` · `emptyStateView` · `errorStateView` · `trailingView` · `loadingStateView` · `leadingView` · `titleView` — details
Styling	`conversationsStyle` — the app `ThemeData` does not reach inside a kit widget, so scope colours here.
Layout	Fills its parent — place it in an `Expanded` (or a sized box) inside a `Column`, or layout throws an unbounded-height error at render.
Stitching	Tap a conversation to open a message view built from `CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer`.
Prerequisites	`CometChatUIKit` initialised and a user logged in.
Full props	72 props

CometChatConversations renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence.

Where It Fits

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

Dart

CometChatConversations(
  onItemTap: (conversation) {
    final entity = conversation.conversationWith;
    if (entity is User) {
      navigateToUserChat(entity);
    } else if (entity is Group) {
      navigateToGroupChat(entity);
    }
  },
)

Quick Start

Using Navigator:

Dart

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

Embedding as a widget:

Dart

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

Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the UI Kit dependency added.

Filtering Conversations

Pass a ConversationsRequestBuilder to control what loads:

Dart

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

Filter Recipes

Recipe	Builder property
Only user conversations	`..conversationType = "user"`
Only group conversations	`..conversationType = "group"`
Limit per page	`..limit = 10`
With tags	`..tags = ["vip"]` and `..withTags = true`
With user and group tags	`..withUserAndGroupTags = true`

Actions and Events

Callback Methods

`onItemTap`

Fires when a conversation row is tapped. Primary navigation hook.

Dart

CometChatConversations(
  onItemTap: (conversation) {
    // Navigate to chat screen
  },
)

`onItemLongPress`

Fires when a conversation row is long-pressed. By default the row opens a context menu with Pin / Unpin (v6.1.1 and later, when pinConversationOptionVisibility is not false) and Delete (when deleteConversationOptionVisibility is true). Setting this callback replaces that menu.

Dart

CometChatConversations(
  onItemLongPress: (conversation) {
    // Custom long press behavior
  },
)

`onBack`

Fires when the user presses the back button in the app bar.

Dart

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

`onSelection`

Fires when conversations are selected/deselected in multi-select mode.

Dart

CometChatConversations(
  selectionMode: SelectionMode.multiple,
  onSelection: (selectedConversations) {
    // Handle selected conversations
  },
)

`onError`

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

Dart

CometChatConversations(
  onError: (e) {
    debugPrint("Error: $e");
  },
)

`onLoad`

Fires when the list is successfully fetched and loaded.

Dart

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

`onEmpty`

Fires when the list is empty after loading.

Dart

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

Global Events

The component emits events via CometChatConversationEvents that can be subscribed to from anywhere:

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) {
    // Handle conversation deleted
  }
}

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

SDK Listener	Internal behavior
`onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived`	Moves conversation to top, updates last message and unread count
`onTypingStarted` / `onTypingEnded`	Shows/hides typing indicator in subtitle
`onMessagesDelivered` / `onMessagesRead`	Updates receipt indicators
`onUserOnline` / `onUserOffline`	Updates presence status dot
`onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned`	Updates group conversation metadata
Connection reconnected	Triggers silent refresh to sync missed messages

Functionality

Property	Type	Default	Description
`conversationsProtocol`	`ConversationsBuilderProtocol?`	`null`	`conversationsProtocol` Request builder protocol to fetch conversations.
`subtitleView`	`Widget? Function(BuildContext context, Conversation conversation)?`	`null`	`subtitleView` to set subtitle for each conversation
`listItemView`	`Widget Function(Conversation conversation)?`	`null`	`listItemView` set custom view for each conversation
`conversationsStyle`	`CometChatConversationsStyle`	`const CometChatConversationsStyle()`	`conversationsStyle` sets style
`scrollController`	`ScrollController?`	`null`	`scrollController` to handle scrolling behavior.
`backButton`	`Widget?`	`null`	`backButton` back button
`showBackButton`	`bool`	`false`	Toggle back button
`selectionMode`	`SelectionMode?`	`null`	Enable selection mode (`single` or `multiple`)
`onSelection`	`Function(List<Conversation>? list)?`	`null`	`onSelection` function will be performed
`title`	`String?`	`null`	Custom app bar title
`conversationsRequestBuilder`	`ConversationsRequestBuilder?`	`null`	`conversationsRequestBuilder` Request builder to fetch conversations.
`hideError`	`bool?`	`null`	`hideError` toggle visibility of error dialog
`emptyStateView`	`WidgetBuilder?`	`null`	`emptyStateView` returns view fow empty state
`errorStateView`	`WidgetBuilder?`	`null`	`errorStateView` returns view fow error state
`listItemStyle`	`ListItemStyle?`	`null`	`listItemStyle` style for every list item
`trailingView`	`Widget? Function(Conversation conversation)?`	`null`	`trailingView` to set tailView for each conversation
`appBarOptions`	`List<Widget>?`	`null`	`appBarOptions` list of options to be visible in app bar
`usersStatusVisibility`	`bool?`	`true`	Show online/offline status indicator
`receiptsVisibility`	`bool?`	`true`	Show message receipts
`protectedGroupIcon`	`Widget?`	`null`	`protectedGroupIcon` provides icon in status indicator for protected group
`privateGroupIcon`	`Widget?`	`null`	`privateGroupIcon` provides icon in status indicator for private group
`readIcon`	`Widget?`	`null`	`readIcon` provides icon in read receipts if a message is read
`deliveredIcon`	`Widget?`	`null`	`deliveredIcon` provides icon in read receipts if a message is delivered
`sentIcon`	`Widget?`	`null`	`sentIcon` provides icon in read receipts if a message is sent
`activateSelection`	`ActivateSelection?`	`null`	`activateSelection` lets the widget know if conversations are allowed to be selected
`datePattern`	`String Function(Conversation conversation)?`	`null`	`datePattern` is used to generate customDateString for CometChatDate
`typingIndicatorText`	`String?`	`null`	`typingIndicatorText` if not null is visible instead of default text shown when another user is typing
`onBack`	`VoidCallback?`	`null`	`onBack` callback triggered on closing this screen
`onItemTap`	`Function(Conversation conversation)?`	`null`	`onItemTap` callback triggered on tapping a conversation item
`onItemLongPress`	`Function(Conversation conversation)?`	`null`	`onItemLongPress` callback triggered on pressing for long on a conversation item
`hideAppbar`	`bool?`	`false`	Toggle app bar visibility
`textFormatters`	`List<CometChatTextFormatter>?`	`null`	`textFormatters` is a list of text formatters for message bubbles with type text
`mentionAllLabel`	`String?`	`null`	`mentionAllLabel` is a String which is used to set a custom label for @all mentions
`mentionAllLabelId`	`String?`	`null`	`mentionAllLabelId` is a String which is used to set a custom label ID for @all mentions
`datePadding`	`EdgeInsets?`	`null`	`datePadding` provides padding for `CometChatDate`
`dateHeight`	`double?`	`null`	`dateHeight` provides height for `CometChatDate`
`dateBackgroundIsTransparent`	`bool?`	`null`	`dateBackgroundIsTransparent` controls the background of `CometChatDate`
`dateWidth`	`double?`	`null`	`dateWidth` provides width for `CometChatDate`
`badgeWidth`	`double?`	`null`	`badgeWidth` provides width for `CometChatBadge`
`badgeHeight`	`double?`	`null`	`badgeHeight` provides height for `CometChatBadge`
`badgePadding`	`EdgeInsetsGeometry?`	`null`	`badgePadding` provides padding to the widget
`statusIndicatorWidth`	`double?`	`null`	`statusIndicatorWidth` provides width to the status indicator
`statusIndicatorHeight`	`double?`	`null`	`statusIndicatorHeight` provides height to the status indicator
`statusIndicatorBorderRadius`	`BorderRadiusGeometry?`	`null`	`statusIndicatorBorderRadius` provides borderRadius to the status indicator
`avatarMargin`	`EdgeInsetsGeometry?`	`null`	`avatarMargin` provides margin to the widget
`avatarPadding`	`EdgeInsetsGeometry?`	`null`	`avatarPadding` provides padding to the widget
`avatarWidth`	`double?`	`null`	`avatarWidth` provides width to the widget
`avatarHeight`	`double?`	`null`	`avatarHeight` provides height to the widget
`deleteConversationOptionVisibility`	`bool?`	`true`	Show delete option on long press
`pinConversationOptionVisibility`	`bool?`	`true`	Show the Pin / Unpin option on long press. Available since v6.1.1.
`groupTypeVisibility`	`bool?`	`true`	Show group type icon on avatar
`setOptions`	`List<CometChatOption>? Function( Conversation conversation, ConversationsBloc bloc, BuildContext context, )?`	`null`	`setOptions` sets List of actions available on the long press of list item
`addOptions`	`List<CometChatOption>? Function( Conversation conversation, ConversationsBloc bloc, BuildContext context, )?`	`null`	`addOptions` adds into the current List of actions available on the long press of list item
`loadingStateView`	`WidgetBuilder?`	`null`	`loadingStateView` returns view fow loading state
`leadingView`	`Widget? Function(BuildContext context, Conversation conversation)?`	`null`	`leadingView` to set leading view for each conversation
`titleView`	`Widget? Function(BuildContext context, Conversation conversation)?`	`null`	`titleView` to set title view for each conversation
`controllerTag`	`String?`	`null`	`controllerTag` tag to create from , if this is passed its parent responsibility to close this
`onLoad`	`OnLoad<Conversation>?`	`null`	`onLoad` callback triggered when conversations are loaded successfully
`onEmpty`	`OnEmpty?`	`null`	`onEmpty` callback triggered when the conversations list is empty
`onError`	`OnError?`	`null`	`onError` callback triggered when the component encounters an error
`customSoundForMessages`	`String?`	`null`	Custom notification sound asset path
`disableSoundForMessages`	`bool?`	`false`	Disable message sounds
`submitIcon`	`Widget?`	`null`	`submitIcon` will override the default submit icon
`dateTimeFormatterCallback`	`DateTimeFormatterCallback?`	`null`	`dateTimeFormatterCallback` is a callback that can be used to format the date and time
`conversationsBloc`	`ConversationsBloc?`	`null`	`conversationsBloc` Optional external ConversationsBloc instance.
`routeObserver`	`RouteObserver<ModalRoute<void>>?`	`null`	`routeObserver` Optional RouteObserver to detect when this widget is not visible.
`hideSearch`	`bool?`	`null`	Toggle search bar
`searchReadOnly`	`bool`	`false`	Make search bar read-only (tap opens custom search)
`onSearchTap`	`GestureTapCallback?`	`null`	`onSearchTap` callback triggered on search box tap
`searchBoxIcon`	`Widget?`	`null`	`searchBoxIcon` search box prefix icon
`searchPadding`	`EdgeInsetsGeometry?`	`null`	`searchPadding` provides padding to the search
`searchContentPadding`	`EdgeInsetsGeometry?`	`null`	`searchContentPadding` provides padding to the search content

Custom View Slots

Leading View

Replace the avatar / left section.

Conversation.conversationWith is an AppEntity (a User or a Group), so it has no .name. Narrow the type before reading a display name. The snippets below use this helper:

String _displayName(Conversation conversation) {
  final entity = conversation.conversationWith;
  return entity is User ? entity.name : (entity is Group ? entity.name : "");
}

Dart

CometChatConversations(
  leadingView: (context, conversation) {
    return CircleAvatar(
      child: Text(_displayName(conversation).isNotEmpty ? _displayName(conversation)[0] : ""),
    );
  },
)

Title View

Replace the name / title text.

Dart

CometChatConversations(
  titleView: (context, conversation) {
    return Text(
      _displayName(conversation),
      style: TextStyle(fontWeight: FontWeight.bold),
    );
  },
)

Subtitle View

Replace the last message preview.

Dart

CometChatConversations(
  subtitleView: (context, conversation) {
    final msg = conversation.lastMessage;
    if (msg is TextMessage) {
      return Text(msg.text, maxLines: 1, overflow: TextOverflow.ellipsis);
    }
    return Text("New conversation");
  },
)

Trailing View

Replace the timestamp / badge / right section.

Dart

CometChatConversations(
  trailingView: (conversation) {
    if (conversation.unreadMessageCount > 0) {
      return Badge(label: Text("${conversation.unreadMessageCount}"));
    }
    return null;
  },
)

List Item View

Replace the entire list item row.

Dart

CometChatConversations(
  listItemView: (conversation) {
    return ListTile(
      leading: CircleAvatar(
        child: Text(_displayName(conversation).isNotEmpty ? _displayName(conversation)[0] : ""),
      ),
      title: Text(_displayName(conversation)),
      subtitle: Text("Custom item"),
    );
  },
)

State Views

Dart

CometChatConversations(
  emptyStateView: (context) => Center(child: Text("No conversations yet")),
  errorStateView: (context) => Center(child: Text("Something went wrong")),
  loadingStateView: (context) => Center(child: CircularProgressIndicator()),
)

Dart

// Replace all options
CometChatConversations(
  setOptions: (conversation, bloc, context) {
    return [
      CometChatOption(
        id: "delete",
        icon: AssetConstants.delete,
        title: "Delete",
        onClick: () {
          bloc.add(DeleteConversation(conversation.conversationId!));
        },
      ),
    ];
  },
)

// Append to defaults
CometChatConversations(
  addOptions: (conversation, bloc, context) {
    return [
      CometChatOption(
        id: "archive",
        iconWidget: Icon(Icons.archive_outlined),
        title: "Archive",
        onClick: () {
          // Archive conversation
        },
      ),
    ];
  },
)

Pin Conversations

Available since v6.1.1 Long-pressing a row opens a context menu with Pin / Unpin alongside Delete. Pinned rows show a pin icon and form a shelf at the top of the list, ordered system pins first (placed by an admin surface, pinnedBy == "app_system"), then the user’s own pins, then the remaining conversations by latest activity. Real-time events keep that ordering: new activity moves a conversation to the top of its own section only, never above a pin. Everything is wired through the SDK’s Pin A Conversation APIs: the component performs the pin/unpin call, shows a “Conversation pinned” / “Conversation unpinned” toast — or, at the cap, “You can only pin N chats. Unpin one to pin another.” with the server’s limit — and reorders the list from the SDK’s ConversationListener events, including pins made from the user’s other devices. The option is offered on unpinned rows and on rows the logged-in user pinned. It is withheld from rows pinned by anyone else — app_system or another UID — which keep the pin icon but cannot be unpinned from the client. It also hides itself when CometChat.isPinConversationEnabled() returns false. To hide it regardless, set pinConversationOptionVisibility to false.

Passing your own onItemLongPress replaces the built-in context menu, Pin and Delete included. From v6.2.0, setOptions also replaces the built-in Pin and Delete entries with the options you return, while addOptions keeps them and lists your options in front.

Dart

CometChatConversations(
  pinConversationOptionVisibility: false, // hide pin/unpin from the long-press menu
)

Common Patterns

Minimal list — hide all chrome

Dart

CometChatConversations(
  hideAppbar: true,
  hideSearch: true,
)

Users-only conversations

Dart

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

Custom date formatting

Dart

CometChatConversations(
  datePattern: (conversation) {
    final timestamp = conversation.updatedAt;
    return DateFormat('MMM d').format(DateTime.fromMillisecondsSinceEpoch(timestamp! * 1000));
  },
)

Advanced

BLoC Access

Provide a custom ConversationsBloc to override behavior:

Dart

CometChatConversations(
  conversationsBloc: CustomConversationsBloc(),
)

Extending ConversationsBloc

ConversationsBloc uses the ListBase<Conversation> mixin with override hooks for custom list behavior:

Dart

class CustomConversationsBloc extends ConversationsBloc {
  @override
  void onItemAdded(Conversation item, List<Conversation> updatedList) {
    // Custom sorting — keep the bloc's pinned shelf (v6.1.1+) on top
    final sorted = _sortWithinPinTiers(updatedList);
    super.onItemAdded(item, sorted);
  }

  @override
  void onListReplaced(List<Conversation> previousList, List<Conversation> newList) {
    // Filter out blocked users on every list refresh
    final filtered = newList.where((c) => !isBlocked(c)).toList();
    super.onListReplaced(previousList, filtered);
  }
}

For ListBase override hooks (onItemAdded, onItemRemoved, onItemUpdated, onListCleared, onListReplaced), see BLoC & Data — ListBase Hooks.

Public BLoC Events

Event	Description
`LoadConversations({silent})`	Load initial conversations. `silent: true` keeps existing list visible during refresh.
`LoadMoreConversations()`	Load next page (pagination)
`RefreshConversations()`	Refresh the list
`DeleteConversation(conversationId)`	Delete via SDK and remove from list
`RemoveConversation(conversationId)`	Remove from list without SDK call
`SetActiveConversation(conversationId)`	Mark as active (suppresses unread count)
`UpdateConversation(conversationId, updatedConversation)`	Update with modified data
`ResetUnreadCount(conversationId)`	Reset unread count to 0

Public BLoC Methods

Method	Returns	Description
`getTypingNotifier(conversationId)`	`ValueNotifier<List<TypingIndicator>>`	Per-conversation typing notifier for isolated rebuilds
`getTypingIndicators(conversationId)`	`List<TypingIndicator>`	Current typing indicators for a conversation

Route Observer

Pass a RouteObserver to freeze rebuilds when another screen is pushed on top (prevents expensive rebuilds during keyboard animation):

Dart

// In your app
final RouteObserver<ModalRoute<void>> routeObserver = RouteObserver<ModalRoute<void>>();

MaterialApp(
  navigatorObservers: [routeObserver],
)

// Pass to conversations
CometChatConversations(
  routeObserver: routeObserver,
)

Style

Dart

CometChatConversations(
  conversationsStyle: CometChatConversationsStyle(
    backgroundColor: Colors.white,
    avatarStyle: CometChatAvatarStyle(
      borderRadius: BorderRadius.circular(8),
      backgroundColor: Color(0xFFFBAA75),
    ),
    badgeStyle: CometChatBadgeStyle(
      backgroundColor: Color(0xFFF76808),
    ),
    receiptStyle: CometChatMessageReceiptStyle(),
    typingIndicatorStyle: CometChatTypingIndicatorStyle(),
    dateStyle: CometChatDateStyle(),
    mentionsStyle: CometChatMentionsStyle(),
    deleteConversationDialogStyle: CometChatConfirmDialogStyle(),
  ),
)

Style Properties

Property	Description
`backgroundColor`	List background color
`avatarStyle`	Avatar appearance
`badgeStyle`	Unread badge appearance
`receiptStyle`	Read receipt icons
`typingIndicatorStyle`	Typing indicator text
`dateStyle`	Timestamp appearance
`mentionsStyle`	Mention highlight style
`deleteConversationDialogStyle`	Delete confirmation dialog

See Component Styling for the full reference.

Next Steps

Users

Browse and search available users

Message List

Display messages for a conversation

Component Styling

Detailed styling reference

Message Template

Customize message bubble structure

​Where It Fits

​Quick Start

​Filtering Conversations

​Filter Recipes

​Actions and Events

​Callback Methods

​onItemTap

​onItemLongPress

​onBack

​onSelection

​onError

​onLoad

​onEmpty

​Global Events

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​Leading View

​Title View

​Subtitle View

​Trailing View

​List Item View

​State Views

​Menu Options

​Pin Conversations

​Common Patterns

​Minimal list — hide all chrome

​Users-only conversations

​Custom date formatting

​Advanced

​BLoC Access

​Extending ConversationsBloc

​Public BLoC Events

​Public BLoC Methods

​Route Observer

​Style

​Style Properties

​Next Steps

Users

Message List

Component Styling

Message Template

Where It Fits

Quick Start

Filtering Conversations

Filter Recipes

Actions and Events

Callback Methods

`onItemTap`

`onItemLongPress`

`onBack`

`onSelection`

`onError`

`onLoad`

`onEmpty`

Global Events

SDK Events (Real-Time, Automatic)

Functionality

Custom View Slots

Leading View

Title View

Subtitle View

Trailing View

List Item View

State Views

Menu Options

Pin Conversations

Common Patterns

Minimal list — hide all chrome

Users-only conversations

Custom date formatting

Advanced

BLoC Access

Extending ConversationsBloc

Public BLoC Events

Public BLoC Methods

Route Observer

Style

Style Properties

Next Steps