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

> Display CometChat React UI Kit users with avatars, online status, search, filtering, selection callbacks, and conversation navigation.

<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-docs-llms-scoped-indexes/LJKChk9TClDdlDNo/images/49c5082a-users_overview_web_screens-701c604eb9c2d04dcaa8013fe409fcd9.png?fit=max&auto=format&n=LJKChk9TClDdlDNo&q=85&s=9b260de79cf868fea2f8e6f74071994e" 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-docs-llms-scoped-indexes/-nSFFcS2LLIkMyn9/images/8a79367f-users_listItemView_default_web_screens-701c604eb9c2d04dcaa8013fe409fcd9.png?fit=max&auto=format&n=-nSFFcS2LLIkMyn9&q=85&s=3d488bfcc9472ae457dc49678c4f8ab4" 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-docs-llms-scoped-indexes/cTCXebw8IhR7IiJw/images/3e262fef-users_listItemView_custom_web_screens-e5bb179fd08dc3089f3f6c8a608a62d3.png?fit=max&auto=format&n=cTCXebw8IhR7IiJw&q=85&s=92c85db3ceb147711c72af2b745162aa" 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-docs-llms-scoped-indexes/k6T3T5MNYFVb-kxX/images/f7433d40-users_leading_view-941e504d4acd9c4f23ccc7bc47d9f35e.png?fit=max&auto=format&n=k6T3T5MNYFVb-kxX&q=85&s=06c42341e4a9dc6e6aec748434bcc4fa" 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-docs-llms-scoped-indexes/zeinwsYvDYBDwir-/images/58d37616-users_trailing_view-3e754b1f9546412d2ab768abe6bbe8aa.png?fit=max&auto=format&n=zeinwsYvDYBDwir-&q=85&s=e846a962b2f56872f317ed01350d9325" 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-docs-llms-scoped-indexes/yGOD4hG5x8gw_zqp/images/77ffdb3f-users_title_view-7f900436f6b63a3e9d3434b6e6e7a1bc.png?fit=max&auto=format&n=yGOD4hG5x8gw_zqp&q=85&s=1f37d131f8008a06e02841fc6aea51d6" 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-docs-llms-scoped-indexes/qatN8AZO7PJYofUv/images/03a38d40-users_subtitleView_default_web_screens-47bbbf7864a0f4c75fd99548ba54240e.png?fit=max&auto=format&n=qatN8AZO7PJYofUv&q=85&s=5928beb3b9ab121cc9d0601f21128f08" 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-docs-llms-scoped-indexes/ZaDaKVdnqtokXiZK/images/aa816f8e-users_subtitleView_custom_web_screens-d71b9197c2c12c7d4639c5cf917d1f20.png?fit=max&auto=format&n=ZaDaKVdnqtokXiZK&q=85&s=1f994ae9e3f827d1fb71e49beb466280" 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-docs-llms-scoped-indexes/LUAnk4kNde8CLq7p/images/81b8e5e1-users_header_view-2071084a55d1482f304cfe15b621dacc.png?fit=max&auto=format&n=LUAnk4kNde8CLq7p&q=85&s=41a32ad86f1ef78de3651ca5c01f8536" 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-docs-llms-scoped-indexes/yGOD4hG5x8gw_zqp/images/7af49a8f-users_options_default_web_screens-2c5d3ec8890d1faa689d322c98b7eff0.png?fit=max&auto=format&n=yGOD4hG5x8gw_zqp&q=85&s=8c37abc99148809a8debab54989ca3b7" 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-docs-llms-scoped-indexes/Fa6hxbnaPB6CCDby/images/0b63f1e5-users_options_custom_web_screens-643d3b290d635ccce5e8079c2540760b.png?fit=max&auto=format&n=Fa6hxbnaPB6CCDby&q=85&s=7bd8ea35af981d9ff5be970f8467dc5f" 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-docs-llms-scoped-indexes/cTCXebw8IhR7IiJw/images/448b5518-users_style-269bf9feb319c99c79d270a1117f35b7.png?fit=max&auto=format&n=cTCXebw8IhR7IiJw&q=85&s=2c8d584bdaa7f12ae4bd444a469bfd63" 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` |


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