Skip to main content
CometChatMessageList renders a scrollable list of messages for a conversation with real-time updates for new messages, edits, deletions, reactions, and threaded replies.

Where It Fits

CometChatMessageList is a message display component. It requires either a User or Group object to fetch and render messages. Wire it with CometChatMessageHeader and CometChatMessageComposer to build a complete messaging layout.
activity_chat.xml

Quick Start

Add to your layout XML:
Set a User or Group — this is required:
Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the UI Kit dependency added.
Simply adding the MessageList component to the layout will only display the loading indicator. You must supply a User or Group object to fetch messages.

Filtering

Pass a MessagesRequest.MessagesRequestBuilder to control what loads:

Filter Recipes

Pass the builder object, not the result of .build(). The component calls .build() internally.

Actions and Events

Callback Methods

onThreadRepliesClick

Fires when a user taps a threaded message bubble.

onError

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

onLoad

Fires when the list is successfully fetched and loaded.

onEmpty

Fires when the list is empty after loading.

SDK Events (Real-Time, Automatic)

The component listens to SDK message events internally. No manual setup needed.
Automatic: new messages, edits, deletions, and reactions update the list in real time.

Functionality


Custom View Slots

Header View

Custom view displayed at the top of the message list.
Custom view displayed at the bottom of the message list.

State Views

Text Formatters (Mentions)


Bubble Factory

CometChatMessageList uses a factory-based pattern to render message content. Each message type (text, image, video, etc.) has a corresponding BubbleFactory that creates and binds the bubble view. You can replace existing factories or register new ones for custom message types.

How It Works

When a message is displayed, the list resolves a factory key from the message’s category and type (e.g., message_text, custom_location). If a matching BubbleFactory is registered, it handles view creation and binding. Otherwise, the built-in InternalContentRenderer handles default rendering. A BubbleFactory has two lifecycle phases:
  1. create*View(context) — called once when the ViewHolder is created. The message object is not available at this point.
  2. bind*View(view, message, alignment, ...) — called every time a message is displayed. This is where you populate the view with message data.

Replacing an Existing Bubble Factory

Override how a built-in message type renders by registering a factory with the same category and type:

Adding a New Bubble Factory for Custom Messages

Register a factory for a custom message type that the SDK doesn’t handle by default:

Replacing the Entire Bubble

Override getBubbleView to replace the entire message bubble (including all slots like header, footer, avatar) instead of just the content area:

Bubble Slot Reference

Each BubbleFactory can override individual slots within the bubble:

Bubble Slot View Providers

While BubbleFactory customizes rendering per message type, slot view providers let you override a specific slot across all message types. This is useful when you want consistent customization (e.g., always show a custom avatar or always add a custom footer) regardless of the message type.
Slot view providers take priority over BubbleFactory slot methods. If both are set, the provider wins.
Use BubbleViewProvider — an interface with createView() (called once per ViewHolder) and bindView() (called each time a message binds):
Available provider setters:

Message Options

Message options are the contextual actions shown when a user long-presses a message bubble (e.g., Reply, Copy, Edit, Delete). You can control their visibility, replace the entire options list, or append custom options.

Toggling Default Option Visibility

Each built-in option has a visibility setter. Pass View.VISIBLE or View.GONE:
Available visibility methods (Kotlin XML):

Replacing All Options (setOptions)

Use setOptions to completely replace the default options for a message. Return a list to override, or null to fall back to defaults:
When setOptions returns a non-null list, addOptions is not invoked.

Appending Custom Options (addOptions)

Use addOptions to append additional options after the default ones. This is invoked only when setOptions is not set or returns null:

Conditional Options Per Message

Both setOptions and addOptions receive the BaseMessage, so you can return different options based on message type, sender, or any other condition:

CometChatMessageOption Reference


Style

Define a custom style in themes.xml:
themes.xml
See Component Styling for the full reference.

ViewModel

See ViewModel & Data for state observation and custom repositories.

Next Steps

Message Header

Display user/group info in the toolbar

Message Composer

Rich input for sending messages

Message Template

Customize message bubble structure

Component Styling

Detailed styling reference