Skip to main content
Version: v5

Users

Overview​

The Users is a Component, showcasing an accessible list of all available users. It provides an integral search functionality, allowing you to locate any specific user swiftly and easily. For each user listed, the widget displays the user's name by default, in conjunction with their avatar when available. Furthermore, it includes a status indicator, visually informing you whether a user is currently online or offline.

Image

Usage​

Integration​

The following code snippet illustrates how you can directly incorporate the Users component into your layout.xml file.

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

Actions​

Actions dictate how a component functions. They are divided into two types: Predefined and User-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

setOnItemClick​

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

YourActivity.java
cometchatUsers.setOnItemClick((view1, position, user) -> {
            
    });
setOnItemLongClick​

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

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

    });
setOnBackPressListener​

OnBackPressListener is triggered when you press the back button in the app bar. It has a predefined behavior; when clicked, it navigates to the previous activity. However, you can override this action using the following code snippet.

YourActivity.java
cometchatUsers.setOnBackPressListener(() -> {
            
    });
setOnSelect​

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

YourActivity.java
cometchatUsers.setOnSelect(t -> {

    });
OnError​

This action doesn't change the behavior of the component but rather listens for any errors that occur in the Users component.

YourActivity.java
cometchatUsers.setOnError(cometchatException -> {

    });
setOnLoad​

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

YourActivity.java
cometchatUsers.setOnLoad(list -> {

});
setOnEmpty​

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

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

Filters​

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria, allowing for a more customized. Filters can be applied using RequestBuilders of Chat SDK.

1. UserRequestBuilder​

The UserRequestBuilder enables you to filter and customize the user list based on available parameters in UserRequestBuilder. This feature allows you to create more specific and targeted queries when fetching users. The following are the parameters available in UserRequestBuilder

MethodsTypeDescription
setLimitintsets the number users that can be fetched in a single request, suitable for pagination
setSearchKeywordStringused for fetching users matching the passed string
hideBlockedUsersboolused for fetching all those users who are not blocked by the logged in user
friendsOnlyboolused for fetching only those users in which logged in user is a member
setRolesList<String>used for fetching users containing the passed tags
setTagsList<String>used for fetching users containing the passed tags
withTagsboolused for fetching users containing tags
setUserStatusStringused for fetching users by their status online or offline
setUIDsList<String>used for fetching users containing the passed users

Example

In the example below, we are applying a filter to the UserList based on Friends.

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

The SearchRequestBuilder uses UserRequestBuilder enables you to filter and customize the search list based on available parameters in UserRequestBuilder. This feature allows you to keep uniformity between the displayed UserList and searched UserList.

Example

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

Events​

Events are emitted by a Component. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed.

To handle events supported by Users you have to add corresponding listeners by using CometChatUserEvents

EventsDescription
ccUserBlockedThis will get triggered when the logged in user blocks another user
ccUserUnblockedThis will get triggered when the logged in user unblocks another user
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");

Customization​

To fit your app's design requirements, you can customize the appearance of the User component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

Style​

Using Style you can customize the look and feel of the component in your app, These parameters typically control elements such as the color, size, shape, and fonts used within the component.

You can set the styling object to the CometChatUsers Component to customize the styling.

Image
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>
 
cometChatUsers.setStyle(R.style.CustomUsersStyle);

To know more such attributes, visit the attributes file.

Functionality​

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can toggle the visibility of UI elements.

Below is a list of customizations along with corresponding code snippets

MethodsDescriptionCode
setBackIconVisibilityUsed to toggle visibility for back button in the app bar.setBackIconVisibility(View.VISIBLE);
setToolbarVisibilityUsed to toggle visibility for back button in the app bar.setToolbarVisibility(View.GONE);
setStickyHeaderVisibilityUsed to toggle visibility for back button in the app bar.setStickyHeaderVisibility(View.GONE);
setErrorStateVisibilityUsed to hide error state on fetching Users.setErrorStateVisibility(View.GONE);
setEmptyStateVisibilityUsed to hide empty state on fetching Users.setEmptyStateVisibility(View.GONE);
setLoadingStateVisibilityUsed to hide loading state while fetching Users.setLoadingStateVisibility(View.GONE);
setSeparatorVisibilityUsed to control visibility of Separators in the list view.setSeparatorVisibility(View.GONE);
setUsersStatusVisibilityUsed to control visibility of status indicator shown if user is online.setUsersStatusVisibility(View.GONE);
setSelectionModeThis method determines the selection mode for Users, enabling users to select either a single User or multiple Users at once..setSelectionMode(UIKitConstants.SelectionMode.MULTIPLE);
setSearchkeywordUsed for fetching users matching the passed keywords.setSearchkeyword("anything");
setSearchBoxVisibilityUsed to hide search box shown in the tool bar.setSearchBoxVisibility(View.GONE);

