Skip to main content

Where It Fits

CometChatConversations is a list component. It renders recent conversations and emits the selected Conversation via setOnItemClick. Wire it to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer to build a standard chat layout.
ChatActivity.kt
On phones, you’d typically use separate Activities instead of a side-by-side layout — see the Conversation List + Message View getting started guide.

Quick Start

Add the component to your layout XML:
layout_activity.xml
Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the cometchat-chat-uikit-android dependency added. To add programmatically in an Activity:
YourActivity.kt
Or in a Fragment:
YourFragment.kt

Filtering Conversations

Pass a ConversationsRequest.ConversationsRequestBuilder to setConversationsRequestBuilder. 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. Refer to ConversationsRequestBuilder for the full builder API.

Actions and Events

Callback Methods

setOnItemClick

Fires when a conversation row is tapped. Primary navigation hook — set the active conversation and render the message view.
YourActivity.kt
What this does: Replaces the default item-click behavior. When a user taps a conversation, your custom lambda executes instead of the built-in navigation.

setOnItemLongClick

Fires when a conversation row is long-pressed. Use for additional actions like delete or select.
YourActivity.kt
What this does: Replaces the default long-press behavior. When a user long-presses a conversation, your custom lambda executes.

setOnBackPressListener

Fires when the user presses the back button in the app bar. Default: navigates to the previous activity.
YourActivity.kt
What this does: Overrides the default back-press navigation. When the user taps the back button, your custom logic runs instead.

setOnSelect

Fires when a conversation is checked/unchecked in multi-select mode. Requires setSelectionMode to be set.
YourActivity.kt
What this does: Registers a callback that fires when the user selects one or more conversations. The callback receives the list of selected Conversation objects.

setOnError

Fires on internal errors (network failure, auth issue, SDK exception).
YourActivity.kt
What this does: Registers an error listener. If the component encounters an error (e.g., network failure), your callback receives the CometChatException.

setOnLoad

Fires when the list is successfully fetched and loaded.
YourActivity.kt
What this does: Registers a callback that fires after the conversation list is fetched and rendered. The callback receives the list of loaded Conversation objects.

setOnEmpty

Fires when the list is empty, enabling custom handling such as showing a placeholder.
YourActivity.kt
What this does: Registers a callback that fires when the conversation list has no items. Use this to show a custom empty-state message or trigger other logic.

setOnSearchClickListener

Fires when the user taps the search icon in the toolbar.
YourActivity.kt
What this does: Overrides the default search icon tap behavior. When the user taps the search icon, your custom logic runs instead.
  • Verify: After setting an action callback, trigger the corresponding user interaction (tap, long-press, back, select, search) and confirm your custom logic executes instead of the default behavior.

Global UI Events

CometChatConversationEvents emits events subscribable from anywhere in the application. Add a listener and remove it when no longer needed.
Add Listener
Remove Listener

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. Manual: deleting a conversation via the SDK directly (not through the component’s context menu) requires emitting CometChatConversationEvents.ccConversationDeleted for the UI to update.

Functionality

Small functional customizations such as toggling visibility of UI elements, setting custom sounds, and configuring selection modes.
  • Verify: After calling a visibility method, confirm the corresponding UI element is shown or hidden. After calling disableSoundForMessages(true), confirm no sound plays on incoming messages.

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 via the ConversationsViewHolderListener pattern (createView + bindView).

setLeadingView

Replace the avatar / left section. Typing-aware avatar example.
What this does: Registers a ConversationsViewHolderListener that provides a custom view for the leading (left) area of each conversation item. createView inflates your layout, and bindView populates it with conversation data.
The following example shows a custom leading view with a chat-dots icon for typing indicators and an avatar with status indicator:
drawable/chat_dots.xml
What this does: Defines a vector drawable of a chat bubble with three dots, used as a typing indicator icon in the custom leading view.
Create a leading_view.xml custom layout:
Inflate and bind with typing indicator tracking:

setTrailingView

Replace the timestamp / badge / right section.
Relative time badge example: Create a custom_tail_view.xml custom layout file:
What this does: Defines a custom trailing view layout with a MaterialCardView containing two TextView elements for displaying the time value and unit (e.g., “5” and “Min ago”).
Inflate and bind with color-coded time badges:

setTitleView

