Users - CometChat Docs

CometChatUsers displays an accessible list of all available users, with built-in search, avatars, names, and online/offline status indicators.

When to use this

You need a screen that lists all available users in your app.
You want to show each user’s name, avatar, and online/offline status.
You need tap and long-press actions on user items (open profile, block, mute).
You want to filter users by status, role, tags, friends-only, or custom request builders.
You need real-time updates when users are blocked or unblocked.
You want to customize the user list appearance with styles, custom views, or selection modes.

Prerequisites

CometChat SDK initialized with CometChatUIKit.init() and a user logged in.
The cometchat-chat-uikit-android dependency added to your project.
A valid layout.xml or Activity/Fragment where you will place the component.

Quick start

Open your layout XML file.
Add the CometChatUsers XML element:

layout.xml

<com.cometchat.chatuikit.users.CometChatUsers
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:id="@+id/users"
        />

What this does: Adds the CometChatUsers component to your layout. It fills the available width and height and renders the user list for the logged-in user.

Build and run your app.
Verify that the user list appears with avatars, names, and online/offline status indicators.

If you need to add the component programmatically, see the Implementation section for actions, filters, events, and advanced views.

Core concepts

CometChatUsers: The main component class that renders the user list. It can be added via XML layout.
Actions: Callbacks such as setOnItemClick, setOnItemLongClick, setOnBackPressListener, setOnSelect, setOnError, setOnLoad, and setOnEmpty that let you respond to user interactions.
Filters: Use UsersRequest.UsersRequestBuilder to filter users by limit, search keyword, friends-only, roles, tags, status, or UIDs. Use setSearchRequestBuilder to customize the search list separately.
Events: Global events emitted via CometChatUserEvents (e.g., ccUserBlocked, ccUserUnblocked) that you can listen to from anywhere in your app.
Style: XML theme styles (parent CometChatUsersStyle) applied via setStyle() to customize colors, fonts, and sub-component styles.
Advanced views: Methods like setLeadingView, setTitleView, setTrailingView, setItemView, setSubtitleView, and setOverflowMenu that let you replace default UI elements with custom layouts.

Implementation

Actions

What you’re changing: How the component responds to user interactions such as taps, long-presses, back button, selection, errors, load completion, and empty states.

Where: Activity or Fragment where you hold a reference to CometChatUsers (e.g., cometchatUsers).
Applies to: CometChatUsers.
Default behavior: Predefined actions execute automatically (e.g., tapping a user opens the chat, pressing back navigates to the previous screen).
Override: Call the corresponding setter method to replace the default behavior with your own logic.

`setOnItemClick`

Function invoked when a user item is clicked, used to open a user profile or chat screen.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnItemClick((view1, position, user) -> {
            
    });

YourActivity.kt

cometchatUsers.onItemClick = OnItemClick { view, position, user ->
            
    }

What this does: Replaces the default item-click behavior. When a user taps a user item, your custom lambda executes instead of the built-in navigation.

`setOnItemLongClick`

Function executed when a user item is long-pressed, allowing additional actions like delete or block.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnItemLongClick((view1, position, user) -> {

    });

YourActivity.kt

cometchatUsers.onItemLongClick = OnItemLongClick({ view, position, user ->
            
    })

What this does: Replaces the default long-press behavior. When a user long-presses a user item, your custom lambda executes.

`setOnBackPressListener`

Triggered when the user presses the back button in the app bar. By default, it navigates to the previous activity.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnBackPressListener(() -> {
            
    });

YourActivity.kt

cometchatUsers.onBackPressListener = OnBackPress {

    }

What this does: Overrides the default back-press navigation. When the user taps the back button, your custom logic runs instead.

`setOnSelect`

Called when an item from the fetched list is selected, useful for multi-selection features.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnSelect(t -> {

    });

YourActivity.kt

cometchatUsers.setOnSelect(object : OnSelection<User?> {
        override fun onSelection(t: MutableList<User?>?) {
                
        }
    })

What this does: Registers a callback that fires when the user selects one or more users. The callback receives the list of selected User objects.

`setOnError`

Listens for any errors that occur in the Users component. This does not change the component’s behavior.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnError(cometchatException -> {

    });

YourActivity.kt

cometchatUsers.setOnError {

    }

What this does: Registers an error listener. If the component encounters an error (e.g., network failure), your callback receives the CometChatException.

`setOnLoad`

Invoked when the list is successfully fetched and loaded, helping track component readiness.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnLoad(list -> {

});

YourActivity.kt

cometchatUsers.setOnLoad(object : OnLoad<User?> {
    override fun onLoad(list: MutableList<User?>?) {

    }
})

What this does: Registers a callback that fires after the user list is fetched and rendered. The callback receives the list of loaded User objects.

`setOnEmpty`

Called when the list is empty, enabling custom handling such as showing a placeholder message.

Java
Kotlin

YourActivity.java

