Retrieve Users

Fetch, filter, search, and sort users using the CometChat JavaScript SDK. Includes pagination, role-based filtering, tag support, and online user counts.

AI Integration Quick Reference

// Fetch users list
const request = new CometChat.UsersRequestBuilder()
  .setLimit(30).build();
const users = await request.fetchNext();

// Get specific user details
const user = await CometChat.getUser("UID");

// Get logged-in user
const me = await CometChat.getLoggedinUser();

// Get online user count
const count = await CometChat.getOnlineUserCount();

The CometChat SDK provides methods to retrieve the logged-in user, fetch filtered user lists, look up individual users by UID, and get online user counts. All user methods return User objects.

User Object Fields

Field	Getter	Return Type	Description
uid	getUid()	string	Unique user ID
name	getName()	string	Display name of the user
avatar	getAvatar()	string	URL of the user’s avatar image
status	getStatus()	string	Online status of the user
lastActiveAt	getLastActiveAt()	number	Timestamp when the user was last active
role	getRole()	string	Role assigned to the user

Get the Logged-In User

Use getLoggedinUser() to get the current user’s details. Resolves with null if no user is logged in.

TypeScript

CometChat.getLoggedinUser().then(
  (user: CometChat.User) => {
      console.log("user details:", { user });
  }, (error: CometChat.CometChatException) => {
      console.log("error getting details:", { error });
  }
);  

JavaScript

CometChat.getLoggedinUser().then(
user => {
  console.log("user details:", { user });
}, error => {
  console.log("error getting details:", { error });
}
);

This method returns a User object with the logged-in user’s information

Retrieve List of Users

In order to fetch the list of users, you can use the UsersRequest class. To use this class i.e to create an object of the UsersRequest class, you need to use the UsersRequestBuilder class. The UsersRequestBuilder class allows you to set the parameters based on which the users are to be fetched.

Fetching using this builder will return User objects

The UsersRequestBuilder class allows you to set the below parameters:

Set Limit

Sets the number of users to fetch per request.

TypeScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .build();

JavaScript

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .build();

Set Search Keyword

Filters users by a search string.

TypeScript

let limit: number = 30;
let searchKeyword: string = "super";
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setSearchKeyword(searchKeyword)
  .build();

JavaScript

let limit = 30;
let searchKeyword = "super";
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setSearchKeyword(searchKeyword)
                  .build();

Search In

Specifies which user properties to search. Works with setSearchKeyword(). By default, searches both UID and name.

TypeScript

