Users - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatUsers",
  "package": "com.cometchat.chatuikit.users",
  "xmlElement": "<com.cometchat.chatuikit.users.CometChatUsers />",
  "description": "Scrollable list of all available users with search, avatars, names, and online/offline status indicators.",
  "primaryOutput": {
    "method": "setOnItemClick",
    "type": "OnItemClick<User>"
  },
  "methods": {
    "data": {
      "setUsersRequestBuilder": {
        "type": "UsersRequest.UsersRequestBuilder",
        "default": "SDK default",
        "note": "Pass the builder, not the result of .build()"
      },
      "setSearchRequestBuilder": {
        "type": "UsersRequest.UsersRequestBuilder",
        "default": "Same as main builder",
        "note": "Separate builder for search results"
      }
    },
    "callbacks": {
      "setOnItemClick": "OnItemClick<User>",
      "setOnItemLongClick": "OnItemLongClick<User>",
      "setOnBackPressListener": "OnBackPress",
      "setOnSelect": "OnSelection<User>",
      "setOnError": "OnError",
      "setOnLoad": "OnLoad<User>",
      "setOnEmpty": "OnEmpty"
    },
    "visibility": {
      "setBackIconVisibility": { "type": "int (View.VISIBLE | View.GONE)", "default": "View.GONE" },
      "setToolbarVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setLoadingStateVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setErrorStateVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setEmptyStateVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setSeparatorVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setUserStatusVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setStickyHeaderVisibility": { "type": "int", "default": "View.VISIBLE" },
      "setSearchBoxVisibility": { "type": "int", "default": "View.VISIBLE" }
    },
    "selection": {
      "setSelectionMode": {
        "type": "UIKitConstants.SelectionMode",
        "values": ["NONE", "SINGLE", "MULTIPLE"],
        "default": "NONE"
      }
    },
    "viewSlots": {
      "seItemView": "UsersViewHolderListener — entire list item row (note: typo in SDK method name)",
      "setLeadingView": "UsersViewHolderListener — avatar / left section",
      "setTitleView": "UsersViewHolderListener — name / title text",
      "setSubtitleView": "UsersViewHolderListener — subtitle text below name",
      "setTrailingView": "UsersViewHolderListener — right section",
      "setLoadingView": "@LayoutRes int — loading spinner",
      "setEmptyView": "@LayoutRes int — empty state",
      "setErrorView": "@LayoutRes int — error state",
      "setOverflowMenu": "View — toolbar menu",
      "setOptions": "Function2<Context, User, List<MenuItem>> — long-press context menu (replaces defaults)",
      "addOptions": "Function2<Context, User, List<MenuItem>> — long-press context menu (appends to defaults)"
    },
    "advanced": {
      "selectUser": "User, SelectionMode — programmatic selection",
      "clearSelection": "void — clears all selected users",
      "getSelectedUsers": "List<User> — returns selected items",
      "setSearchKeyword": "String — programmatic search",
      "setTitleText": "String — custom toolbar title",
      "setSearchPlaceholderText": "String — search placeholder",
      "getBinding": "CometchatUserListBinding — root ViewBinding",
      "getViewModel": "UsersViewModel — internal ViewModel access",
      "getUsersAdapter": "UsersAdapter — internal adapter access",
      "setAdapter": "UsersAdapter — replace the default adapter"
    },
    "style": {
      "setStyle": {
        "type": "@StyleRes int",
        "parent": "CometChatUsersStyle"
      }
    }
  },
  "events": [
    {
      "name": "CometChatUserEvents.ccUserBlocked",
      "payload": "User",
      "description": "Logged-in user blocked another user"
    },
    {
      "name": "CometChatUserEvents.ccUserUnblocked",
      "payload": "User",
      "description": "Logged-in user unblocked another user"
    }
  ],
  "sdkListeners": [
    "onUserOnline",
    "onUserOffline"
  ]
}

Where It Fits

CometChatUsers is a list component. It renders all available users and emits the selected User via setOnItemClick. Wire it to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer to build a direct messaging layout.

Kotlin
Java

ChatActivity.kt