cometchatUsers.setOnEmpty(() -> {
            
    });

YourActivity.kt

cometchatUsers.setOnEmpty{
            
    }

What this does: Registers a callback that fires when the user list has no items. Use this to show a custom empty-state message or trigger other logic.

Verify: After setting an action callback, trigger the corresponding user interaction (tap, long-press, back, select) and confirm your custom logic executes instead of the default behavior.

Filters

What you’re changing: Which users appear in the list.

Where: Activity or Fragment where you hold a reference to CometChatUsers.
Applies to: CometChatUsers.
Default behavior: All users are fetched and displayed.
Override: Create a UsersRequest.UsersRequestBuilder, configure it, and pass it to setUsersRequestBuilder.

`UsersRequestBuilder`

The UsersRequestBuilder enables you to filter and customize the user list based on available parameters. The following parameters are available:

Methods	Type	Description
`setLimit`	int	Sets the number of users that can be fetched in a single request, suitable for pagination
`setSearchKeyword`	String	Used for fetching users matching the passed string
`hideBlockedUsers`	bool	Used for fetching all those users who are not blocked by the logged in user
`friendsOnly`	bool	Used for fetching only those users in which logged in user is a member
`setRoles`	List<String>	Used for fetching users containing the passed tags
`setTags`	List<String>	Used for fetching users containing the passed tags
`withTags`	bool	Used for fetching users containing tags
`setUserStatus`	String	Used for fetching users by their status online or offline
`setUIDs`	List<String>	Used for fetching users containing the passed users

Code:

Java
Kotlin

UsersRequest.UsersRequestBuilder builder=new UsersRequest.UsersRequestBuilder()
                .friendsOnly(false)
                        .setLimit(10);
cometChatUsers.setUsersRequestBuilder(builder);

val builder = UsersRequest.UsersRequestBuilder()
            .friendsOnly(false)
            .setLimit(10)
cometChatUsers.setUsersRequestBuilder(builder)

What this does: Creates a UsersRequestBuilder that fetches all users (not friends-only) with a limit of 10 per fetch. The builder is then applied to the CometChatUsers component.

Verify: The user list shows all users (not filtered to friends) and fetches at most 10 items per request.

`SearchRequestBuilder`

The SearchRequestBuilder uses UsersRequestBuilder to filter and customize the search list based on available parameters. This keeps uniformity between the displayed user list and searched user list.

Code:

Java
Kotlin

UsersRequest.UsersRequestBuilder builder = new UsersRequest.UsersRequestBuilder()
        .setSearchKeyword("**");
users.setSearchRequestBuilder(builder);

val builder = UsersRequest.UsersRequestBuilder()
    .setSearchKeyword("**")
users.searchRequestBuilder = builder

What this does: Creates a UsersRequestBuilder configured with a search keyword and applies it as the search request builder. This controls how the search results are filtered when the user types in the search bar.

Verify: When searching in the user list, the search results are filtered according to the configured SearchRequestBuilder parameters.

Events

What you’re changing: How your app reacts to global events emitted by the Users component.

Where: Any Activity, Fragment, or class where you want to listen for user events.
Applies to: CometChatUserEvents.
Default behavior: No external listeners are registered. Events are emitted but not handled outside the component.
Override: Add a listener using CometChatUserEvents.addUserListener and remove it when no longer needed using CometChatUserEvents.removeListener.

The following events are available:

Events	Description
`ccUserBlocked`	This will get triggered when the logged in user blocks another user
`ccUserUnblocked`	This will get triggered when the logged in user unblocks another user

Code:

Java
Kotlin

CometChatUserEvents.addUserListener("LISTENER_TAG", new CometChatUserEvents() {
            @Override
            public void ccUserBlocked(User user) {
                super.ccUserBlocked(user);
            }

            @Override
            public void ccUserUnblocked(User user) {
                super.ccUserUnblocked(user);
            }
        });

Remove Listener

CometChatUserEvents.removeListener("YOUR_LISTENER_TAG");

CometChatUserEvents.addUserListener("LISTENER_TAG", object : CometChatUserEvents() {
            override fun ccUserBlocked(user: User?) {
                super.ccUserBlocked(user)
            }

            override fun ccUserUnblocked(user: User?) {
                super.ccUserUnblocked(user)
            }
        })

Remove Listener

 CometChatUserEvents.removeListener("LISTENER_TAG");

What this does: Registers a global event listener tagged with your identifier. When a user is blocked, the ccUserBlocked callback fires with the blocked User object. When a user is unblocked, the ccUserUnblocked callback fires. Call removeListener with the same tag to unsubscribe.

Verify: Block a user in the UI and confirm your ccUserBlocked callback fires with the correct User object. Unblock a user and confirm ccUserUnblocked fires.

Style

What you’re changing: The visual appearance of the Users component using XML theme styles.