Replace the name / title text.
Inline user status example: Create a custom_title_view.xml layout:
custom_title_view.xml
What this does: Defines a custom title layout with the conversation name and an inline user status message.
What this does: Registers a ConversationsViewHolderListener that provides a custom title view for each conversation item. The example inflates a layout with the conversation name and an inline user status message. For group conversations, the status is hidden.

setSubtitleView

Replace the last message preview text.
Example with last-active timestamp:
What this does: Registers a ConversationsViewHolderListener that provides a custom subtitle view for each conversation item. The example creates a TextView showing the last active timestamp formatted as “dd/MM/yyyy, HH:mm:ss”.

setItemView

Replace the entire list item row.
Example with compact layout:
Create an item_converation_list.xml custom layout file:
What this does: Defines a custom list item layout with a CometChatAvatar, status indicator, conversation name, and date — providing a compact, single-line conversation item design.
Inflate the XML and bind:
What this does: Registers a ConversationsViewHolderListener that replaces the entire list item row. The example inflates a compact layout with an avatar, name, and date — replacing the default multi-line conversation item.

setDateTimeFormatter

Custom date/time formatting for conversation timestamps. Implement the DateTimeFormatterCallback interface to control how each time range is displayed:

setOptions

Replace the long-press context menu entirely. Generic signature:
Example with a custom delete option:

addOptions

Append to the long-press context menu without removing defaults. Generic signature:
Example with archive, pin, and mark-as-read options:

setTextFormatters

Custom text formatters for the conversation subtitle. See the MentionsFormatter Guide for details.
themes.xml

setLoadingView

Sets a custom loading view displayed when data is being fetched.
What this does: Replaces the default loading spinner with your custom layout resource. The custom view displays while conversations are being fetched.

setEmptyView

Configures a custom view displayed when there are no conversations in the list.
What this does: Replaces the default empty state with your custom layout resource. The custom view displays when the conversation list has no items.

setErrorView

Defines a custom error state view that appears when an issue occurs while loading conversations.
What this does: Replaces the default error state with your custom layout resource. The custom view displays when the component encounters an error during data fetching.

setDateFormat

Customizes the date format used for displaying timestamps in conversations. Generic signature:
Example:
What this does: Sets the conversation date format to “dd MMM, hh:mm a” (e.g., “10 Jul, 02:30 PM”) using the device’s default locale.

setOverflowMenu

Replace the toolbar overflow menu. Generic signature:
Example with a user profile popup menu:
Create a user_profile_popup_menu_layout.xml custom view file:
user_profile_popup_menu_layout.xml
What this does: Defines a popup menu layout with options for creating a conversation, viewing the user profile, logging out, and displaying the app version.
Inflate the view and pass it to setOverflowMenu:
What this does: Creates a complete overflow menu implementation. An avatar of the logged-in user is set as the overflow menu view. When tapped, it shows a popup window with options for creating a conversation, viewing the user profile, logging out, and displaying the app version.
  • Verify: After setting any custom view slot, confirm the custom view renders in the correct position within the conversation list item, and the data binding populates correctly for each conversation.

Common Patterns

Custom empty state with action button

layout/empty_conversations.xml

Hide all chrome — minimal list

Filter to user conversations only

Advanced Methods

Programmatic Selection

selectConversation

Programmatically selects or deselects a conversation. Works with both SINGLE and MULTIPLE selection modes.
In SINGLE mode, selecting a new conversation replaces the previous selection. In MULTIPLE mode, calling this on an already-selected conversation deselects it (toggle behavior).

clearSelection

Clears all selected conversations and resets the selection UI.

getSelectedConversations

Returns the list of currently selected Conversation objects.

Selected Conversations List

When using multi-select mode, a horizontal list of selected conversations can be shown above the main list.

Search Input Customization

The built-in search box can be customized programmatically:

Internal Access

These methods provide direct access to internal components for advanced use cases.
Use these only when the standard API is insufficient. Directly manipulating the adapter or ViewModel may conflict with the component’s internal state management.

Other Methods

Style

The component uses XML theme styles. Define a custom style with parent CometChatConversationsStyle in themes.xml, then apply with setStyle().
themes.xml
To know more such attributes, visit the attributes file.

Programmatic Style Properties

In addition to XML theme styles, the component exposes programmatic setters for fine-grained control:

Checkbox Style Properties (Selection Mode)

When using SINGLE or MULTIPLE selection mode, checkboxes appear on each item:

Customization Matrix

Next Steps

Users

Browse and search available users

Groups

Browse and search available groups

Message List

Display messages in a conversation

Message Composer

Rich input for sending messages