> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onItemTap: (context, user) {
        // Navigate to chat with this user
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatUsers()));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatUsers(),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

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:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      usersRequestBuilder: UsersRequestBuilder()
        ..limit = 20
        ..friendsOnly = true,
    )
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onItemTap: (context, user) {
        // Navigate to chat screen
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a user row is long-pressed.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onItemLongPress: (context, user) {
        // Show context menu
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      selectionMode: SelectionMode.multiple,
      activateSelection: ActivateSelection.onClick,
      onSelection: (selectedUsers, context) {
        // Handle selected users
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onLoad: (userList) {
        debugPrint("Loaded ${userList.length}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      onEmpty: () {
        debugPrint("No users found");
      },
    )
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      leadingView: (context, user) {
        return CircleAvatar(
          child: Text(user.name?[0] ?? ""),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the name / title text.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      titleView: (context, user) {
        return Text(
          user.name ?? "",
          style: TextStyle(fontWeight: FontWeight.bold),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the user's name.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      subtitleView: (context, user) {
        return Text(
          user.status ?? "offline",
          maxLines: 1,
          overflow: TextOverflow.ellipsis,
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each user item.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      trailingView: (context, user) {
        return Text(user.role ?? "");
      },
    )
    ```
  </Tab>
</Tabs>

### List Item View

Replace the entire list item row.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      listItemView: (user) {
        return ListTile(
          leading: CircleAvatar(child: Text(user.name?[0] ?? "")),
          title: Text(user.name ?? ""),
          subtitle: Text(user.status ?? "offline"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      emptyStateView: (context) => Center(child: Text("No users found")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      hideAppbar: true,
      hideSearch: true,
      stickyHeaderVisibility: false,
    )
    ```
  </Tab>
</Tabs>

### Friends-only list

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      usersRequestBuilder: UsersRequestBuilder()
        ..friendsOnly = true,
    )
    ```
  </Tab>
</Tabs>

### Online users only

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      usersRequestBuilder: UsersRequestBuilder()
        ..userStatus = CometChatConstants.userStatusOnline,
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `UsersBloc` to override behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      usersBloc: CustomUsersBloc(),
    )
    ```
  </Tab>
</Tabs>

### Extending UsersBloc

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    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);
      }
    }
    ```
  </Tab>
</Tabs>

For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/ui-kit/flutter/customization-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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatUsers(
      usersStyle: CometChatUsersStyle(
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        statusIndicatorStyle: CometChatStatusIndicatorStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

### Style Properties

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

See [Component Styling](/ui-kit/flutter/component-styling) for the full reference.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/conversations">
    Browse recent conversations
  </Card>

  <Card title="Groups" icon="users" href="/ui-kit/flutter/groups">
    Browse and search available groups
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Message Template" icon="puzzle-piece" href="/ui-kit/flutter/message-template">
    Customize message bubble structure
  </Card>
</CardGroup>