Where: themes.xml for style definitions, and your Activity/Fragment for applying the style.
Applies to: CometChatUsers.
Default behavior: The component uses the default CometChatUsersStyle.
Override: Define a custom style with parent CometChatUsersStyle in themes.xml, then call setStyle() on the component.

Code:

themes.xml

    <style name="CustomAvatarStyle" parent="CometChatAvatarStyle">
        <item name="cometchatAvatarStrokeRadius">8dp</item>
        <item name="cometchatAvatarBackgroundColor">#FBAA75</item>
    </style>
    <style name="CustomUsersStyle" parent="CometChatUsersStyle">
        <item name="cometchatUsersAvatarStyle">@style/CustomAvatarStyle</item>
        <item name="cometchatUsersSeparatorColor">#F76808</item>
        <item name="cometchatUsersTitleTextColor">#F76808</item>
    </style>

What this does: Defines two custom styles: CustomAvatarStyle sets the avatar corner radius to 8dp and background color to #FBAA75; CustomUsersStyle applies the avatar sub-style and sets the separator and title text colors to #F76808.

Java
Kotlin

cometChatUsers.setStyle(R.style.CustomUsersStyle);

cometChatUsers.setStyle(R.style.CustomUsersStyle)

What this does: Applies the CustomUsersStyle theme to the CometChatUsers component, changing the avatar, separator, and title text appearance.

To know more such attributes, visit the attributes file.

Verify: The user list avatars display with rounded corners (8dp radius) and an orange background (#FBAA75), separators show in orange (#F76808), and title text appears in orange (#F76808).

Functionality

What you’re changing: Small functional customizations such as toggling visibility of UI elements and configuring selection modes.

Where: Activity or Fragment where you hold a reference to CometChatUsers.
Applies to: CometChatUsers.
Default behavior: All UI elements are visible with default settings.
Override: Call the corresponding method on the component instance.

Methods	Description	Code
`setBackIconVisibility`	Toggles visibility for the back button in the app bar	`.setBackIconVisibility(View.VISIBLE);`
`setToolbarVisibility`	Toggles visibility for the toolbar in the app bar	`.setToolbarVisibility(View.GONE);`
`setStickyHeaderVisibility`	Toggles visibility for the sticky header in the list	`.setStickyHeaderVisibility(View.GONE);`
`setErrorStateVisibility`	Hides the error state on fetching users	`.setErrorStateVisibility(View.GONE);`
`setEmptyStateVisibility`	Hides the empty state on fetching users	`.setEmptyStateVisibility(View.GONE);`
`setLoadingStateVisibility`	Hides the loading state while fetching users	`.setLoadingStateVisibility(View.GONE);`
`setSeparatorVisibility`	Controls visibility of separators in the list view	`.setSeparatorVisibility(View.GONE);`
`setUsersStatusVisibility`	Controls visibility of the online status indicator	`.setUsersStatusVisibility(View.GONE);`
`setSelectionMode`	Determines the selection mode (single or multiple)	`.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE);`
`setSearchkeyword`	Used for fetching users matching the passed keywords	`.setSearchkeyword("anything");`
`setSearchBoxVisibility`	Hides the search box shown in the toolbar	`.setSearchBoxVisibility(View.GONE);`

Verify: After calling a visibility method, confirm the corresponding UI element is shown or hidden. After calling setSelectionMode, confirm the selection behavior matches the mode.

Advanced views

What you’re changing: The default UI elements of user list items and the component’s chrome (loading, empty, error states, overflow menu, options).

Where: Activity or Fragment where you hold a reference to CometChatUsers.
Applies to: CometChatUsers.
Default behavior: The component renders its built-in views for each part of the user item and component chrome.
Override: Call the corresponding setter method and provide a custom view or callback.

`setOptions`

Sets a predefined list of actions that users can perform when they long press a user in the list. This replaces the default options entirely.

Java
Kotlin

cometchatUsers.setOptions((context, user) -> Collections.emptyList());

cometchatUsers.options = Function2<Context?, User?, List<CometChatPopupMenu.MenuItem?>?> { context, user -> emptyList<CometChatPopupMenu.MenuItem?>() }

What this does: Replaces the default long-press options with an empty list, effectively removing all long-press menu items.

`addOptions`

Extends the existing set of long-press actions without removing the default ones.

Java
Kotlin

cometchatUsers.addOptions((context, user) -> Collections.emptyList());

cometchatUsers.addOptions { context, user -> emptyList<CometChatPopupMenu.MenuItem?>() }

What this does: Appends an empty list to the existing long-press options, leaving the defaults unchanged. Replace the empty list with your custom MenuItem objects to add new actions.

`setLoadingView`

Sets a custom loading view displayed when data is being fetched.

Java
Kotlin

cometchatUsers.setLoadingView(R.layout.your_loading_view);

cometchatUsers.loadingView = R.layout.your_loading_view

What this does: Replaces the default loading spinner with your custom layout resource. The custom view displays while users are being fetched.

`setEmptyView`

Configures a custom view displayed when there are no users in the list.

Java
Kotlin

cometchatUsers.setEmptyView(R.layout.your_empty_view);

cometchatUsers.emptyView = R.layout.your_empty_view

What this does: Replaces the default empty state with your custom layout resource. The custom view displays when the user list has no items.

`setErrorView`

Defines a custom error state view that appears when an issue occurs while loading users.

Java
Kotlin

cometchatUsers.setErrorView(R.layout.your_empty_view);

cometchatUsers.errorView = R.layout.your_error_view

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.

`setLeadingView`

Sets a custom leading view element that appears at the beginning of each user item (e.g., profile pictures, avatars, or user badges).

Java
Kotlin

cometchatUsers.setLeadingView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return null;
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {

            }
        });

