> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Searchable, scrollable list of all available users with avatar, name, and online/offline status.

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatUsers",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatUsers } from \"@cometchat/chat-uikit-react\";",
    "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
    "description": "Searchable, scrollable list of all available users with avatar, name, and online/offline status.",
    "cssRootClass": ".cometchat-users",
    "primaryOutput": {
      "prop": "onItemClick",
      "type": "(user: CometChat.User) => void"
    },
    "props": {
      "data": {
        "usersRequestBuilder": {
          "type": "CometChat.UsersRequestBuilder",
          "default": "SDK default (30 per page)",
          "note": "Pass the builder, not the result of .build()"
        },
        "searchRequestBuilder": {
          "type": "CometChat.UsersRequestBuilder",
          "default": "undefined"
        },
        "activeUser": {
          "type": "CometChat.User",
          "default": "undefined"
        },
        "searchKeyword": {
          "type": "string",
          "default": "\"\""
        },
        "sectionHeaderKey": {
          "type": "keyof CometChat.User",
          "default": "getName"
        }
      },
      "callbacks": {
        "onItemClick": "(user: CometChat.User) => void",
        "onSelect": "(user: CometChat.User, selected: boolean) => void",
        "onError": "((error: CometChat.CometChatException) => void) | null",
        "onEmpty": "() => void"
      },
      "visibility": {
        "hideSearch": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "hideUserStatus": { "type": "boolean", "default": false },
        "showSectionHeader": { "type": "boolean", "default": true },
        "showScrollbar": { "type": "boolean", "default": false },
        "showSelectedUsersPreview": { "type": "boolean", "default": false }
      },
      "behavior": {
        "disableLoadingState": { "type": "boolean", "default": false }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["SelectionMode.single (0)", "SelectionMode.multiple (1)", "SelectionMode.none (2)"],
          "default": "SelectionMode.none"
        }
      },
      "viewSlots": {
        "itemView": "(user: CometChat.User) => JSX.Element",
        "leadingView": "(user: CometChat.User) => JSX.Element",
        "titleView": "(user: CometChat.User) => JSX.Element",
        "subtitleView": "(user: CometChat.User) => JSX.Element",
        "trailingView": "(user: CometChat.User) => JSX.Element",
        "headerView": "JSX.Element",
        "loadingView": "JSX.Element",
        "emptyView": "JSX.Element",
        "errorView": "JSX.Element",
        "options": "(user: CometChat.User) => CometChatOption[]"
      }
    },
    "events": [],
    "subscribedEvents": [
      {
        "name": "CometChatUserEvents.ccUserBlocked",
        "payload": "CometChat.User",
        "description": "Updates blocked user in list"
      },
      {
        "name": "CometChatUserEvents.ccUserUnblocked",
        "payload": "CometChat.User",
        "description": "Updates unblocked user in list"
      }
    ],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline"
    ],
    "compositionExample": {
      "description": "User list wired to message view",
      "components": [
        "CometChatUsers",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "onItemClick emits CometChat.User -> pass to MessageHeader, MessageList, MessageComposer"
    },
    "types": {
      "CometChatOption": {
        "id": "string | undefined",
        "title": "string | undefined",
        "iconURL": "string | undefined",
        "onClick": "(() => void) | undefined"
      },
      "SelectionMode": {
        "single": 0,
        "multiple": 1,
        "none": 2
      }
    }
  }
  ```
</Accordion>

## Where It Fits

`CometChatUsers` is a contact list component. It renders all available users and emits the selected `CometChat.User` via `onItemClick`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard two-panel chat layout.

```tsx lines theme={null}
import { useState } from "react";
import {
  CometChatUsers,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import "@cometchat/chat-uikit-react/css-variables.css";

function ChatApp() {
  const [selectedUser, setSelectedUser] = useState<CometChat.User>();

  return (
    <div style={{ display: "flex", height: "100vh", width: "100vw" }}>
      <div style={{ width: 480, height: "100%" }}>
        <CometChatUsers onItemClick={(user) => setSelectedUser(user)} />
      </div>
      {selectedUser ? (
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          <CometChatMessageHeader user={selectedUser} />
          <CometChatMessageList user={selectedUser} />
          <CometChatMessageComposer user={selectedUser} />
        </div>
      ) : (
        <div style={{ flex: 1, display: "grid", placeItems: "center", background: "#F5F5F5", color: "#727272" }}>
          Select a user
        </div>
      )}
    </div>
  );
}
```

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/sVDw7GNAn28WGWte/images/49c5082a-users_overview_web_screens-701c604eb9c2d04dcaa8013fe409fcd9.png?fit=max&auto=format&n=sVDw7GNAn28WGWte&q=85&s=64f49220ab6d78adf191519660c78cbf" width="1280" height="800" data-path="images/49c5082a-users_overview_web_screens-701c604eb9c2d04dcaa8013fe409fcd9.png" />
</Frame>

***

## Minimal Render

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function UsersDemo() {
  return (
    <div style={{ width: "100%", height: "100%" }}>
      <CometChatUsers />
    </div>
  );
}

export default UsersDemo;
```

Root CSS class: `.cometchat-users`

***

## Filtering Users

Pass a `CometChat.UsersRequestBuilder` to `usersRequestBuilder`. Pass the builder instance — not the result of `.build()`.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function FilteredUsers() {
  return (
    <CometChatUsers
      usersRequestBuilder={
        new CometChat.UsersRequestBuilder().friendsOnly(true).setLimit(15)
      }
    />
  );
}
```

### Filter Recipes

| Recipe               | Code                                                                   |
| -------------------- | ---------------------------------------------------------------------- |
| Friends only         | `new CometChat.UsersRequestBuilder().friendsOnly(true)`                |
| Online users only    | `new CometChat.UsersRequestBuilder().setStatus("online")`              |
| Limit to 15 per page | `new CometChat.UsersRequestBuilder().setLimit(15)`                     |
| Search by keyword    | `new CometChat.UsersRequestBuilder().setSearchKeyword("alice")`        |
| Hide blocked users   | `new CometChat.UsersRequestBuilder().hideBlockedUsers(true)`           |
| Filter by roles      | `new CometChat.UsersRequestBuilder().setRoles(["admin", "moderator"])` |
| Filter by tags       | `new CometChat.UsersRequestBuilder().setTags(["vip"])`                 |
| Specific UIDs        | `new CometChat.UsersRequestBuilder().setUIDs(["uid1", "uid2"])`        |

Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.

A separate `searchRequestBuilder` can be passed to filter the search list independently from the main list.

Refer to [UsersRequestBuilder](/sdk/javascript/retrieve-users) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemClick

Fires when a user row is tapped. Primary navigation hook — set the active user and render the message view.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function UsersWithClick() {
  const handleItemClick = (user: CometChat.User) => {
    console.log("Selected:", user.getName());
  };

  return <CometChatUsers onItemClick={handleItemClick} />;
}
```

#### onSelect

Fires when a user is checked/unchecked in selection mode. Requires `selectionMode` to be set.

```tsx lines theme={null}
import { useState } from "react";
import {
  CometChatUsers,
  SelectionMode,
} from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function BatchSelectDemo() {
  const [selected, setSelected] = useState<Set<string>>(new Set());

  const handleSelect = (user: CometChat.User, isSelected: boolean) => {
    setSelected((prev) => {
      const next = new Set(prev);
      const uid = user.getUid();
      isSelected ? next.add(uid) : next.delete(uid);
      return next;
    });
  };

  return (
    <CometChatUsers
      selectionMode={SelectionMode.multiple}
      onSelect={handleSelect}
    />
  );
}
```

#### onEmpty

Fires when the user list fetch returns zero results.

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";

function UsersWithEmptyHandler() {
  return (
    <CometChatUsers onEmpty={() => console.log("No users available")} />
  );
}
```

#### onError

Fires on internal errors (network failure, auth issue, SDK exception).

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function UsersWithErrorHandler() {
  return (
    <CometChatUsers
      onError={(error: CometChat.CometChatException) => {
        console.error("CometChatUsers error:", error);
      }}
    />
  );
}
```

### Global UI Events

The component subscribes to `CometChatUserEvents` internally:

| Event                                 | Internal behavior                      |
| ------------------------------------- | -------------------------------------- |
| `CometChatUserEvents.ccUserBlocked`   | Updates the blocked user in the list   |
| `CometChatUserEvents.ccUserUnblocked` | Updates the unblocked user in the list |

`CometChatUsers` does not emit any custom UI events.

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.

| SDK Listener    | Internal behavior                        |
| --------------- | ---------------------------------------- |
| `onUserOnline`  | Updates the user's status dot to online  |
| `onUserOffline` | Updates the user's status dot to offline |

Automatic: user presence changes (online/offline), blocked/unblocked state.

<Note>
  In React 18 StrictMode, `useEffect` runs twice on mount in development. The component handles listener cleanup internally, but any additional listeners added alongside the component need cleanup in the `useEffect` return function to avoid duplicate event handling.
</Note>

***

## Custom View Slots

Each slot replaces a section of the default UI. Slots that accept a user parameter receive the `CometChat.User` object for that row.

| Slot           | Signature                                     | Replaces                     |
| -------------- | --------------------------------------------- | ---------------------------- |
| `itemView`     | `(user: CometChat.User) => JSX.Element`       | Entire list item row         |
| `leadingView`  | `(user: CometChat.User) => JSX.Element`       | Avatar / left section        |
| `titleView`    | `(user: CometChat.User) => JSX.Element`       | Name / title text            |
| `subtitleView` | `(user: CometChat.User) => JSX.Element`       | Subtitle text                |
| `trailingView` | `(user: CometChat.User) => JSX.Element`       | Right section                |
| `headerView`   | `JSX.Element`                                 | Entire header bar            |
| `loadingView`  | `JSX.Element`                                 | Loading spinner              |
| `emptyView`    | `JSX.Element`                                 | Empty state                  |
| `errorView`    | `JSX.Element`                                 | Error state                  |
| `options`      | `(user: CometChat.User) => CometChatOption[]` | Context menu / hover actions |

### itemView

Replace the entire list item row.

Default:

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/oaJbJ0bOxG69pJ1L/images/8a79367f-users_listItemView_default_web_screens-701c604eb9c2d04dcaa8013fe409fcd9.png?fit=max&auto=format&n=oaJbJ0bOxG69pJ1L&q=85&s=93506543b909c123654bec49ad73e97c" width="1280" height="800" data-path="images/8a79367f-users_listItemView_default_web_screens-701c604eb9c2d04dcaa8013fe409fcd9.png" />
</Frame>

Customized:

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/QxoaCZzLrVi321Ps/images/3e262fef-users_listItemView_custom_web_screens-e5bb179fd08dc3089f3f6c8a608a62d3.png?fit=max&auto=format&n=QxoaCZzLrVi321Ps&q=85&s=3297c198e3cf1cc27f7a19503ee3a19e" width="1280" height="800" data-path="images/3e262fef-users_listItemView_custom_web_screens-e5bb179fd08dc3089f3f6c8a608a62d3.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers, CometChatListItem } from "@cometchat/chat-uikit-react";

    function UsersDemo() {
      const getItemView = (user: CometChat.User) => {
        const status = user.getStatus();

        return (
          <div
            className={`cometchat-users__list-item cometchat-users__list-item-${status}
              ${status === "online" ? `cometchat-users__list-item-active` : ""}
              `}
          >
            <CometChatListItem
              title={user.getName()}
              subtitleView={user.getStatus()}
              avatarURL={user.getAvatar()}
              avatarName={user.getName()}
            />
          </div>
        );
      };

      return <CometChatUsers itemView={getItemView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .cometchat .cometchat-users .cometchat-list-item__body-subtitle {
      overflow: hidden;
      color: #727272;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: 400 14px/16.8px Roboto;
    }

    .cometchat .cometchat-users .cometchat-users__list-item-active .cometchat-list-item {
      background: rgba(9, 194, 111, 0.1);
    }
    ```
  </Tab>
</Tabs>

### leadingView

Replace the avatar / left section.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/Mh-tK73gC5erLrBQ/images/f7433d40-users_leading_view-941e504d4acd9c4f23ccc7bc47d9f35e.png?fit=max&auto=format&n=Mh-tK73gC5erLrBQ&q=85&s=141caa730acc04909c9786a398605a20" width="1280" height="800" data-path="images/f7433d40-users_leading_view-941e504d4acd9c4f23ccc7bc47d9f35e.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers, CometChatAvatar } from "@cometchat/chat-uikit-react";

    function LeadingViewUsers() {
      const getLeadingView = (user: CometChat.User) => {
        return (
          <div className="users__leading-view">
            <CometChatAvatar
              image={user.getAvatar()}
              name={user.getName()}
            />
          </div>
        );
      };

      return <CometChatUsers leadingView={getLeadingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .cometchat-users .cometchat-list-item .users__leading-view .cometchat-avatar__image,
    .cometchat-users .cometchat-list-item .users__leading-view .cometchat-avatar {
      border-radius: 8px;
      height: 48px;
      width: 48px;
    }

    .users__leading-view {
      position: relative;
    }
    ```
  </Tab>
</Tabs>

### trailingView

Replace the right section.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/v4EbHQCGZ54oJcmr/images/58d37616-users_trailing_view-3e754b1f9546412d2ab768abe6bbe8aa.png?fit=max&auto=format&n=v4EbHQCGZ54oJcmr&q=85&s=440e48b2a7b89de6f0279a18c4e44340" width="1280" height="800" data-path="images/58d37616-users_trailing_view-3e754b1f9546412d2ab768abe6bbe8aa.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function TrailingViewUsers() {
      const getTrailingView = (user: CometChat.User) => {
        const tag = user.getTags()?.[0] ?? "";
        return (
          <div className="users__trailing-view">
            <span className="users__trailing-view-text">{tag}</span>
          </div>
        );
      };

      return <CometChatUsers trailingView={getTrailingView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .users__trailing-view {
      display: flex;
      width: 33px;
      padding: 5px 3px;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      gap: 3px;
      border-radius: 4px;
      background: #6852d6;
    }

    .users__trailing-view-text {
      font: 600 8px Inter;
      color: white;
    }
    ```
  </Tab>
</Tabs>

### titleView

Replace the name / title text. Role badge inline example.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/dDWpooIQ48haNjyU/images/77ffdb3f-users_title_view-7f900436f6b63a3e9d3434b6e6e7a1bc.png?fit=max&auto=format&n=dDWpooIQ48haNjyU&q=85&s=73f8d7d9eadd9edd77e5f722fb7bd5d2" width="1280" height="800" data-path="images/77ffdb3f-users_title_view-7f900436f6b63a3e9d3434b6e6e7a1bc.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function TitleViewUsers() {
      const getTitleView = (user: CometChat.User) => {
        return (
          <div className="users__title-view">
            <span className="users__title-view-name">{user.getName()}</span>
            <span className="users__title-view-type">{user.getRole()}</span>
          </div>
        );
      };

      return <CometChatUsers titleView={getTitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .users__title-view {
      display: flex;
      align-items: center;
      gap: 4px;
      align-self: stretch;
    }

    .users__title-view-name {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 500 16px Roboto;
    }

    .users__title-view-type {
      color: #fff;
      font: 600 8px Roboto;
      display: flex;
      height: 15px;
      padding: 1px 3px;
      justify-content: center;
      align-items: center;
      border-radius: 7px;
      background: #09c26f;
    }
    ```
  </Tab>
</Tabs>

### subtitleView

Replace the subtitle text for each user.

Default:

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/8ODUflBxloB1jkgP/images/03a38d40-users_subtitleView_default_web_screens-47bbbf7864a0f4c75fd99548ba54240e.png?fit=max&auto=format&n=8ODUflBxloB1jkgP&q=85&s=68babeabdf677750a46ec79b3eede8b5" width="1280" height="800" data-path="images/03a38d40-users_subtitleView_default_web_screens-47bbbf7864a0f4c75fd99548ba54240e.png" />
</Frame>

Customized:

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/THlknidvlbNx5AzI/images/aa816f8e-users_subtitleView_custom_web_screens-d71b9197c2c12c7d4639c5cf917d1f20.png?fit=max&auto=format&n=THlknidvlbNx5AzI&q=85&s=4d5c236251a07d6b50a48a053a740b42" width="1280" height="800" data-path="images/aa816f8e-users_subtitleView_custom_web_screens-d71b9197c2c12c7d4639c5cf917d1f20.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import { CometChatUsers } from "@cometchat/chat-uikit-react";

    function SubtitleViewUsers() {
      const getSubtitleView = (user: CometChat.User) => {
        return (
          <div className="users-subtitle">
            Last Active At: {new Date(user.getLastActiveAt() * 1000).toLocaleString()}
          </div>
        );
      };

      return <CometChatUsers subtitleView={getSubtitleView} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .users-subtitle {
      overflow: hidden;
      color: #727272;
      text-overflow: ellipsis;
      white-space: nowrap;
      font: 400 14px/120% sans-serif;
    }
    ```
  </Tab>
</Tabs>

### headerView

Replace the entire header bar.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/NuY3hD_g_g_X-fwH/images/81b8e5e1-users_header_view-2071084a55d1482f304cfe15b621dacc.png?fit=max&auto=format&n=NuY3hD_g_g_X-fwH&q=85&s=0edd88456e2f1abd39526771a3d66eb1" width="1280" height="406" data-path="images/81b8e5e1-users_header_view-2071084a55d1482f304cfe15b621dacc.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import {
      CometChatUsers,
      CometChatButton,
      getLocalizedString,
    } from "@cometchat/chat-uikit-react";

    function CustomHeaderUsers() {
      return (
        <CometChatUsers
          headerView={
            <div className="users__header">
              <div className="users__header__title">
                {getLocalizedString("user_title")}
              </div>
              <CometChatButton onClick={() => { /* handle click */ }} />
            </div>
          }
        />
      );
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .users__header {
      display: flex;
      width: 100%;
      padding: 8px 16px;
      align-items: center;
      justify-content: space-between;
      gap: 12px;
      border-radius: 10px;
      border: 1px solid #e8e8e8;
      background: #edeafa;
    }

    .users__header__title {
      overflow: hidden;
      color: #141414;
      text-overflow: ellipsis;
      font: 700 24px Roboto;
    }

    .users__header .cometchat-button .cometchat-button__icon {
      background: #141414;
    }

    .users__header .cometchat-button {
      width: 24px;
      border: none;
      background: transparent;
      border-radius: 0;
    }
    ```
  </Tab>
</Tabs>

### options

Replace the context menu / hover actions on each user item.

Default:

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/tiy_c-4NywbKIGIr/images/7af49a8f-users_options_default_web_screens-2c5d3ec8890d1faa689d322c98b7eff0.png?fit=max&auto=format&n=tiy_c-4NywbKIGIr&q=85&s=3739b6cfcabee198f3ae06ce14a009f3" width="1280" height="800" data-path="images/7af49a8f-users_options_default_web_screens-2c5d3ec8890d1faa689d322c98b7eff0.png" />
</Frame>

Customized:

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/KVBs_L3B6NmQumhv/images/0b63f1e5-users_options_custom_web_screens-643d3b290d635ccce5e8079c2540760b.png?fit=max&auto=format&n=KVBs_L3B6NmQumhv&q=85&s=5925786b6cd776a5dc11ae457ba6978c" width="1280" height="800" data-path="images/0b63f1e5-users_options_custom_web_screens-643d3b290d635ccce5e8079c2540760b.png" />
</Frame>

<Tabs>
  <Tab title="TypeScript">
    ```tsx lines theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    import {
      CometChatOption,
      CometChatUsers,
    } from "@cometchat/chat-uikit-react";

    function CustomOptionsUsers() {
      const getOptions = (user: CometChat.User) => [
        new CometChatOption({
          id: "delete",
          title: "Delete",
          onClick: () => { /* delete logic */ },
        }),
        new CometChatOption({
          id: "block",
          title: "Block",
          onClick: () => { /* block logic */ },
        }),
      ];

      return <CometChatUsers options={getOptions} />;
    }
    ```
  </Tab>

  <Tab title="CSS">
    ```css lines theme={null}
    .cometchat .cometchat-users .cometchat-menu-list__menu {
      background: none;
    }
    ```
  </Tab>
</Tabs>

```ts lines theme={null}
// CometChatOption interface
interface CometChatOption {
  id?: string;       // Unique identifier
  title?: string;    // Display text
  iconURL?: string;  // Icon asset URL
  onClick?: () => void; // Click handler
}
```

***

## Common Patterns

### Custom empty state with CTA

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";

function EmptyStateUsers() {
  return (
    <CometChatUsers
      emptyView={
        <div style={{ textAlign: "center", padding: 40 }}>
          <p>No users found</p>
          <button onClick={() => { /* invite users */ }}>
            Invite users
          </button>
        </div>
      }
    />
  );
}
```

### Friends-only list with search

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function FriendsOnlyUsers() {
  return (
    <CometChatUsers
      usersRequestBuilder={
        new CometChat.UsersRequestBuilder().friendsOnly(true).setLimit(15)
      }
    />
  );
}
```

### Multi-select with preview strip

```tsx lines theme={null}
import { CometChatUsers, SelectionMode } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function MultiSelectUsers() {
  return (
    <CometChatUsers
      selectionMode={SelectionMode.multiple}
      showSelectedUsersPreview={true}
      onSelect={(user: CometChat.User, selected: boolean) => {
        console.log(user.getName(), selected);
      }}
    />
  );
}
```

### Hide all chrome — minimal list

```tsx lines theme={null}
import { CometChatUsers } from "@cometchat/chat-uikit-react";

function MinimalUsers() {
  return (
    <CometChatUsers
      hideSearch={true}
      hideUserStatus={true}
      showSectionHeader={false}
    />
  );
}
```

***

## CSS Architecture

The component uses CSS custom properties (design tokens) defined in `@cometchat/chat-uikit-react/css-variables.css`. The cascade:

1. Global tokens (e.g., `--cometchat-primary-color`, `--cometchat-background-color-01`) are set on the `.cometchat` root wrapper.
2. Component CSS (`.cometchat-users`) consumes these tokens via `var()` with fallback values.
3. Overrides target `.cometchat-users` descendant selectors in a global stylesheet.

To scope overrides to a single instance when multiple `CometChatUsers` exist on the same page, wrap the component in a container and scope selectors:

```css lines theme={null}
.sidebar-left .cometchat-users .cometchat-avatar {
  border-radius: 8px;
}
```

Overrides survive component updates because the component never sets inline styles on these elements — all styling flows through CSS classes and custom properties.

### Key Selectors

| Target            | Selector                                                          |
| ----------------- | ----------------------------------------------------------------- |
| Root              | `.cometchat-users`                                                |
| List item         | `.cometchat-users__list-item`                                     |
| Active item       | `.cometchat-users__list-item-active .cometchat-list-item`         |
| Online status     | `.cometchat-users__list-item-online .cometchat-list-item__status` |
| Avatar            | `.cometchat-users__list-item .cometchat-avatar`                   |
| Leading view      | `.cometchat-users__list-item .cometchat-list-item__leading-view`  |
| Body              | `.cometchat-users .cometchat-list-item__body`                     |
| Empty state       | `.cometchat-users__empty-state-view`                              |
| Error state       | `.cometchat-users__error-state-view`                              |
| Shimmer loading   | `.cometchat-users__shimmer`                                       |
| Shimmer item      | `.cometchat-users__shimmer-item`                                  |
| Shimmer avatar    | `.cometchat-users__shimmer-item-avatar`                           |
| Shimmer title     | `.cometchat-users__shimmer-item-title`                            |
| Selected preview  | `.cometchat-users__selected-preview`                              |
| Selected chip     | `.cometchat-users__selected-preview-chip`                         |
| Chip name         | `.cometchat-users__selected-preview-chip-name`                    |
| Chip close button | `.cometchat-users__selected-preview-chip-close-button`            |

### Example: Brand-themed users

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/_jsRdrzYcNj1bcHI/images/448b5518-users_style-269bf9feb319c99c79d270a1117f35b7.png?fit=max&auto=format&n=_jsRdrzYcNj1bcHI&q=85&s=3fd03dde10d6d1c3aa7192859c403168" width="1280" height="800" data-path="images/448b5518-users_style-269bf9feb319c99c79d270a1117f35b7.png" />
</Frame>

```css lines theme={null}
.cometchat .cometchat-users .cometchat-list__header-title {
  background-color: #fce9ea;
  color: #e5484d;
  font-family: "Times New Roman";
}

.cometchat .cometchat-users .cometchat-list-item__body-title {
  overflow: hidden;
  color: #141414;
  text-overflow: ellipsis;
  font-family: "Times New Roman";
}

.cometchat-list-item__leading-view {
  background: #f0999b;
  border-radius: 9.6px;
}
```

### Customization Matrix

| What to change                        | Where           | Property/API                                    | Example                                                                       |
| ------------------------------------- | --------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
| Override behavior on user interaction | Component props | `on<Event>` callbacks                           | `onItemClick={(u) => setActive(u)}`                                           |
| Filter which users appear             | Component props | `usersRequestBuilder`                           | `usersRequestBuilder={new CometChat.UsersRequestBuilder().friendsOnly(true)}` |
| Toggle visibility of UI elements      | Component props | `hide<Feature>` / `show<Feature>` boolean props | `hideSearch={true}`                                                           |
| Replace a section of the list item    | Component props | `<slot>View` render props                       | `itemView={(user) => <div>...</div>}`                                         |
| Change colors, fonts, spacing         | Global CSS      | Target `.cometchat-users` class                 | `.cometchat-users .cometchat-avatar { border-radius: 8px; }`                  |

***

## Props

All props are optional unless noted.

### activeUser

Highlights the specified user in the list.

|         |                  |
| ------- | ---------------- |
| Type    | `CometChat.User` |
| Default | `undefined`      |

Must be a reference-equal object from the SDK; a manually constructed object will not match.

***

### disableLoadingState

Disables the loading state while fetching users.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

Useful when updating the request builder without clearing the list.

***

### emptyView

Custom component displayed when there are no users.

|         |                      |
| ------- | -------------------- |
| Type    | `JSX.Element`        |
| Default | Built-in empty state |

***

### errorView

Custom component displayed when an error occurs.

|         |                      |
| ------- | -------------------- |
| Type    | `JSX.Element`        |
| Default | Built-in error state |

Hidden when `hideError={true}`.

***

### headerView

Custom component rendered as the entire header bar.

|         |                                       |
| ------- | ------------------------------------- |
| Type    | `JSX.Element`                         |
| Default | Built-in header with title and search |

***

### hideError

Hides the default and custom error views.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

Also suppresses `errorView` if set.

***

### hideSearch

Hides the default search bar.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### hideUserStatus

Hides the online/offline status indicator.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### itemView

Custom renderer for the entire list item row.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in list item                      |

***

### leadingView

Custom renderer for the avatar / left section.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in avatar                         |

***

### loadingView

Custom component displayed during the loading state.

|         |                  |
| ------- | ---------------- |
| Type    | `JSX.Element`    |
| Default | Built-in shimmer |

***

### onEmpty

Callback fired when the user list is empty.

|         |              |
| ------- | ------------ |
| Type    | `() => void` |
| Default | `undefined`  |

***

### onError

Callback fired when the component encounters an error.

|         |                                                           |
| ------- | --------------------------------------------------------- |
| Type    | `((error: CometChat.CometChatException) => void) \| null` |
| Default | `undefined`                                               |

***

### onItemClick

Callback fired when a user row is clicked.

|         |                                  |
| ------- | -------------------------------- |
| Type    | `(user: CometChat.User) => void` |
| Default | `undefined`                      |

***

### onSelect

Callback fired when a user is selected/deselected. Requires `selectionMode` to be set.

|         |                                                     |
| ------- | --------------------------------------------------- |
| Type    | `(user: CometChat.User, selected: boolean) => void` |
| Default | `undefined`                                         |

***

### options

Custom context menu / hover actions for each user item.

|         |                                               |
| ------- | --------------------------------------------- |
| Type    | `(user: CometChat.User) => CometChatOption[]` |
| Default | `undefined`                                   |

```ts lines theme={null}
class CometChatOption {
  id?: string;
  title?: string;
  iconURL?: string;
  onClick?: () => void;
}
```

***

### searchKeyword

Pre-fills the search and filters the user list.

|         |          |
| ------- | -------- |
| Type    | `string` |
| Default | `""`     |

***

### searchRequestBuilder

Request builder with search parameters to fetch users.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | `undefined`                     |

If the search input is not empty, the search keyword of this request builder is set to the text in the search input.

***

### sectionHeaderKey

The property on the user object used to extract the section header character.

|         |                        |
| ------- | ---------------------- |
| Type    | `keyof CometChat.User` |
| Default | `getName`              |

Only relevant when `showSectionHeader={true}`.

***

### selectionMode

Enables single or multi-select checkboxes on list items.

|         |                      |
| ------- | -------------------- |
| Type    | `SelectionMode`      |
| Default | `SelectionMode.none` |

```ts lines theme={null}
enum SelectionMode {
  single,    // 0
  multiple,  // 1
  none,      // 2
}
```

Must pair with `onSelect` to capture selections.

***

### showScrollbar

Shows the scrollbar in the user list.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

***

### showSectionHeader

Displays alphabetical section headers (A, B, C…).

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### showSelectedUsersPreview

Shows a preview strip of selected users when `selectionMode` is `multiple`.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `false`   |

Each chip displays avatar, name, and a close button to remove the user.

***

### subtitleView

Custom renderer for the subtitle text.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | `undefined`                             |

***

### titleView

Custom renderer for the name / title text.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in title                          |

***

### trailingView

Custom renderer for the right section.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(user: CometChat.User) => JSX.Element` |
| Default | Built-in trailing view                  |

***

### usersRequestBuilder

Controls which users load and in what order.

|         |                                 |
| ------- | ------------------------------- |
| Type    | `CometChat.UsersRequestBuilder` |
| Default | SDK default (30 per page)       |

Pass the builder instance, not the result of `.build()`.

***

## Events

`CometChatUsers` does not emit custom UI events. It subscribes to:

| Event                                 | Payload          | Internal behavior              |
| ------------------------------------- | ---------------- | ------------------------------ |
| `CometChatUserEvents.ccUserBlocked`   | `CometChat.User` | Updates blocked user in list   |
| `CometChatUserEvents.ccUserUnblocked` | `CometChat.User` | Updates unblocked user in list |

***

## CSS Selectors

| Target                     | Selector                                                          |
| -------------------------- | ----------------------------------------------------------------- |
| Root                       | `.cometchat-users`                                                |
| Hide scrollbar variant     | `.cometchat-users-hide-scrollbar`                                 |
| List item                  | `.cometchat-users__list-item`                                     |
| Active item                | `.cometchat-users__list-item-active .cometchat-list-item`         |
| Online status indicator    | `.cometchat-users__list-item-online .cometchat-list-item__status` |
| Avatar                     | `.cometchat-users__list-item .cometchat-avatar`                   |
| Leading view               | `.cometchat-users__list-item .cometchat-list-item__leading-view`  |
| Body                       | `.cometchat-users .cometchat-list-item__body`                     |
| Empty state                | `.cometchat-users__empty-state-view`                              |
| Empty state icon           | `.cometchat-users__empty-state-view-icon`                         |
| Empty state title          | `.cometchat-users__empty-state-view-body-title`                   |
| Empty state description    | `.cometchat-users__empty-state-view-body-description`             |
| Error state                | `.cometchat-users__error-state-view`                              |
| Error state icon           | `.cometchat-users__error-state-view-icon`                         |
| Error state title          | `.cometchat-users__error-state-view-body-title`                   |
| Error state description    | `.cometchat-users__error-state-view-body-description`             |
| Shimmer loading            | `.cometchat-users__shimmer`                                       |
| Shimmer item               | `.cometchat-users__shimmer-item`                                  |
| Shimmer avatar             | `.cometchat-users__shimmer-item-avatar`                           |
| Shimmer title              | `.cometchat-users__shimmer-item-title`                            |
| Selected preview           | `.cometchat-users__selected-preview`                              |
| Selected preview container | `.cometchat-users__selected-preview-container`                    |
| Selected chip              | `.cometchat-users__selected-preview-chip`                         |
| Chip avatar                | `.cometchat-users__selected-preview-chip .cometchat-avatar`       |
| Chip name                  | `.cometchat-users__selected-preview-chip-name`                    |
| Chip close button          | `.cometchat-users__selected-preview-chip-close-button`            |