class ChatActivity : AppCompatActivity() {

    private lateinit var users: CometChatUsers
    private lateinit var messageHeader: CometChatMessageHeader
    private lateinit var messageList: CometChatMessageList
    private lateinit var messageComposer: CometChatMessageComposer

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_chat)

        users = findViewById(R.id.users)
        messageHeader = findViewById(R.id.message_header)
        messageList = findViewById(R.id.message_list)
        messageComposer = findViewById(R.id.message_composer)

        users.setOnItemClick { view, position, user ->
            messageHeader.setUser(user)
            messageList.setUser(user)
            messageComposer.setUser(user)
        }
    }
}

ChatActivity.java

public class ChatActivity extends AppCompatActivity {

    private CometChatUsers users;
    private CometChatMessageHeader messageHeader;
    private CometChatMessageList messageList;
    private CometChatMessageComposer messageComposer;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_chat);

        users = findViewById(R.id.users);
        messageHeader = findViewById(R.id.message_header);
        messageList = findViewById(R.id.message_list);
        messageComposer = findViewById(R.id.message_composer);

        users.setOnItemClick((view, position, user) -> {
            messageHeader.setUser(user);
            messageList.setUser(user);
            messageComposer.setUser(user);
        });
    }
}

Quick Start

Add the component to your layout XML:

layout_activity.xml

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

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:

Kotlin
Java

YourActivity.kt

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(CometChatUsers(this))
}

YourActivity.java

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(new CometChatUsers(this));
}

Or in a Fragment:

Kotlin
Java

YourFragment.kt

override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View {
    return CometChatUsers(requireContext())
}

YourFragment.java

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
    return new CometChatUsers(getContext());
}

Filtering Users

Pass a UsersRequest.UsersRequestBuilder to setUsersRequestBuilder. Pass the builder instance — not the result of .build().

Kotlin
Java

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

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

Filter Recipes

Recipe	Code
Friends only	`builder.friendsOnly(true)`
Limit to 10 per page	`builder.setLimit(10)`
Search by keyword	`builder.setSearchKeyword("john")`
Hide blocked users	`builder.hideBlockedUsers(true)`
Filter by roles	`builder.setRoles(Arrays.asList("admin", "moderator"))`
Filter by tags	`builder.setTags(Arrays.asList("vip"))`
Online users only	`builder.setUserStatus(CometChatConstants.USER_STATUS_ONLINE)`
Filter by UIDs	`builder.setUIDs(Arrays.asList("uid1", "uid2"))`

The component uses infinite scroll — the next page loads as the user scrolls to the bottom. Refer to UsersRequestBuilder for the full builder API.

Search Request Builder

Use setSearchRequestBuilder to customize the search list separately from the main list:

Kotlin
Java

val searchBuilder = UsersRequest.UsersRequestBuilder()
    .setSearchKeyword("**")
cometChatUsers.setSearchRequestBuilder(searchBuilder)

UsersRequest.UsersRequestBuilder searchBuilder = new UsersRequest.UsersRequestBuilder()
    .setSearchKeyword("**");
cometChatUsers.setSearchRequestBuilder(searchBuilder);

Actions and Events

Callback Methods

`setOnItemClick`

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

Kotlin
Java

YourActivity.kt

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

YourActivity.java