cometchatUsers.setLeadingView(object: UsersViewHolderListener {
    override fun createView(context: Context, cometChatListItem: CometChatListItem): View? {
        return null
    }

    override fun bindView(context: Context, view: View, user: User, viewHolder: RecyclerView.ViewHolder, list: List<User>, i: Int) {
    }
})

What this does: Registers a UsersViewHolderListener that provides a custom view for the leading (left) area of each user item. createView inflates your layout, and bindView populates it with user data.

`setTitleView`

Customizes the title view of each user item, which displays the user’s name. It allows for styling modifications, additional metadata, or inline action buttons.

Java
Kotlin

cometchatUsers.setTitleView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return null;
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {

            }
        });

cometchatUsers.setTitleView(object: UsersViewHolderListener {
    override fun createView(context: Context, cometChatListItem: CometChatListItem): View? {
        return null
    }

    override fun bindView(context: Context, view: View, user: User, viewHolder: RecyclerView.ViewHolder, list: List<User>, i: Int) {
    }
})

What this does: Registers a UsersViewHolderListener that provides a custom view for the title area of each user item. createView inflates your layout, and bindView populates it with user data.

Create a custom layout file named custom_user_title_view.xml:

custom_user_title_view.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/user_layout"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:gravity="center_vertical"
    android:orientation="horizontal">

    <TextView
        android:id="@+id/title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_weight="1"
        android:text="teacher"
        android:textAppearance="?attr/cometchatTextAppearanceHeading4Medium" />

    <View
        android:id="@+id/role"
        android:layout_width="50dp"
        android:layout_height="15dp"
        android:layout_marginStart="@dimen/cometchat_16dp"
        android:background="@drawable/teacher" />

</LinearLayout>

What this does: Defines a custom title view layout with a TextView for the user name and a View for a role badge indicator. The role badge displays a drawable based on the user’s role.

Inflate the layout inside createView() and use bindView() to initialize and assign values based on the User object:

Java
Kotlin

cometchatUsers.setTitleView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return LayoutInflater.from(context).inflate(R.layout.custom_user_title_view, null);
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {
                LinearLayout layout = createdView.findViewById(R.id.user_layout);
                LinearLayout.LayoutParams layoutParams = new LinearLayout.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT,
                                                                                       ViewGroup.LayoutParams.WRAP_CONTENT);
                layout.setLayoutParams(layoutParams);
                TextView name = createdView.findViewById(R.id.title);
                name.setText(user.getName());
                View role = createdView.findViewById(R.id.role);
                if ("teacher".equals(user.getRole())) {
                    role.setVisibility(View.VISIBLE);
                    role.setBackground(ResourcesCompat.getDrawable(getResources(), R.drawable.teacher, null));
                } else if ("student".equals(user.getRole())) {
                    role.setVisibility(View.VISIBLE);
                    role.setBackground(ResourcesCompat.getDrawable(getResources(), R.drawable.student, null));
                } else if ("close_friend".equals(user.getRole())) {
                    role.setVisibility(View.VISIBLE);
                    role.setBackground(ResourcesCompat.getDrawable(getResources(), R.drawable.close_friend, null));
                } else {
                    role.setVisibility(View.GONE);
                }

            }
        });

cometchatUsers.setTitleView(object : UsersViewHolderListener() {
            override fun createView(context: Context?, listItem: CometchatListBaseItemsBinding?): View {
                return LayoutInflater.from(context).inflate(R.layout.custom_user_title_view, null)
            }

            override fun bindView(
                context: Context,
                createdView: View,
                user: User,
                holder: RecyclerView.ViewHolder,
                userList: List<User>,
                position: Int
            ) {
                val layout = createdView.findViewById<LinearLayout>(R.id.user_layout)
                val layoutParams = LinearLayout.LayoutParams(
                    ViewGroup.LayoutParams.WRAP_CONTENT,
                    ViewGroup.LayoutParams.WRAP_CONTENT
                )
                layout.layoutParams = layoutParams
                val name = createdView.findViewById<TextView>(R.id.title)
                name.text = user.name
                val role = createdView.findViewById<View>(R.id.role)
                if ("teacher" == user.role) {
                    role.visibility = View.VISIBLE
                    role.background = ResourcesCompat.getDrawable(resources, R.drawable.teacher, null)
                } else if ("student" == user.role) {
                    role.visibility = View.VISIBLE
                    role.background = ResourcesCompat.getDrawable(resources, R.drawable.student, null)
                } else if ("close_friend" == user.role) {
                    role.visibility = View.VISIBLE
                    role.background = ResourcesCompat.getDrawable(resources, R.drawable.close_friend, null)
                } else {
                    role.visibility = View.GONE
                }
            }
        })