Advanced​

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

setOptions​

This method sets a predefined list of actions that users can perform when they long press a user in the list. These options typically include:

  • Muting notifications for a specific user

By customizing these options, developers can provide a streamlined and contextually relevant user experience.

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

addOptions​

This method extends the existing set of actions available when users long press a user item. Unlike setOptionsDefines, which replaces the default options, addOptionsAdds allows developers to append additional actions without removing the default ones. Example use cases include:

  • Adding a "Report Spam" action
  • Introducing a "Save to Notes" option
  • Integrating third-party actions such as "Share to Cloud Storage"

This method provides flexibility in modifying user interaction capabilities.

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

setLoadingView​

This method allows developers to set a custom loading view that is displayed when data is being fetched or loaded within the component. Instead of using a default loading spinner, a custom animation, progress bar, or branded loading screen can be displayed.

Use cases:

  • Showing a skeleton loader for users while data loads
  • Displaying a custom progress indicator with branding
  • Providing an animated loading experience for a more engaging UI
cometchatUsers.setLoadingView(R.layout.your_loading_view);

setEmptyView​

Configures a custom view to be displayed when there are no users. This improves the user experience by providing meaningful content instead of an empty screen.

Examples:

  • Displaying a message like "No users yet. Start a new chat!"
  • Showing an illustration or animation to make the UI visually appealing
  • Providing a button to start a new user
cometchatUsers.setEmptyView(R.layout.your_empty_view);

setErrorView​

Defines a custom error state view that appears when an issue occurs while loading users or messages. This enhances the user experience by displaying friendly error messages instead of generic system errors.

Common use cases:

  • Showing "Something went wrong. Please try again." with a retry button
  • Displaying a connection issue message if the user is offline
  • Providing troubleshooting steps for the error
cometchatUsers.setErrorView(R.layout.your_empty_view);

setLeadingView​

This method allows developers to set a custom leading view element that appears at the beginning of each user item. Typically, this space is used for profile pictures, avatars, or user badges.

Use Cases:

  • Profile Pictures & Avatars – Display user profile images with online/offline indicators.
  • Custom Icons or Badges – Show role-based badges (Admin, VIP, Verified) before the user name.
  • Status Indicators – Add an active status ring or colored border based on availability.
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) {

            }
        });

setTitleView​

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

Use Cases:

  • Styled Usernames – Customize fonts, colors, or text sizes for the name display.
  • Additional Metadata – Show extra details like username handles or job roles.
  • Inline Actions – Add a follow button or verification checkmark next to the name.
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) {

            }
        });

setTrailingView​

This method allows developers to customize the trailing (right-end) section of each user item, typically used for actions like buttons, icons, or extra information.

Use Cases:

  • Quick Actions – Add a follow/unfollow button.
  • Notification Indicators – Show unread message counts or alert icons.
  • Custom Info Display – Display last active time or mutual connections.
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) {

            }
        });

setItemView​

This method allows developers to assign a fully custom ListItem layout to the Users component, replacing the default design. It provides complete control over the appearance and structure of each user item in the list.

Use Cases:

  • Customizing User Display – Modify how user information (name, avatar, status) is presented.
  • Adding Action Buttons – Include follow, message, or call buttons directly in the item view.
  • Highlighting User Roles – Display user badges such as Admin, Moderator, or VIP.
 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

Image

You can indeed create a custom layout file named custom_list_item_view.xml for more complex or unique list items.

Once this layout file is made, you would inflate it inside the createView() method of the UsersViewHolderListener. The inflation process prepares the layout for use in your application:

Following this, you would use the bindView() method to initialize and assign values to your individual views. This could include setting text on TextViews, images on ImageViews, and so on based on the properties of the User object:

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

            }
        });

setSubtitleView​

This method customizes the subtitle view of each user item, typically shown below the user's name. It can display additional details such as user status, last seen time, or a brief bio.

Use Cases:

  • Last Active Time – Show "Online Now", "Last seen 2 hours ago".
  • User Status – Display status messages like "Offine", "Available".
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

Image

You can indeed create a custom layout file named subtitle_layout.xml for more complex or unique list items.

Once this layout file is made, you would inflate it inside the createView() method of the UsersViewHolderListener. The inflation process prepares the layout for use in your application:

Following this, you would use the bindView() method to initialize and assign values to your individual views. This could include setting text on TextViews, images on ImageViews, and so on based on the properties of the User object:

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

setOverflowMenu​

This method customizes the overflow menu, typically appearing as a three-dot (⋮) icon, allowing additional options for each user in the list.

Use Cases:

  • User Management Actions – "Block User", "Report", "Add to Favorites".
  • Friendship & Communication – "Send Message", "Follow/Unfollow".
  • Profile Settings – "View Profile", "Edit Contact Info".
users.setOverflowMenu(v);

Example

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