cometchatUsers.setOnItemClick((view1, 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`

Fires when a user row is long-pressed. Use for additional actions like block or mute.

Kotlin
Java

YourActivity.kt

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

YourActivity.java

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

});

`setOnBackPressListener`

Fires when the user presses the back button in the app bar. Default: navigates to the previous activity.

Kotlin
Java

YourActivity.kt

cometchatUsers.onBackPressListener = OnBackPress {

}

YourActivity.java

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

`setOnSelect`

Fires when a user is checked/unchecked in multi-select mode. Requires setSelectionMode to be set.

Kotlin
Java

YourActivity.kt

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

YourActivity.java

cometchatUsers.setOnSelect(t -> {

});

`setOnError`

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

Kotlin
Java

YourActivity.kt

cometchatUsers.setOnError {

}

YourActivity.java

cometchatUsers.setOnError(cometchatException -> {

});

`setOnLoad`

Fires when the list is successfully fetched and loaded.

Kotlin
Java

YourActivity.kt

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

    }
})

YourActivity.java

cometchatUsers.setOnLoad(list -> {

});

`setOnEmpty`

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

Kotlin
Java

YourActivity.kt

cometchatUsers.setOnEmpty {
            
}

YourActivity.java

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

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.

Global UI Events

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

Event	Fires when	Payload
`ccUserBlocked`	The logged-in user blocks another user	`User`
`ccUserUnblocked`	The logged-in user unblocks another user	`User`

Kotlin
Java

Add Listener

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")

Add Listener

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("LISTENER_TAG");

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

SDK Listener	Internal behavior
`onUserOnline`	Updates online status indicator for the user
`onUserOffline`	Updates offline status indicator for the user

Automatic: user presence changes update the status indicator in real time.

Functionality

Small functional customizations such as toggling visibility of UI elements and configuring selection modes.

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 alphabetical sticky header	`.setStickyHeaderVisibility(View.GONE);`
`setLoadingStateVisibility`	Hides the loading state while fetching users	`.setLoadingStateVisibility(View.GONE);`
`setErrorStateVisibility`	Hides the error state on fetching users	`.setErrorStateVisibility(View.GONE);`
`setEmptyStateVisibility`	Hides the empty state on fetching users	`.setEmptyStateVisibility(View.GONE);`
`setSeparatorVisibility`	Controls visibility of separators in the list view	`.setSeparatorVisibility(View.GONE);`
`setUserStatusVisibility`	Controls visibility of the online status indicator	`.setUserStatusVisibility(View.GONE);`
`setSearchBoxVisibility`	Controls visibility of the search box in the toolbar	`.setSearchBoxVisibility(View.GONE);`
`setSelectionMode`	Determines the selection mode (single or multiple)	`.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE);`
`setSearchKeyword`	Programmatically triggers a search with the given keyword	`.setSearchKeyword("john");`
`setTitleText`	Sets a custom title in the toolbar	`.setTitleText("Contacts");`
`setSearchPlaceholderText`	Sets the placeholder text for the search input	`.setSearchPlaceholderText("Find users...");`

Verify: After calling a visibility method, confirm the corresponding UI element is shown or hidden.

Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a User parameter receive the user object for that row via the UsersViewHolderListener pattern (createView + bindView).

Slot	Method	Replaces
Leading view	`setLeadingView(UsersViewHolderListener)`	Avatar / left section
Title view	`setTitleView(UsersViewHolderListener)`	Name / title text
Subtitle view	`setSubtitleView(UsersViewHolderListener)`	Subtitle text below name
Trailing view	`setTrailingView(UsersViewHolderListener)`	Right section
Item view	`seItemView(UsersViewHolderListener)`	Entire list item row (note: typo in SDK)
Loading view	`setLoadingView(@LayoutRes int)`	Loading spinner
Empty view	`setEmptyView(@LayoutRes int)`	Empty state
Error view	`setErrorView(@LayoutRes int)`	Error state
Overflow menu	`setOverflowMenu(View)`	Toolbar menu
Options (replace)	`setOptions(Function2)`	Long-press context menu (replaces defaults)
Options (append)	`addOptions(Function2)`	Long-press context menu (appends to defaults)

`setLeadingView`

Replace the avatar / left section.

Kotlin
Java

cometchatUsers.setLeadingView(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
    ) {
    }
})

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) {

    }
});

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`

Replace the name / title text.

Kotlin
Java

cometchatUsers.setTitleView(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
    ) {
    }
})

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) {

    }
});

Inline role badge example:

Create a custom_user_title_view.xml layout:

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>

Kotlin
Java

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)
        when (user.role) {
            "teacher" -> {
                role.visibility = View.VISIBLE
                role.background = ResourcesCompat.getDrawable(resources, R.drawable.teacher, null)
            }
            "student" -> {
                role.visibility = View.VISIBLE
                role.background = ResourcesCompat.getDrawable(resources, R.drawable.student, null)
            }
            "close_friend" -> {
                role.visibility = View.VISIBLE
                role.background = ResourcesCompat.getDrawable(resources, R.drawable.close_friend, null)
            }
            else -> role.visibility = View.GONE
        }
    }
})

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);
        }
    }
});