What this does: Inflates the custom title view layout and populates it with the user’s name. If the user’s role is “teacher”, “student”, or “close_friend”, the corresponding role badge drawable is shown. If the role does not match any of these, the badge is hidden.

`setTrailingView`

Customizes the trailing (right-end) section of each user item, used for actions like buttons, icons, or extra information.

Java
Kotlin

cometchatUsers.setTrailingView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return null;
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {

            }
        });

cometchatUsers.setTrailingView(object: UsersViewHolderListener {
    override fun createView(context: Context, cometChatListItem: CometChatListItem): View? {
        return null
    }

    override fun bindView(context: Context, view: View, user: User, viewHolder: RecyclerView.ViewHolder, list: List<User>, i: Int) {
    }
})

What this does: Registers a UsersViewHolderListener that provides a custom view for the trailing (right) area of each user item. createView inflates your layout, and bindView populates it with user data.

Create a custom layout file named custom_user_tail_view.xml:

custom_user_tail_view.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:gravity="center_vertical"
    android:orientation="horizontal">

    <View
        android:id="@+id/tag"
        android:layout_width="50dp"
        android:layout_height="15dp"
        android:layout_marginStart="@dimen/cometchat_16dp"
        android:background="@drawable/teacher" />

</LinearLayout>

What this does: Defines a custom trailing view layout with a View element for displaying a tag badge based on the user’s role.

Inflate the layout inside createView() and use bindView() to initialize and assign values based on the User object:

Java
Kotlin

cometchatUsers.setTrailingView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return LayoutInflater.from(context).inflate(R.layout.custom_user_tail_view, null);
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {
                View role = createdView.findViewById(R.id.tag);
                if ("pro".equals(user.getRole())) {
                    role.setVisibility(View.VISIBLE);
                    role.setBackground(ResourcesCompat.getDrawable(getResources(), R.drawable.teacher, null));
                } else {
                    role.setVisibility(View.GONE);
                }
            }
        });

cometchatUsers.setTrailingView(object : UsersViewHolderListener() {
            override fun createView(context: Context?, listItem: CometchatListBaseItemsBinding?): View {
                return LayoutInflater.from(context).inflate(R.layout.custom_user_tail_view, null)
            }

            override fun bindView(
                context: Context,
                createdView: View,
                user: User,
                holder: RecyclerView.ViewHolder,
                userList: List<User>,
                position: Int
            ) {
                val role = createdView.findViewById<View>(R.id.tag)
                if ("pro" == user.role) {
                    role.visibility = View.VISIBLE
                    role.background = ResourcesCompat.getDrawable(resources, R.drawable.teacher, null)
                } else {
                    role.visibility = View.GONE
                }
            }
        })

What this does: Inflates the custom trailing view layout and checks the user’s role. If the role is “pro”, the tag badge is shown with the teacher drawable. If the role does not match, the badge is hidden.

`setItemView`

Assigns a completely custom list item design to the Users component, replacing the default layout entirely.

Java
Kotlin

 cometchatUsers.seItemView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return null;
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {

            }
        });

cometchatUsers.setItemView(object: UsersViewHolderListener {
    override fun createView(context: Context, cometChatListItem: CometChatListItem): View? {
        return null
    }

    override fun bindView(context: Context, view: View, user: User, viewHolder: RecyclerView.ViewHolder, list: List<User>, i: Int) {
    }
})

What this does: Registers a UsersViewHolderListener that replaces the entire default user list item layout. createView inflates your custom layout, and bindView populates it with user data.

Create a custom layout file named custom_list_item_view.xml:

custom_list_item_view.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/parent_lay"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginStart="@dimen/cometchat_padding_4"
        android:layout_marginTop="@dimen/cometchat_padding_3"
        android:layout_marginEnd="@dimen/cometchat_padding_4"
        android:layout_marginBottom="@dimen/cometchat_padding_3"
        android:gravity="center_vertical"
        android:orientation="horizontal">

        <androidx.constraintlayout.widget.ConstraintLayout
            android:id="@+id/leading_view"
            android:layout_width="@dimen/cometchat_45dp"
            android:layout_height="@dimen/cometchat_45dp">

            <com.cometchat.chatuikit.shared.views.cometchatavatar.CometChatAvatar
                android:id="@+id/custom_avatar"
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                app:cometchatAvatarPlaceHolderTextAppearance="@style/CometChatTextAppearanceHeading4.Bold"
                app:cometchatAvatarStrokeRadius="@dimen/cometchat_8dp" />

        </androidx.constraintlayout.widget.ConstraintLayout>

        <TextView
            android:id="@+id/tvName"
            android:layout_width="0dp"
            android:layout_height="wrap_content"
            android:layout_marginStart="@dimen/cometchat_margin_3"
            android:layout_weight="1"
            android:textAppearance="@style/CometChatTextAppearanceHeading4.Medium" />

    </LinearLayout>

    <View
        android:layout_width="match_parent"
        android:layout_height="1dp"
        android:background="?attr/cometchatStrokeColorLight" />

