Users - CometChat Docs

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.

Usage

Integration

To use Users in your component, use the following code snippet:

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code
return <CometChatUsers />;

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.

onItemPress

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onPressHandler = (user: CometChat.User) => {
  //code
};

return <CometChatUsers onItemPress={onPressHandler} />;

onItemLongPress

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onLongPressHandler = (user: CometChat.User) => {
  //code
};

return <CometChatUsers onItemLongPress={onLongPressHandler} />;

onBack

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

const onBackHandler = () => {
  //code
};

return <CometChatUsers showBackButton={true} onBack={onBackHandler} />;

onSelection

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onSelectionHandler = (selection: Array<CometChat.User>) => {
  //code
};

return (
  <CometChatUsers selectionMode={"single"} onSelection={onSelectionHandler} />
);

onError

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onErrorHandler = (error: CometChat.CometChatException) => {
  console.log("Error");
};

return <CometChatUsers onError={onErrorHandler} />;

onEmpty

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onEmptyHandler = () => {
  console.log("Empty");
};

return <CometChatUsers onEmpty={onEmptyHandler} />;

onLoad

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onLoadHandler = (list: CometChat.User[]) => {
  console.log("Loading");
};

return <CometChatUsers onLoad={onLoadHandler} />;

onSubmit

Callback when submit selection button is pressed.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

const onSubmitHandler = (list: Array<CometChat.User>) => {
  console.log("Final List", list);
};

return <CometChatUsers onSubmit={onSubmitHandler} />;

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

Methods	Type	Description
setLimit	number	sets the number 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	Array<string>	used for fetching users containing the passed tags
setTags	Array<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	Array<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.

App.tsx

import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

function App(): React.JSX.Element {
  const usersRequestBuilder = new CometChat.UsersRequestBuilder()
    .setLimit(5)
    .friendsOnly(true);

  return <CometChatUsers usersRequestBuilder={usersRequestBuilder} />;
}

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

App.tsx

import { CometChat } from "@cometchat/chat-sdk-react-native";
import { CometChatUsers } from "@cometchat/chat-uikit-react-native";

function App(): React.JSX.Element {
  const usersRequestBuilder = new CometChat.UsersRequestBuilder()
    .setLimit(5)
    .setSearchKeyword("Alice");

  return <CometChatUsers searchRequestBuilder={usersRequestBuilder} />;
}

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 CometChatUIEventHandler.addUserListener

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

Adding Listeners

import { CometChatUIEventHandler } from "@cometchat/chat-uikit-react-native";

CometChatUIEventHandler.addUserListener("USER_LISTENER_ID", {
  ccUserBlocked: ({ item }) => {
    //code
  },
});

CometChatUIEventHandler.addUserListener("USER_LISTENER_ID", {
  ccUserUnblocked: ({ item }) => {
    //code
  },
});

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.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code
return (
  <CometChatUsers
    style={{
      titleStyle: {
        color: "#FBAA75",
      },
      titleSeparatorStyle: {
        borderBottomColor: "#FBAA75",
      },
      itemStyle: {
        avatarStyle: {
          containerStyle: {
            borderRadius: 8,
            backgroundColor: "#FBAA75",
          },
          imageStyle: {
            borderRadius: 8,
          },
        },
      },
    }}
  ></CometChatUsers>
);

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

Property	Description	Code
hideHeader	Used to toggle visibility for the toolbar/header	`hideHeader?: boolean`
showBackButton	Used to toggle visibility for back button	`showBackButton?: boolean`
hideSearch	Used to toggle visibility for search box	`hideSearch?: boolean`
hideError	Used to hide error on fetching users	`hideError?: boolean`
stickyHeaderVisibility	Used to hide section headers	`stickyHeaderVisibility?: boolean`
selectionMode	This method determines the selection mode for users, enabling users to select either a single user or multiple users at once.	`selectionMode={SelectionMode.multiple}`
hideSubmitButton	Used to toggle the visibility of the submit button when selectionMode is enabled.	`hideBackButton={true}`
searchPlaceholderText	Used to set search placeholder text	`searchPlaceholderText?: string;`
hideLoadingState	Used to toggle visibility for Loading state	`hideLoadingState?: boolean`
usersStatusVisibility	Used to toggle visibility for User status	`usersStatusVisibility?: boolean`
searchKeyword	Keyword used to fetch initial user list.	`searchKeyword?: string`
title	Title for the header.	`title?: string`

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.

LoadingView

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code
const getLoadingView = (): JSX.Element => {
  //your custom loading view
  //return jsx;
};
return <CometChatUsers LoadingView={getLoadingView} />;

EmptyView

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code
const getEmptyView = (): JSX.Element => {
  //your custom Empty view
  //return jsx;
};
return <CometChatUsers EmptyView={getEmptyView}/>;

ErrorView

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code
const getErrorView = (): JSX.Element => {
  //your custom error view
  //return jsx;
};
return <CometChatUsers ErrorView={getErrorView} />;

LeadingView

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.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
//code
const getLeadingView = (user: CometChat.User): JSX.Element => {
  //your custom leading view
  //return jsx;
};
return <CometChatUsers LeadingView={getLeadingView} />;

TitleView

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.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
//code
const getTitleView = (user: CometChat.User): JSX.Element => {
  //your custom title view
  //return jsx;
};
return <CometChatUsers TitleView={getTitleView} />;

TrailingView

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.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
//code
const getTrailingView = (user: CometChat.User): JSX.Element => {
  //your custom Trailing view
  //return jsx;
};
return <CometChatUsers TrailingView={getTrailingView} />;

ItemView

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.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
//code
const getItemView = (user: CometChat.User): JSX.Element => {
  //your custom Item view
  //return jsx;
};
return <CometChatUsers ItemView={getItemView} />;

Example

SubtitleView

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
//code
const getSubtitleView = (user: CometChat.User): JSX.Element => {
  //your custom Subtitle view
  //return jsx;
};
return <CometChatUsers SubtitleView={getSubtitleView} />;

Example

AppBarOptions

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code
return (
  <CometChatUsers
    AppBarOptions={() => {
      return (
        <TouchableOpacity
          onPress={() => {
            //do something
          }}
        >
          <Text>Custom App Bar Options</Text>
        </TouchableOpacity>
      );
    }}
  />
);

Example

options

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

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code

const setMyOptions = (_user: CometChat.User) => {
    return [
      //options
    ];
  };


return (
  <CometChatUsers
    options={setMyOptions}
  />
);

addOptions

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

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.

App.tsx

import { CometChatUsers } from "@cometchat/chat-uikit-react-native";
//code

const addOptions = (_user: CometChat.User) => {
    return [
      //options
    ];
  };


return (
  <CometChatUsers
    addOptions={addOptions}
  />
);

​Overview

​Usage

​Integration

​Actions

onItemPress

onItemLongPress

onBack

onSelection

onError

onEmpty

onLoad

onSubmit

​Filters

1. UserRequestBuilder

2. SearchRequestBuilder

​Events

​Customization

​Style

​Functionality

​Advanced

​LoadingView

​EmptyView

​ErrorView

​LeadingView

​TitleView

​TrailingView

​ItemView

​SubtitleView

​AppBarOptions

​options

​addOptions

Overview

Usage

Integration

Actions

Filters

Events

Customization

Style

Functionality

Advanced

LoadingView

EmptyView

ErrorView

LeadingView

TitleView

TrailingView

ItemView

SubtitleView

AppBarOptions

options

addOptions