> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.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.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Component | `CometChatUsers` |
  | Package | `cometchat_chat_uikit` |
  | Import | `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';` |
  | Purpose | Scrollable list of all available users with search, avatars, names, and online/offline status indicators. |
  | Data props | `searchKeyword` · `usersRequestBuilder` |
  | Actions | `onSelection` · `onError` · `onBack` · `onItemTap` · `onItemLongPress` · `onLoad` · `onEmpty` — [details](#actions-and-events) |
  | View slots | `loadingStateView` · `emptyStateView` · `errorStateView` · `appBarOptions` · `subtitleView` · `listItemView` · `titleView` · `leadingView` · +1 more — [details](#custom-view-slots) |
  | Styling | `usersStyle` — the app `ThemeData` does not reach inside a kit widget, so scope colours here. |
  | Layout | Fills its parent — place it in an `Expanded` (or a sized box) inside a `Column`, or layout throws an unbounded-height error at render. |
  | Prerequisites | `CometChatUIKit` initialised and a user logged in. |
  | Full props | [35 props](#functionality) |
</Accordion>

`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 = CometChatUserStatus.online` |
| 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");
      },
    )
    ```
  </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 |
| - | - | - | - |
| `usersStyle` | `CometChatUsersStyle` | `const CometChatUsersStyle()` | Style object for this widget. The app `ThemeData` does not reach inside a kit widget, so scope colours here. |
| `scrollController` | `ScrollController?` | `null` | Optional scroll controller |
| `searchPlaceholder` | `String?` | `null` | Search placeholder text |
| `backButton` | `Widget?` | `null` | `backButton` back button |
| `showBackButton` | `bool` | `true` | Toggle back button |
| `searchBoxIcon` | `Widget?` | `null` | `searchBoxIcon` search box prefix icon |
| `hideSearch` | `bool` | `false` | Toggle search bar |
| `selectionMode` | `SelectionMode?` | `null` | Enable selection mode (`single` or `multiple`) |
| `onSelection` | `Function(List<User>?, BuildContext)?` | `null` | Called with the selected users when selection mode is confirmed. |
| `title` | `String?` | `null` | Custom app bar title |
| `loadingStateView` | `WidgetBuilder?` | `null` | `loadingStateView` is a parameter used to show the loading state view in case of loading |
| `emptyStateView` | `WidgetBuilder?` | `null` | `emptyStateView` returns view fow empty state |
| `errorStateView` | `WidgetBuilder?` | `null` | `errorStateView` is a parameter used to show the error state view in case of any error |
| `appBarOptions` | `List<Widget> Function(BuildContext context)?` | `null` | `appBarOptions` list of options to be visible in app bar |
| `usersStatusVisibility` | `bool?` | `true` | Show online/offline status indicator |
| `activateSelection` | `ActivateSelection?` | `null` | `activateSelection` lets the widget know if groups are allowed to be selected |
| `onError` | `OnError?` | `null` | Called when the list fails to load. |
| `onBack` | `VoidCallback?` | `null` | `onBack` callback triggered on closing a screen |
| `onItemTap` | `Function(BuildContext context, User)?` | `null` | Called when a user row is tapped. |
| `onItemLongPress` | `Function(BuildContext context, User)?` | `null` | Called when a user row is long-pressed. |
| `submitIcon` | `Widget?` | `null` | `submitIcon` will override the default submit icon |
| `hideAppbar` | `bool?` | `false` | Toggle app bar visibility |
| `height` | `double?` | `null` | `height` provides height to the widget |
| `width` | `double?` | `null` | `width` provides width to the widget |
| `stickyHeaderVisibility` | `bool?` | `false` | Show alphabetical sticky header |
| `searchKeyword` | `String?` | `null` | Pre-fill search keyword |
| `onLoad` | `OnLoad<User>?` | `null` | Called once the first page of users has loaded. |
| `onEmpty` | `OnEmpty?` | `null` | Called when the user list resolves with no results. |
| `subtitleView` | `Widget? Function(BuildContext, User)?` | `null` | Replaces the subtitle slot of each user row. |
| `listItemView` | `Widget Function(User)?` | `null` | Replaces the entire user row. Overrides the leading, title, subtitle and trailing slots. |
| `titleView` | `Widget? Function(BuildContext context, User user)?` | `null` | Replaces the title slot of each user row. |
| `leadingView` | `Widget? Function(BuildContext context, User user)?` | `null` | Replaces the leading slot of each user row — the avatar area by default. |
| `trailingView` | `Widget? Function(BuildContext context, User user)?` | `null` | Replaces the trailing slot of each user row. |
| `usersBloc` | `UsersBloc?` | `null` | External BLoC instance. Pass one to share list state with another widget instead of letting this one create its own. |
| `usersRequestBuilder` | `UsersRequestBuilder?` | `null` | `usersRequestBuilder` custom request builder for filtering users |

***

## 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 = CometChatUserStatus.online,
    )
    ```
  </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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.