</LinearLayout>

What this does: Defines a custom list item layout with a CometChatAvatar and a TextView for the user name, separated by a thin divider line at the bottom.

Inflate the layout inside createView() and use bindView() to initialize and assign values based on the User object:

Java
Kotlin

YourActivity.java

binding.users.setListItemView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return LayoutInflater.from(context).inflate(R.layout.custom_list_item_view, null, false);
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {
                CometChatAvatar avatar = createdView.findViewById(R.id.custom_avatar);
                TextView title = createdView.findViewById(R.id.tvName);
                LinearLayout parentLayout = createdView.findViewById(R.id.parent_lay);
                String name = user.getName();
                title.setText(name);
                avatar.setStyle(com.cometchat.chatuikit.R.style.CometChatAvatarStyle);
                avatar.setAvatarPlaceHolderTextAppearance(com.cometchat.chatuikit.R.style.CometChatTextAppearanceHeading4_Bold);
                avatar.setAvatar(name,user.getAvatar());
                if(user.getStatus().equals(UIKitConstants.UserStatus.ONLINE)) {
                    parentLayout.setBackgroundColor(Color.parseColor("#E6F4ED"));
                } else {
                    parentLayout.setBackgroundColor(Color.parseColor("#00000000"));
                }

            }
        });

YourActivity.kt

users.setListItemView(object : UsersViewHolderListener() {
            override fun createView(
                context: Context?,
                listItem: CometchatListBaseItemsBinding?
            ): View {
                return LayoutInflater.from(context)
                    .inflate(R.layout.custom_list_item_view, null, false)
            }

            override fun bindView(
                context: Context,
                createdView: View,
                user: User,
                holder: RecyclerView.ViewHolder,
                userList: List<User>,
                position: Int
            ) {
                val avatar = createdView.findViewById<CometChatAvatar>(R.id.custom_avatar)
                val title = createdView.findViewById<TextView>(R.id.tvName)
                val parentLayout = createdView.findViewById<LinearLayout>(R.id.parent_lay)
                val name = user.name
                title.text = name
                avatar.setStyle(com.cometchat.chatuikit.R.style.CometChatAvatarStyle)
                avatar.avatarPlaceHolderTextAppearance =
                    com.cometchat.chatuikit.R.style.CometChatTextAppearanceHeading4_Bold
                avatar.setAvatar(name, user.avatar)
                if (user.status == UIKitConstants.UserStatus.ONLINE) {
                    parentLayout.setBackgroundColor(Color.parseColor("#E6F4ED"))
                } else {
                    parentLayout.setBackgroundColor(Color.parseColor("#00000000"))
                }
            }
        })

What this does: Inflates a custom list item layout and populates it with the user’s avatar and name. If the user’s status is ONLINE, the parent layout background is set to a light green (#E6F4ED). If the user is offline, the background is transparent.

`setSubtitleView`

Customizes the subtitle view of each user item, shown below the user’s name. It can display additional details such as user status or last active time.

Java
Kotlin

cometChatUsers.setSubtitleView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return null;
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {

            }
        });

cometChatUsers.setSubtitleView(object : UsersViewHolderListener() {
            override fun createView(
                context: Context?,
                listItem: CometchatListBaseItemsBinding?
            ): View? {
                return null
            }

            override fun bindView(
                context: Context,
                createdView: View,
                user: User,
                holder: RecyclerView.ViewHolder,
                userList: List<User>,
                position: Int
            ) {
            }
        })

What this does: Registers a UsersViewHolderListener that provides a custom subtitle view for each user item. createView inflates your layout, and bindView populates it with user data.

The following example shows a custom subtitle view that displays the user’s last active time:

Java
Kotlin

cometChatUsers.setSubtitleView(new UsersViewHolderListener() {
            @Override
            public View createView(Context context, CometchatListBaseItemsBinding listItem) {
                return new TextView(context);
            }

            @Override
            public void bindView(Context context, View createdView, User user, RecyclerView.ViewHolder holder, List<User> userList, int position) {
                TextView tvSubtitle = (TextView) createdView;
                tvSubtitle.setText("Last Active at: "+new SimpleDateFormat("dd/mm/yyyy, HH:MM:SS").format(user.getLastActiveAt() * 1000));
                tvSubtitle.setTextColor(Color.BLACK);
            }
        });