`setSubtitleView`

Replace the subtitle text below the user’s name.

Kotlin
Java

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
    ) {
    }
})

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) {

    }
});

Example with last-active timestamp:

Kotlin
Java

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)
    }
})

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);
    }
});

`setTrailingView`

Replace the right section of each user item.

Kotlin
Java

cometchatUsers.setTrailingView(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
    ) {
    }
})

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) {

    }
});

Role tag badge example:

Create a custom_user_tail_view.xml layout:

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>

Kotlin
Java

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
        }
    }
})

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);
        }
    }
});

`setItemView`

Replace the entire list item row.

The Java method name is seItemView (note the missing ‘t’). This is a known typo in the SDK. In Kotlin, property access syntax normalizes this.

Kotlin
Java

cometchatUsers.seItemView(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
    ) {
    }
})

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) {

    }
});

Example with online status background:

Create a custom_list_item_view.xml layout:

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.avatar.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>

Kotlin
Java

cometchatUsers.seItemView(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"))
        }
    }
})

cometchatUsers.seItemView(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"));
        }
    }
});

`setOptions`

Replace the long-press context menu entirely.

Kotlin
Java

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

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

`addOptions`

Append to the long-press context menu without removing defaults.

Kotlin
Java

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

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

`setLoadingView`

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

Kotlin
Java

cometchatUsers.loadingView = R.layout.your_loading_view

cometchatUsers.setLoadingView(R.layout.your_loading_view);

`setEmptyView`

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

Kotlin
Java

cometchatUsers.emptyView = R.layout.your_empty_view

cometchatUsers.setEmptyView(R.layout.your_empty_view);

`setErrorView`

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

Kotlin
Java

cometchatUsers.errorView = R.layout.your_error_view

cometchatUsers.setErrorView(R.layout.your_error_view);

`setOverflowMenu`

Replace the toolbar overflow menu.

Kotlin
Java

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

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

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

Common Patterns

Hide all chrome — minimal list

Kotlin
Java

cometChatUsers.setUserStatusVisibility(View.GONE)
cometChatUsers.setSeparatorVisibility(View.GONE)
cometChatUsers.setToolbarVisibility(View.GONE)
cometChatUsers.setStickyHeaderVisibility(View.GONE)

cometChatUsers.setUserStatusVisibility(View.GONE);
cometChatUsers.setSeparatorVisibility(View.GONE);
cometChatUsers.setToolbarVisibility(View.GONE);
cometChatUsers.setStickyHeaderVisibility(View.GONE);

Friends-only list

Kotlin
Java

val builder = UsersRequest.UsersRequestBuilder()
    .friendsOnly(true)
cometChatUsers.setUsersRequestBuilder(builder)

UsersRequest.UsersRequestBuilder builder = new UsersRequest.UsersRequestBuilder()
    .friendsOnly(true);
cometChatUsers.setUsersRequestBuilder(builder);

Online users only

Kotlin
Java

val builder = UsersRequest.UsersRequestBuilder()
    .setUserStatus(CometChatConstants.USER_STATUS_ONLINE)
cometChatUsers.setUsersRequestBuilder(builder)

UsersRequest.UsersRequestBuilder builder = new UsersRequest.UsersRequestBuilder()
    .setUserStatus(CometChatConstants.USER_STATUS_ONLINE);
cometChatUsers.setUsersRequestBuilder(builder);

Advanced Methods

Programmatic Selection

`selectUser`

Programmatically selects or deselects a user. Works with both SINGLE and MULTIPLE selection modes.

Kotlin
Java

// Select a user in single-select mode
cometChatUsers.selectUser(user, UIKitConstants.SelectionMode.SINGLE)

// Select a user in multi-select mode
cometChatUsers.selectUser(user, UIKitConstants.SelectionMode.MULTIPLE)

// Select a user in single-select mode
cometChatUsers.selectUser(user, UIKitConstants.SelectionMode.SINGLE);

