Skip to main content

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.

Minimal Render

You can also launch it using Navigator.push:

Filtering Conversations

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

Filter Recipes

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

ConversationsRequestBuilder Properties

Refer to ConversationsRequestBuilder for the full builder API.

Actions and Events

Callback Props

onItemTap

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

onItemLongPress

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

onSelection

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

onError

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

onBack

Fires when the back button is pressed.

onLoad

Fires when the conversation list is successfully loaded.

onEmpty

Fires when the conversation list is empty.

Global UI Events

CometChatConversationEvents emits events subscribable from anywhere in the application. Add a listener in initState and remove it in dispose. 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.

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required. 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.

listItemView

Replace the entire list item row.
For a more complete custom list item with status indicator and date:

leadingView

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

titleView

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

subtitleView

Replace the last message preview text.

trailingView

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

setOptions

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

addOptions

Add to the existing context menu actions without removing defaults.

appBarOptions

Add custom widgets to the app bar.
For a more complete popup menu with styling:

Styling

Set CometChatConversationsStyle to customize the appearance.

Style Properties


Common Patterns

Custom empty state with CTA

Hide all chrome — minimal list

Custom date pattern

Text formatters

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

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. Values: ActivateSelection.onClick, ActivateSelection.onLongClick

addOptions

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

appBarOptions

List of widgets to display in the app bar.

backButton

Custom back button widget.

conversationsRequestBuilder

Controls which conversations load and in what order. Pass the builder instance, not the result of .build().

conversationsProtocol

Custom protocol for fetching conversations. Use this for advanced customization of how conversations are fetched.

conversationsStyle

Style configuration for the component.

customSoundForMessages

Path to a custom audio file for incoming message notifications.

datePattern

Custom date format function for conversation timestamps.

deleteConversationOptionVisibility

Controls visibility of delete option in context menu.

deliveredIcon

Custom icon for delivered message receipts.

disableSoundForMessages

Disables notification sound for incoming messages.

emptyStateView

Custom widget displayed when there are no conversations.

errorStateView

Custom widget displayed when an error occurs. Hidden when hideError: true.

groupTypeVisibility

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

hideAppbar

Hides the entire app bar.

hideError

Hides the default and custom error views.

hideSearch

Hides the search bar in the app bar.

leadingView

Custom renderer for the avatar / left section. Return null to use the default avatar.

listItemView

Custom renderer for the entire list item row.

loadingStateView

Custom widget displayed during loading state.

mentionAllLabel

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

mentionAllLabelId

Custom label ID for group mentions.

onBack

Callback fired when the back button is pressed.

onEmpty

Callback fired when the conversation list is empty.

onError

Callback fired when the component encounters an error.

onItemLongPress

Callback fired when a conversation row is long-pressed.

onItemTap

Callback fired when a conversation row is tapped.

onLoad

Callback fired when the conversation list is loaded.

onSearchTap

Callback fired when the search box is tapped. Requires searchReadOnly: true to work properly.

onSelection

Callback fired when conversations are selected/deselected. Requires selectionMode to be set.

privateGroupIcon

Custom icon for private group indicator.

protectedGroupIcon

Custom icon for password-protected group indicator.

readIcon

Custom icon for read message receipts.

receiptsVisibility

Controls visibility of message read/delivery receipts.

scrollController

Custom scroll controller for the list.

searchBoxIcon

Custom prefix icon for the search box.

searchContentPadding

Padding for search box content.

searchPadding

Padding for the search box.

searchReadOnly

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

selectionMode

Enables single or multi-select mode. Values: SelectionMode.single, SelectionMode.multiple, SelectionMode.none Must pair with onSelection to capture selections.

sentIcon

Custom icon for sent message receipts.

setOptions

Replaces the list of actions available on long press.

showBackButton

Shows the back button in the app bar.

subtitleView

Custom renderer for the last message preview.

textFormatters

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

title

Custom title text for the app bar.

titleView

Custom renderer for the name / title text.

trailingView

Custom renderer for the timestamp / badge / right section.

typingIndicatorText

Custom text shown when a user is typing.

usersStatusVisibility

Controls visibility of online/offline status indicator.

avatarHeight

Height for user/group avatars.

avatarWidth

Width for user/group avatars.

avatarPadding

Padding for user/group avatars.

avatarMargin

Margin for user/group avatars.

badgeWidth

Width for unread message badge.

badgeHeight

Height for unread message badge.

badgePadding

Padding for unread message badge.

controllerTag

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

dateBackgroundIsTransparent

Controls whether the date background is transparent.

dateHeight

Height for the conversation date display.

datePadding

Padding for the conversation date display.

dateTimeFormatterCallback

Callback for custom date and time formatting.

dateWidth

Width for the conversation date display.

listItemStyle

Style configuration for list items.

searchContentPadding

Padding for search box content.

searchPadding

Padding for the search box.

statusIndicatorBorderRadius

Border radius for the status indicator.

statusIndicatorHeight

Height for the status indicator.

statusIndicatorWidth

Width for the status indicator.

submitIcon

Custom submit icon for selection mode.

Events

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

Customization Matrix


Users

Display and select from a list of users

Groups

Display and select from a list of groups

Message List

Display messages in a conversation

Theming

Customize the look and feel of components