cometChatUsers.setSubtitleView(object : UsersViewHolderListener() {
            override fun createView(
                context: Context?,
                listItem: CometchatListBaseItemsBinding?
            ): View {
                return TextView(context)
            }

            override fun bindView(
                context: Context,
                createdView: View,
                user: User,
                holder: RecyclerView.ViewHolder,
                userList: List<User>,
                position: Int
            ) {
                val tvSubtitle = createdView as TextView
                tvSubtitle.text =
                    "Last Active at: " + SimpleDateFormat("dd/mm/yyyy, HH:MM:SS").format(user.lastActiveAt * 1000)
                tvSubtitle.setTextColor(Color.BLACK)
            }
        })

What this does: Replaces the default subtitle with a custom TextView that shows “Last Active at:” followed by the user’s last active timestamp formatted as “dd/mm/yyyy, HH:MM:SS” in black text.

`setOverflowMenu`

Customizes the overflow menu within the Users component. This menu appears as a three-dot (⋮) icon and provides additional options.

Java
Kotlin

users.setOverflowMenu(v);

users.setOverflowMenu(v)

What this does: Sets a custom View as the overflow menu in the users toolbar. Pass any view (e.g., an icon button, image) to replace the default overflow menu.

Java
Kotlin

    ImageView imageView = new ImageView(requireContext());
    imageView.setImageResource(R.drawable.ic_user_menu);
    users.setOverflowMenu(imageView);

    val imageView = ImageView(requireContext())
    imageView.setImageResource(android.R.drawable.ic_user_menu)
    users.setOverflowMenu(imageView)

What this does: Creates an ImageView with a custom menu icon and sets it as the overflow menu in the users toolbar. The icon appears in the toolbar’s overflow position.

Verify: After setting any advanced view, confirm the custom view renders in the correct position within the user list item, and the data binding populates correctly for each user.

Customization matrix

What you want to change	Where	Property/API	Example
Avatar style (corner radius, background)	`themes.xml`	`CometChatUsersStyle` with `cometchatUsersAvatarStyle`	`<item name="cometchatAvatarStrokeRadius">8dp</item>`
Separator color	`themes.xml`	`CometChatUsersStyle` with `cometchatUsersSeparatorColor`	`<item name="cometchatUsersSeparatorColor">#F76808</item>`
Title text color	`themes.xml`	`CometChatUsersStyle` with `cometchatUsersTitleTextColor`	`<item name="cometchatUsersTitleTextColor">#F76808</item>`
Apply a custom style	Activity/Fragment	`setStyle(int styleRes)`	`cometChatUsers.setStyle(R.style.CustomUsersStyle);`
Back button visibility	Activity/Fragment	`setBackIconVisibility(int)`	`.setBackIconVisibility(View.VISIBLE);`
Toolbar visibility	Activity/Fragment	`setToolbarVisibility(int)`	`.setToolbarVisibility(View.GONE);`
Sticky header visibility	Activity/Fragment	`setStickyHeaderVisibility(int)`	`.setStickyHeaderVisibility(View.GONE);`
Error state visibility	Activity/Fragment	`setErrorStateVisibility(int)`	`.setErrorStateVisibility(View.GONE);`
Empty state visibility	Activity/Fragment	`setEmptyStateVisibility(int)`	`.setEmptyStateVisibility(View.GONE);`
Loading state visibility	Activity/Fragment	`setLoadingStateVisibility(int)`	`.setLoadingStateVisibility(View.GONE);`
Separator visibility	Activity/Fragment	`setSeparatorVisibility(int)`	`.setSeparatorVisibility(View.GONE);`
User online status visibility	Activity/Fragment	`setUsersStatusVisibility(int)`	`.setUsersStatusVisibility(View.GONE);`
Selection mode (single/multiple)	Activity/Fragment	`setSelectionMode(SelectionMode)`	`.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE);`
Search keyword	Activity/Fragment	`setSearchkeyword(String)`	`.setSearchkeyword("anything");`
Search box visibility	Activity/Fragment	`setSearchBoxVisibility(int)`	`.setSearchBoxVisibility(View.GONE);`
Long-press options (replace)	Activity/Fragment	`setOptions(Function2)`	See `setOptions` code above
Long-press options (append)	Activity/Fragment	`addOptions(Function2)`	See `addOptions` code above
Loading view	Activity/Fragment	`setLoadingView(int)`	`cometchatUsers.setLoadingView(R.layout.your_loading_view);`
Empty view	Activity/Fragment	`setEmptyView(int)`	`cometchatUsers.setEmptyView(R.layout.your_empty_view);`
Error view	Activity/Fragment	`setErrorView(int)`	`cometchatUsers.setErrorView(R.layout.your_empty_view);`
Leading view (avatar area)	Activity/Fragment	`setLeadingView(UsersViewHolderListener)`	See `setLeadingView` code above
Title view	Activity/Fragment	`setTitleView(UsersViewHolderListener)`	See `setTitleView` code above
Trailing view	Activity/Fragment	`setTrailingView(UsersViewHolderListener)`	See `setTrailingView` code above
Entire list item	Activity/Fragment	`setItemView(UsersViewHolderListener)` / `setListItemView(UsersViewHolderListener)`	See `setItemView` code above
Subtitle view	Activity/Fragment	`setSubtitleView(UsersViewHolderListener)`	See `setSubtitleView` code above
Overflow menu	Activity/Fragment	`setOverflowMenu(View)`	`users.setOverflowMenu(imageView);`
Filter users	Activity/Fragment	`setUsersRequestBuilder(UsersRequestBuilder)`	See Filters code above
Search filter	Activity/Fragment	`setSearchRequestBuilder(UsersRequestBuilder)`	See SearchRequestBuilder code above