// Select a user in multi-select mode
cometChatUsers.selectUser(user, UIKitConstants.SelectionMode.MULTIPLE);

In SINGLE mode, selecting a new user replaces the previous selection. In MULTIPLE mode, calling this on an already-selected user deselects it (toggle behavior).

`clearSelection`

Clears all selected users and resets the selection UI.

Kotlin
Java

cometChatUsers.clearSelection()

cometChatUsers.clearSelection();

`getSelectedUsers`

Returns the list of currently selected User objects.

Kotlin
Java

val selected = cometChatUsers.selectedUsers

List<User> selected = cometChatUsers.getSelectedUsers();

Selected Users List

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

Method	Type	Description
`setSelectedUsersListVisibility`	`int (View.VISIBLE / View.GONE)`	Show or hide the selected users strip
`setSelectedUserAvatarStyle`	`@StyleRes int`	Avatar style for selected user chips
`setSelectedUserItemTextColor`	`@ColorInt int`	Text color for selected user names
`setSelectedUserItemTextAppearance`	`@StyleRes int`	Text appearance for selected user names
`setSelectedUserItemRemoveIcon`	`Drawable`	Icon for the remove button on each chip
`setSelectedUserItemRemoveIconTint`	`@ColorInt int`	Tint color for the remove icon

Search Input Customization

The built-in search box can be customized programmatically:

Method	Type	Description
`setSearchPlaceholderText`	`String`	Sets the placeholder text for the search input
`setSearchInputTextColor`	`@ColorInt int`	Text color of the search input
`setSearchInputTextAppearance`	`@StyleRes int`	Text appearance of the search input
`setSearchInputPlaceHolderTextColor`	`@ColorInt int`	Placeholder text color
`setSearchInputPlaceHolderTextAppearance`	`@StyleRes int`	Placeholder text appearance
`setSearchInputIcon`	`Drawable`	Leading icon in the search box
`setSearchInputIconTint`	`@ColorInt int`	Tint for the leading icon
`setSearchInputEndIcon`	`Drawable`	Trailing icon in the search box
`setSearchInputEndIconTint`	`@ColorInt int`	Tint for the trailing icon
`setSearchInputStrokeWidth`	`@Dimension int`	Stroke width of the search box border
`setSearchInputStrokeColor`	`@ColorInt int`	Stroke color of the search box border
`setSearchInputBackgroundColor`	`@ColorInt int`	Background color of the search box
`setSearchInputCornerRadius`	`@Dimension int`	Corner radius of the search box

Internal Access

These methods provide direct access to internal components for advanced use cases.

Method	Returns	Description
`getBinding()`	`CometchatUserListBinding`	The ViewBinding for the component’s root layout
`getViewModel()`	`UsersViewModel`	The ViewModel managing user data and state
`getUsersAdapter()`	`UsersAdapter`	The adapter powering the RecyclerView
`setAdapter(UsersAdapter)`	`void`	Replaces the default adapter with a custom one

Use these only when the standard API is insufficient. Directly manipulating the adapter or ViewModel may conflict with the component’s internal state management.

Style

The component uses XML theme styles. Define a custom style with parent CometChatUsersStyle in themes.xml, then apply with setStyle().

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>

Kotlin
Java

cometChatUsers.setStyle(R.style.CustomUsersStyle)

cometChatUsers.setStyle(R.style.CustomUsersStyle);

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:

Method	Type	Description
`setBackgroundColor`	`@ColorInt int`	Background color of the component
`setBackIconTint`	`@ColorInt int`	Tint color for the back icon
`setBackIcon`	`Drawable`	Custom back icon drawable
`setTitleTextColor`	`@ColorInt int`	Title text color in the toolbar
`setTitleTextAppearance`	`@StyleRes int`	Title text appearance in the toolbar
`setItemTitleTextColor`	`@ColorInt int`	Text color for user item titles
`setItemTitleTextAppearance`	`@StyleRes int`	Text appearance for user item titles
`setItemBackgroundColor`	`@ColorInt int`	Background color for list items
`setItemSelectedBackgroundColor`	`@ColorInt int`	Background color for selected list items
`setSeparatorColor`	`@ColorInt int`	Color of list item separators
`setStrokeColor`	`@ColorInt int`	Stroke color of the component border
`setStrokeWidth`	`@Dimension int`	Stroke width of the component border
`setCornerRadius`	`@Dimension int`	Corner radius of the component
`setStickyTitleColor`	`@ColorInt int`	Text color for sticky alphabetical headers
`setStickyTitleAppearance`	`@StyleRes int`	Text appearance for sticky headers
`setStickyTitleBackgroundColor`	`@ColorInt int`	Background color for sticky headers
`setEmptyStateTextColor`	`@ColorInt int`	Title text color for the empty state
`setEmptyStateTextAppearance`	`@StyleRes int`	Title text appearance for the empty state
`setEmptyStateSubtitleTextColor`	`@ColorInt int`	Subtitle text color for the empty state
`setEmptyStateSubTitleTextAppearance`	`@StyleRes int`	Subtitle text appearance for the empty state
`setErrorStateTextColor`	`@ColorInt int`	Title text color for the error state
`setErrorStateTextAppearance`	`@StyleRes int`	Title text appearance for the error state
`setErrorStateSubtitleColor`	`@ColorInt int`	Subtitle text color for the error state
`setErrorStateSubtitleTextAppearance`	`@StyleRes int`	Subtitle text appearance for the error state
`setRetryButtonTextColor`	`@ColorInt int`	Text color for the retry button
`setRetryButtonTextAppearance`	`@StyleRes int`	Text appearance for the retry button
`setRetryButtonBackgroundColor`	`@ColorInt int`	Background color for the retry button
`setRetryButtonStrokeColor`	`@ColorInt int`	Stroke color for the retry button
`setRetryButtonStrokeWidth`	`@Dimension int`	Stroke width for the retry button
`setRetryButtonCornerRadius`	`@Dimension int`	Corner radius for the retry button
`setAvatarStyle`	`@StyleRes int`	Style for user avatars
`setStatusIndicatorStyle`	`@StyleRes int`	Style for online/offline status indicators

Checkbox Style Properties (Selection Mode)

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

Method	Type	Description
`setCheckBoxStrokeWidth`	`@Dimension int`	Stroke width of the checkbox border
`setCheckBoxCornerRadius`	`@Dimension int`	Corner radius of the checkbox
`setCheckBoxStrokeColor`	`@ColorInt int`	Stroke color of the checkbox border
`setCheckBoxBackgroundColor`	`@ColorInt int`	Background color of unchecked checkbox
`setCheckBoxCheckedBackgroundColor`	`@ColorInt int`	Background color of checked checkbox
`setCheckBoxSelectIcon`	`Drawable`	Icon shown when checkbox is checked
`setCheckBoxSelectIconTint`	`@ColorInt int`	Tint for the checkbox select icon
`setDiscardSelectionIcon`	`Drawable`	Icon for the discard selection button
`setDiscardSelectionIconTint`	`@ColorInt int`	Tint for the discard selection icon
`setSubmitSelectionIcon`	`Drawable`	Icon for the submit selection button
`setSubmitSelectionIconTint`	`@ColorInt int`	Tint for the submit selection icon

Customization Matrix