let limit: number = 30;
let searchKeyword: string = "super";
let searchIn: Array<String> = ["uid", "name"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setSearchKeyword(searchKeyword)
  .searchIn(searchIn)
  .build();

JavaScript

let limit = 30;
let searchKeyword = "super";
let searchIn = ["uid", "name"];
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setSearchKeyword(searchKeyword)
                  .searchIn(searchIn)
                  .build();

Set Status

Filters users by online status:

• CometChat.USER_STATUS.ONLINE — Only online users
• CometChat.USER_STATUS.OFFLINE — Only offline users

If not set, returns all users.

TypeScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setStatus(CometChat.USER_STATUS.ONLINE)
  .build(); 

JavaScript

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
 .setLimit(limit)
 .setStatus(CometChat.USER_STATUS.ONLINE)
 .build(); 

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
status	getStatus()	string	Online status of the user ("online" or "offline")

Hide Blocked Users

When true, excludes users blocked by the logged-in user from the results.

TypeScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .hideBlockedUsers(true)
  .build();

JavaScript

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .hideBlockedUsers(true)
                  .build();

Set Roles

Filters users by specified roles.

TypeScript

let limit: number = 30;
let roles: Array<String> = ["default", "dev"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setRoles(roles)
  .build();

JavaScript

let limit = 30;
let roles = ["default", "dev"];
let usersRequest = new CometChat.UsersRequestBuilder()
 .setLimit(limit)
 .setRoles(roles)
 .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
role	getRole()	string	Role assigned to the user

Friends Only

When true, returns only friends of the logged-in user.

TypeScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .friendsOnly(true)
  .build();

JavaScript

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .friendsOnly(true)
                  .build();

Set Tags

Filters users by specified tags.

TypeScript

let limit: number = 30;
let tags: Array<String> = ["tag1", "tag2"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setTags(tags)
  .build();

JavaScript

let limit = 30;
let tags = ["tag1", "tag2"];
let usersRequest = new CometChat.UsersRequestBuilder()
 .setLimit(limit)
 .setTags(tags)
 .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
tags	getTags()	string[]	Tags associated with the user

With Tags

When true, includes tag data in the returned user objects.

TypeScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .withTags(true)
  .build();

JavaScript

let limit = 30;
let usersRequest = new CometChat.UsersRequestBuilder()
 .setLimit(limit)
 .withTags(true)
 .build();

Relevant fields to access on returned users:

Field	Getter	Return Type	Description
tags	getTags()	string[]	Tags associated with the user

Set UIDs

Fetches specific users by their UIDs. Maximum 25 users per request.

TypeScript

let limit: number = 30;
let UIDs: Array<String> = ["cometchat-uid-1", "cometchat-uid-2"];
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .setUIDs(UIDs)
  .build();

JavaScript

let limit = 30;
let UIDs = ["cometchat-uid-1", "cometchat-uid-2"];
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .setUIDs(UIDs)
                  .build();

Sort By

Sorts the user list by a specific property. Default sort order: status → name → UID. Pass "name" to sort by name → UID.

TypeScript

let limit: number = 30;
let sortBy: string = "name";
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .sortBy(sortBy)
  .build(); 

JavaScript

let limit = 30;
let UIDs = ["cometchat-uid-1", "cometchat-uid-2"];
let sortBy = "name";
let usersRequest = new CometChat.UsersRequestBuilder()
                  .setLimit(limit)
                  .sortBy(sortBy)
                  .build();

Sort By Order

Sets the sort order. Default is ascending ("asc"). Use "desc" for descending.

TypeScript

let limit: number = 30;
let sortOrder: string = "desc";
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .sortByOrder(sortOrder)
  .build();

JavaScript

let limit = 30;
let sortOrder = "desc";
let usersRequest = new CometChat.UsersRequestBuilder()
  .setLimit(limit)
  .sortByOrder(sortOrder)
  .build();

After configuring the builder, call build() to get the UsersRequest object, then call fetchNext() to retrieve users.

TypeScript

let limit: number = 30;
let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder()
.setLimit(limit)
.build();

usersRequest.fetchNext().then(
  (userList: CometChat.User[]) => {
      console.log("User list received:", userList);
  }, (error: CometChat.CometChatException) => {
      console.log("User list fetching failed with error:", error);
  }
);

JavaScript

const limit = 30;
const usersRequest = new CometChat.UsersRequestBuilder()
.setLimit(limit)
.build();

usersRequest.fetchNext().then(
userList => {
  console.log("User list received:", userList);
}, error => {
  console.log("User list fetching failed with error:", error);
}
);

The fetchNext() method returns an array of User objects.

Retrieve Particular User Details

Use getUser() to fetch a specific user’s details by UID.

TypeScript

let UID: string = "UID";
CometChat.getUser(UID).then(
  (user: CometChat.User) => {
      console.log("User details fetched for user:", user);
  }, (error: CometChat.CometChatException) => {
      console.log("User details fetching failed with error:", error);
  }
);

JavaScript

let UID = "UID";
CometChat.getUser(UID).then(
user => {
  console.log("User details fetched for user:", user);
}, error => {
  console.log("User details fetching failed with error:", error);
}
);

Parameter	Description
UID	The UID of the user to fetch

It returns the User object containing the details of the user.

Get Online User Count

Use getOnlineUserCount() to get the total number of online users in your app.

TypeScript

CometChat.getOnlineUserCount().then(
  (userCount: number) => {
      console.log("Total online user count:", userCount);
  }, (error: CometChat.CometChatException) => {
      console.log("Online user count fetching failed with error:", error);
  }
);

JavaScript

CometChat.getOnlineUserCount().then(
userCount => {
  console.log("Total online user count:", userCount);
}, error => {
  console.log("Online user count fetching failed with error:", error);
}
);

Returns the total online user count as a number.

---

Next Steps

User Presence

Track and subscribe to user online/offline status

Block Users

Block and unblock users from your application

User Management

Create, update, and delete users programmatically

Retrieve Conversations

Fetch conversation lists for your chat UI