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

Retrieve Logged In User Details

Use getLoggedInUser() to get the current user’s details. This method also verifies if a user is logged in — a rejected promise indicates 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.

The method returns a User object. Access the response data using getter methods:

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

Retrieve List of Users

Use UsersRequestBuilder to fetch users with filtering, searching, and pagination.

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

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

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

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

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. Access the response data using getter methods:

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

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

Returns a User object with the user’s details.

The method returns a User object. Access the response data using getter methods:

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