What to change	Where	Property/API	Example
Override behavior on user interaction	Activity/Fragment	`setOn<Event>` callbacks	`setOnItemClick((v, pos, u) -> { ... })`
Filter which users appear	Activity/Fragment	`setUsersRequestBuilder`	`setUsersRequestBuilder(builder)`
Customize search results	Activity/Fragment	`setSearchRequestBuilder`	`setSearchRequestBuilder(builder)`
Toggle visibility of UI elements	Activity/Fragment	`set<Feature>Visibility(int)`	`setUserStatusVisibility(View.GONE)`
Replace a section of the list item	Activity/Fragment	`set<Slot>View`	`setLeadingView(listener)`
Change colors, fonts, spacing	`themes.xml`	`CometChatUsersStyle`	`<item name="cometchatUsersSeparatorColor">#F76808</item>`
Avatar style (corner radius, background)	`themes.xml`	`cometchatUsersAvatarStyle`	`<item name="cometchatAvatarStrokeRadius">8dp</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	`setUserStatusVisibility(int)`	`.setUserStatusVisibility(View.GONE);`
Selection mode (single/multiple)	Activity/Fragment	`setSelectionMode(SelectionMode)`	`.setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE);`
Search keyword	Activity/Fragment	`setSearchKeyword(String)`	`.setSearchKeyword("john");`
Search box visibility	Activity/Fragment	`setSearchBoxVisibility(int)`	`.setSearchBoxVisibility(View.GONE);`
Custom toolbar title	Activity/Fragment	`setTitleText(String)`	`.setTitleText("Contacts");`
Search placeholder	Activity/Fragment	`setSearchPlaceholderText(String)`	`.setSearchPlaceholderText("Find users...");`
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)`	`.setLoadingView(R.layout.your_loading_view);`
Empty view	Activity/Fragment	`setEmptyView(int)`	`.setEmptyView(R.layout.your_empty_view);`
Error view	Activity/Fragment	`setErrorView(int)`	`.setErrorView(R.layout.your_error_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)`	See `setItemView` code above
Subtitle view	Activity/Fragment	`setSubtitleView(UsersViewHolderListener)`	See `setSubtitleView` code above
Overflow menu	Activity/Fragment	`setOverflowMenu(View)`	`cometChatUsers.setOverflowMenu(view);`
Programmatic selection	Activity/Fragment	`selectUser(User, SelectionMode)`	`.selectUser(user, SelectionMode.SINGLE);`
Clear selection	Activity/Fragment	`clearSelection()`	`.clearSelection();`
Selected users strip	Activity/Fragment	`setSelectedUsersListVisibility(int)`	`.setSelectedUsersListVisibility(View.VISIBLE);`
Internal adapter access	Activity/Fragment	`getUsersAdapter()` / `setAdapter()`	Advanced use only

Next Steps

Conversations

Browse recent conversations

Groups

Browse and search available groups

Message List

Display messages in a conversation

Theming

Customize colors, fonts, and styles

​Where It Fits

​Quick Start

​Filtering Users

​Filter Recipes

​Search Request Builder

​Actions and Events

​Callback Methods

​setOnItemClick

​setOnItemLongClick

​setOnBackPressListener

​setOnSelect

​setOnError

​setOnLoad

​setOnEmpty

​Global UI Events

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​setLeadingView

​setTitleView

​setSubtitleView

​setTrailingView

​setItemView

​setOptions

​addOptions

​setLoadingView

​setEmptyView

​setErrorView

​setOverflowMenu

​Common Patterns

​Hide all chrome — minimal list

​Friends-only list

​Online users only

​Advanced Methods

​Programmatic Selection

​selectUser

​clearSelection

​getSelectedUsers

​Selected Users List

​Search Input Customization

​Internal Access

​Style

​Programmatic Style Properties

​Checkbox Style Properties (Selection Mode)

​Customization Matrix

​Next Steps

Conversations

Groups

Message List

Theming

Where It Fits

Quick Start

Filtering Users

Filter Recipes

Search Request Builder

Actions and Events

Callback Methods

`setOnItemClick`

`setOnItemLongClick`

`setOnBackPressListener`

`setOnSelect`

`setOnError`

`setOnLoad`

`setOnEmpty`

Global UI Events

SDK Events (Real-Time, Automatic)

Functionality

Custom View Slots

`setLeadingView`

`setTitleView`

`setSubtitleView`

`setTrailingView`

`setItemView`

`setOptions`

`addOptions`

`setLoadingView`

`setEmptyView`

`setErrorView`

`setOverflowMenu`

Common Patterns

Hide all chrome — minimal list

Friends-only list

Online users only

Advanced Methods

Programmatic Selection

`selectUser`

`clearSelection`

`getSelectedUsers`

Selected Users List

Search Input Customization

Internal Access

Style

Programmatic Style Properties

Checkbox Style Properties (Selection Mode)

Customization Matrix

Next Steps