Common pitfalls & fixes

Pitfall	Fix
Component does not render	Ensure `CometChatUIKit.init()` is called and awaited before using any UI Kit component. If `init()` has not completed, the component will not load data.
User list is empty despite having users	Verify that a user is logged in with `CometChatUIKit.login()` before displaying the component. The component fetches users for the logged-in user only.
Filters not applied	Ensure you call `setUsersRequestBuilder(builder)` on the `CometChatUsers` instance after creating and configuring the builder.
Custom style not visible	Verify the style parent is `CometChatUsersStyle` and that you call `setStyle(R.style.YourStyle)` on the component instance.
`setOnItemClick` not firing	If you set `setSelectionMode` to `MULTIPLE`, item clicks may be consumed by the selection logic. Set the selection mode to `NONE` if you need standard click behavior.
Event listener not receiving events	Ensure you call `CometChatUserEvents.addUserListener` with a unique tag. If you use the same tag as another listener, the previous one is replaced.
Search not working with custom filter	If you set a `UsersRequestBuilder` via `setUsersRequestBuilder`, the search may use different parameters. Use `setSearchRequestBuilder` to control search behavior separately.
Custom view returns null in `createView`	If `createView` returns `null`, the default view is used. Return a valid inflated `View` to replace the default.
Sticky header not showing	Ensure `setStickyHeaderVisibility` is set to `View.VISIBLE`. If set to `View.GONE`, the alphabetical sticky headers will not appear.
Online status indicator not visible	Ensure `setUsersStatusVisibility` is set to `View.VISIBLE`. If set to `View.GONE`, the online/offline status indicator will not appear next to user avatars.

FAQ

Q: How do I show only friends in the user list? A: Create a UsersRequest.UsersRequestBuilder, call friendsOnly(true), and pass it to setUsersRequestBuilder. Q: How do I filter users by role? A: Create a UsersRequest.UsersRequestBuilder, call setRoles(List<String>) with the desired role names, and pass it to setUsersRequestBuilder. Q: How do I listen for user blocked/unblocked events outside the component? A: Use CometChatUserEvents.addUserListener("YOUR_TAG", ...) and override ccUserBlocked and ccUserUnblocked. Call CometChatUserEvents.removeListener("YOUR_TAG") to unsubscribe. Q: How do I customize the avatar style in the user list? A: Define a custom style with parent CometChatAvatarStyle in themes.xml, reference it in a CometChatUsersStyle using cometchatUsersAvatarStyle, and apply with setStyle(). Q: How do I add custom long-press options without removing the defaults? A: Use addOptions instead of setOptions. addOptions appends your custom MenuItem objects to the existing default options.

​When to use this

​Prerequisites

​Quick start

​Core concepts

​Implementation

​Actions

​setOnItemClick

​setOnItemLongClick

​setOnBackPressListener

​setOnSelect

​setOnError

​setOnLoad

​setOnEmpty

​Filters

​UsersRequestBuilder

​SearchRequestBuilder

​Events

​Style

​Functionality

​Advanced views

​setOptions

​addOptions

​setLoadingView

​setEmptyView

​setErrorView

​setLeadingView

​setTitleView

​setTrailingView

​setItemView

​setSubtitleView

​setOverflowMenu

​Customization matrix

​Common pitfalls & fixes

​FAQ

​Next steps

When to use this

Prerequisites

Quick start

Core concepts

Implementation

Actions

`setOnItemClick`

`setOnItemLongClick`

`setOnBackPressListener`

`setOnSelect`

`setOnError`

`setOnLoad`

`setOnEmpty`

Filters

`UsersRequestBuilder`

`SearchRequestBuilder`

Events

Style

Functionality

Advanced views

`setOptions`

`addOptions`

`setLoadingView`

`setEmptyView`

`setErrorView`

`setLeadingView`

`setTitleView`

`setTrailingView`

`setItemView`

`setSubtitleView`

`setOverflowMenu`

Customization matrix

Common pitfalls & fixes

FAQ

Next steps