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	71 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 shows a delete overlay (when deleteConversationOptionVisibility is true).

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
`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
        },
      ),
    ];
  },
)

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 — pinned conversations first
    final sorted = _sortWithPinnedFirst(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

​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