Users

Scrollable list of all available users with search, avatars, names, and online/offline status indicators.

CometChatUsers renders a scrollable list of all available users with real-time presence updates, search, avatars, and online/offline status indicators.

---

Where It Fits

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

Dart

CometChatUsers(
  onItemTap: (context, user) {
    // Navigate to chat with this user
  },
)

---

Quick Start

Using Navigator:

Dart

Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatUsers()));

Embedding as a widget:

Dart

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: CometChatUsers(),
    ),
  );
}

Prerequisites: CometChat SDK initialized with CometChatUIKit.init(), a user logged in, and the UI Kit dependency added.

---

Filtering Users

Pass a UsersRequestBuilder to control what loads:

Dart

CometChatUsers(
  usersRequestBuilder: UsersRequestBuilder()
    ..limit = 20
    ..friendsOnly = true,
)

Filter Recipes

Recipe	Builder property
Friends only	..friendsOnly = true
Limit per page	..limit = 10
Search by keyword	..searchKeyword = "john"
Hide blocked users	..hideBlockedUsers = true
Filter by roles	..roles = ["admin", "moderator"]
Filter by tags	..tags = ["vip"]
Online users only	..userStatus = CometChatConstants.userStatusOnline
Filter by UIDs	..UIDs = ["uid1", "uid2"]

---

Actions and Events

Callback Methods

onItemTap

Fires when a user row is tapped. Primary navigation hook.

Dart

CometChatUsers(
  onItemTap: (context, user) {
    // Navigate to chat screen
  },
)

onItemLongPress

Fires when a user row is long-pressed.

Dart

CometChatUsers(
  onItemLongPress: (context, user) {
    // Show context menu
  },
)

onBack

Fires when the user presses the back button in the app bar.

Dart

CometChatUsers(
  onBack: () {
    Navigator.pop(context);
  },
)

onSelection

Fires when users are selected/deselected in multi-select mode.

Dart

CometChatUsers(
  selectionMode: SelectionMode.multiple,
  activateSelection: ActivateSelection.onClick,
  onSelection: (selectedUsers, context) {
    // Handle selected users
  },
)

onError

Fires on internal errors.

Dart

CometChatUsers(
  onError: (e) {
    debugPrint("Error: ${e.message}");
  },
)

onLoad

Fires when the list is successfully fetched and loaded.

Dart

CometChatUsers(
  onLoad: (userList) {
    debugPrint("Loaded ${userList.length}");
  },
)

onEmpty

Fires when the list is empty after loading.

Dart

CometChatUsers(
  onEmpty: () {
    debugPrint("No users found");
  },
)

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

SDK Listener	Internal behavior
onUserOnline	Updates online status indicator for the user
onUserOffline	Updates offline status indicator for the user
Connection reconnected	Triggers silent refresh to sync user list

---

Functionality

Property	Type	Default	Description
title	String?	null	Custom app bar title
showBackButton	bool	true	Toggle back button
hideAppbar	bool?	false	Toggle app bar visibility
hideSearch	bool	false	Toggle search bar
usersStatusVisibility	bool?	true	Show online/offline status indicator
stickyHeaderVisibility	bool?	false	Show alphabetical sticky header
selectionMode	SelectionMode?	null	Enable selection mode (single or multiple)
searchPlaceholder	String?	null	Search placeholder text
searchKeyword	String?	null	Pre-fill search keyword

---

Custom View Slots

Leading View

Replace the avatar / left section.

Dart

CometChatUsers(
  leadingView: (context, user) {
    return CircleAvatar(
      child: Text(user.name?[0] ?? ""),
    );
  },
)

Title View

Replace the name / title text.

Dart

CometChatUsers(
  titleView: (context, user) {
    return Text(
      user.name ?? "",
      style: TextStyle(fontWeight: FontWeight.bold),
    );
  },
)

Subtitle View

Replace the subtitle text below the user’s name.

Dart

CometChatUsers(
  subtitleView: (context, user) {
    return Text(
      user.status ?? "offline",
      maxLines: 1,
      overflow: TextOverflow.ellipsis,
    );
  },
)

Trailing View

Replace the right section of each user item.

Dart

CometChatUsers(
  trailingView: (context, user) {
    return Text(user.role ?? "");
  },
)

List Item View

Replace the entire list item row.

Dart

CometChatUsers(
  listItemView: (user) {
    return ListTile(
      leading: CircleAvatar(child: Text(user.name?[0] ?? "")),
      title: Text(user.name ?? ""),
      subtitle: Text(user.status ?? "offline"),
    );
  },
)

State Views

Dart

CometChatUsers(
  emptyStateView: (context) => Center(child: Text("No users found")),
  errorStateView: (context) => Center(child: Text("Something went wrong")),
  loadingStateView: (context) => Center(child: CircularProgressIndicator()),
)

---

Common Patterns

Minimal list — hide all chrome

Dart

CometChatUsers(
  hideAppbar: true,
  hideSearch: true,
  stickyHeaderVisibility: false,
)

Friends-only list

Dart

CometChatUsers(
  usersRequestBuilder: UsersRequestBuilder()
    ..friendsOnly = true,
)

Online users only

Dart

CometChatUsers(
  usersRequestBuilder: UsersRequestBuilder()
    ..userStatus = CometChatConstants.userStatusOnline,
)

---

Advanced

BLoC Access

Provide a custom UsersBloc to override behavior:

Dart

CometChatUsers(
  usersBloc: CustomUsersBloc(),
)

Extending UsersBloc

UsersBloc uses the ListBase<User> mixin with override hooks:

Dart

class CustomUsersBloc extends UsersBloc {
  @override
  void onItemAdded(User item, List<User> updatedList) {
    // Custom sorting logic
    super.onItemAdded(item, updatedList);
  }

  @override
  void onListReplaced(List<User> previousList, List<User> newList) {
    // Filter out specific users
    final filtered = newList.where((u) => u.role != "bot").toList();
    super.onListReplaced(previousList, filtered);
  }
}

For ListBase override hooks (onItemAdded, onItemRemoved, onItemUpdated, onListCleared, onListReplaced), see BLoC & Data — ListBase Hooks.

Public BLoC Events

Event	Description
LoadUsers({searchKeyword, silent})	Load initial users. silent: true keeps existing list visible.
LoadMoreUsers()	Load next page (pagination)
RefreshUsers()	Refresh the list
SearchUsers(keyword)	Search users with debouncing
ToggleUserSelection(uid)	Toggle selection state
ClearUserSelection()	Clear all selections
UpdateUser(user)	Update a specific user

Public BLoC Methods

Method	Returns	Description
getStatusNotifier(uid)	ValueNotifier<String>	Per-user status notifier for isolated rebuilds
getUserStatus(uid)	String	Current status for a user (online / offline)

---

Style

Dart

CometChatUsers(
  usersStyle: CometChatUsersStyle(
    avatarStyle: CometChatAvatarStyle(
      borderRadius: BorderRadius.circular(8),
      backgroundColor: Color(0xFFFBAA75),
    ),
    statusIndicatorStyle: CometChatStatusIndicatorStyle(),
  ),
)

Style Properties

Property	Description
backgroundColor	List background color
avatarStyle	Avatar appearance
statusIndicatorStyle	Online/offline indicator
searchBoxStyle	Search box appearance

See Component Styling for the full reference.

---

Next Steps

Conversations

Browse recent conversations

Groups

Browse and search available groups

Component Styling

Detailed styling reference

Message Template

Customize message bubble structure