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

# Users

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

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "component": "CometChatUsers",
    "package": "@cometchat/chat-uikit-react-native",
    "import": "import { CometChatUsers } from \"@cometchat/chat-uikit-react-native\";",
    "description": "Searchable, scrollable list of all available users with avatar, name, and online/offline status.",
    "primaryOutput": {
      "prop": "onItemPress",
      "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"
        },
        "searchKeyword": {
          "type": "string",
          "default": "\"\""
        }
      },
      "callbacks": {
        "onItemPress": "(user: CometChat.User) => void",
        "onItemLongPress": "(user: CometChat.User) => void",
        "onBack": "() => void",
        "onSelection": "(list: CometChat.User[]) => void",
        "onError": "(error: CometChat.CometChatException) => void",
        "onEmpty": "() => void",
        "onLoad": "(list: CometChat.User[]) => void",
        "onSubmit": "(list: Array<CometChat.User>) => void"
      },
      "visibility": {
        "hideHeader": { "type": "boolean", "default": false },
        "showBackButton": { "type": "boolean", "default": false },
        "hideSearch": { "type": "boolean", "default": false },
        "hideError": { "type": "boolean", "default": false },
        "stickyHeaderVisibility": { "type": "boolean", "default": true },
        "hideSubmitButton": { "type": "boolean", "default": true },
        "hideLoadingState": { "type": "boolean", "default": false },
        "usersStatusVisibility": { "type": "boolean", "default": true },
        "title": { "type": "string", "default": "\"Users\"" }
      },
      "selection": {
        "selectionMode": {
          "type": "SelectionMode",
          "values": ["single", "multiple", "none"],
          "default": "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",
        "LoadingView": "() => JSX.Element",
        "EmptyView": "() => JSX.Element",
        "ErrorView": "() => JSX.Element",
        "AppBarOptions": "() => JSX.Element"
      },
      "menu": {
        "options": "(user: CometChat.User) => MenuItemInterface[]",
        "addOptions": "(user: CometChat.User) => MenuItemInterface[]"
      },
      "search": {
        "searchPlaceholderText": { "type": "string", "default": "\"Search\"" }
      }
    },
    "events": [
      {
        "name": "ccUserBlocked",
        "payload": "CometChat.User",
        "description": "Triggered when logged-in user blocks another user"
      },
      {
        "name": "ccUserUnblocked",
        "payload": "CometChat.User",
        "description": "Triggered when logged-in user unblocks another user"
      }
    ],
    "sdkListeners": [
      "onUserOnline",
      "onUserOffline"
    ],
    "compositionExample": {
      "description": "User list wired to message view",
      "components": [
        "CometChatUsers",
        "CometChatMessageHeader",
        "CometChatMessageList",
        "CometChatMessageComposer"
      ],
      "flow": "onItemPress emits CometChat.User -> pass to MessageHeader, MessageList, MessageComposer"
    },
    "types": {
      "SelectionMode": {
        "single": "Select one user at a time",
        "multiple": "Select multiple users",
        "none": "No selection mode"
      }
    }
  }
  ```
</Accordion>

## Where It Fits

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

```tsx lines theme={null}
import { useState } from "react";
import { View, Text, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import {
  CometChatUsers,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatThemeProvider,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

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

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <View style={styles.container}>
            <View style={styles.sidebar}>
              <CometChatUsers onItemPress={(user) => setSelectedUser(user)} />
            </View>
            {selectedUser ? (
              <View style={styles.chatArea}>
                <CometChatMessageHeader user={selectedUser} />
                <CometChatMessageList user={selectedUser} />
                <CometChatMessageComposer user={selectedUser} />
              </View>
            ) : (
              <View style={styles.placeholder}>
                <Text>Select a user</Text>
              </View>
            )}
          </View>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, flexDirection: "row" },
  sidebar: { width: 350 },
  chatArea: { flex: 1 },
  placeholder: { flex: 1, justifyContent: "center", alignItems: "center" },
});
```

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/PaxBG9I1yMoeQmt2/images/358a0b21-users-4e1d9c895a8ae47d23ac0d6646db160b.png?fit=max&auto=format&n=PaxBG9I1yMoeQmt2&q=85&s=883ebbcc6e353ebf259c124b36875272" width="2560" height="1600" data-path="images/358a0b21-users-4e1d9c895a8ae47d23ac0d6646db160b.png" />
</Frame>

***

## Minimal Render

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

function UsersDemo() {
  return <CometChatUsers />;
}

export default UsersDemo;
```

***

## 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-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

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/react-native/retrieve-users) for the full builder API.

***

## Actions and Events

### Callback Props

#### onItemPress

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-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

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

  return <CometChatUsers onItemPress={handleItemPress} />;
}
```

#### onItemLongPress

Fires when a user item is long-pressed, allowing additional actions like block or report.

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

function UsersWithLongPress() {
  const handleLongPress = (user: CometChat.User) => {
    console.log("Long pressed:", user.getName());
  };

  return <CometChatUsers onItemLongPress={handleLongPress} />;
}
```

#### onSelection

Fires when users are selected/deselected in selection mode. Requires `selectionMode` to be set.

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

function UsersWithSelection() {
  const handleSelection = (list: CometChat.User[]) => {
    console.log("Selected:", list.length);
  };

  return (
    <CometChatUsers
      selectionMode="multiple"
      onSelection={handleSelection}
    />
  );
}
```

#### onEmpty

Fires when the user list fetch returns zero results.

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

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-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";

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

#### onLoad

Fires when the list is successfully fetched and loaded.

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

function UsersWithLoadHandler() {
  const handleLoad = (list: CometChat.User[]) => {
    console.log("Users loaded:", list.length);
  };

  return <CometChatUsers onLoad={handleLoad} />;
}
```

### Global UI Events

`CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

| Event             | Fires when                               | Payload          |
| ----------------- | ---------------------------------------- | ---------------- |
| `ccUserBlocked`   | The logged-in user blocks another user   | `CometChat.User` |
| `ccUserUnblocked` | The logged-in user unblocks another user | `CometChat.User` |

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

function useUserEvents() {
  useEffect(() => {
    const listenerId = "USER_EVENTS_" + Date.now();
    
    CometChatUIEventHandler.addUserListener(listenerId, {
      ccUserBlocked: (user: CometChat.User) => {
        console.log("Blocked:", user.getName());
      },
      ccUserUnblocked: (user: CometChat.User) => {
        console.log("Unblocked:", user.getName());
      },
    });

    return () => {
      CometChatUIEventHandler.removeUserListener(listenerId);
    };
  }, []);
}
```

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

***

## 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         |
| `LoadingView`   | `() => JSX.Element`                     | Loading spinner       |
| `EmptyView`     | `() => JSX.Element`                     | Empty state           |
| `ErrorView`     | `() => JSX.Element`                     | Error state           |
| `AppBarOptions` | `() => JSX.Element`                     | Header bar options    |

### ItemView

Replace the entire list item row.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/OOBJyP9hM0C-rAe_/images/de656dc8-users_list_item_view-e66a444aac7edcb18dec787a42b646c3.png?fit=max&auto=format&n=OOBJyP9hM0C-rAe_&q=85&s=33c92766d69cc7e841020d6c921ef90d" width="1280" height="800" data-path="images/de656dc8-users_list_item_view-e66a444aac7edcb18dec787a42b646c3.png" />
</Frame>

```tsx lines theme={null}
import {
  CometChatUsers,
  CometChatAvatar,
  useTheme,
} from "@cometchat/chat-uikit-react-native";
import { CometChat } from "@cometchat/chat-sdk-react-native";
import { View, Text } from "react-native";

function CustomItemViewUsers() {
  const theme = useTheme();

  const getItemView = (user: CometChat.User) => {
    return (
      <View
        style={{
          flexDirection: "row",
          flex: 1,
          paddingHorizontal: 16,
          paddingVertical: 12,
          alignItems: "center",
          borderWidth: 1,
          borderColor: theme.color.borderLight,
        }}>
        <CometChatAvatar
          name={user.getName()}
          image={{ uri: user.getAvatar() }}
          style={{
            containerStyle: { borderRadius: 8 },
            imageStyle: { borderRadius: 8 },
          }}
        />
        <Text
          style={{
            flex: 1,
            color: theme.color.textPrimary,
            fontSize: 16,
            marginLeft: 12,
            fontWeight: "500",
          }}
          numberOfLines={1}
          ellipsizeMode="tail">
          {user.getName()}
        </Text>
      </View>
    );
  };

  return <CometChatUsers ItemView={getItemView} />;
}
```

### LeadingView

Replace the avatar / left section.

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

function LeadingViewUsers() {
  const getLeadingView = (user: CometChat.User) => {
    return (
      <View
        style={{
          width: 40,
          height: 40,
          borderRadius: 20,
          backgroundColor: "#6852D6",
          justifyContent: "center",
          alignItems: "center",
        }}>
        <Text style={{ color: "white", fontWeight: "bold" }}>
          {user.getName().charAt(0)}
        </Text>
      </View>
    );
  };

  return <CometChatUsers LeadingView={getLeadingView} />;
}
```

### SubtitleView

Replace the subtitle text.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/2JiXkJ8lq6PmPGlJ/images/6e16192f-users_subtitle_view-51f448114408521010b6feb4a5bba41d.png?fit=max&auto=format&n=2JiXkJ8lq6PmPGlJ&q=85&s=6187cd3feabcfd9d04ce76314b70cc87" width="1280" height="800" data-path="images/6e16192f-users_subtitle_view-51f448114408521010b6feb4a5bba41d.png" />
</Frame>

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

function SubtitleViewUsers() {
  const getSubtitleView = (user: CometChat.User) => {
    return (
      <Text style={{ fontSize: 12, color: "#727272" }}>
        {user.getStatus() === "online" ? "Online" : "Offline"}
      </Text>
    );
  };

  return <CometChatUsers SubtitleView={getSubtitleView} />;
}
```

### TrailingView

Replace the right section.

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

function TrailingViewUsers() {
  const getTrailingView = (user: CometChat.User) => {
    return (
      <TouchableOpacity onPress={() => console.log("Follow:", user.getName())}>
        <Text style={{ color: "#6852D6", fontWeight: "500" }}>Follow</Text>
      </TouchableOpacity>
    );
  };

  return <CometChatUsers TrailingView={getTrailingView} />;
}
```

### AppBarOptions

Custom view for the header bar options.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/le8ibYc8lBJsShSE/images/50473531-user_menu-5b7eb7088d966ada9e751e591dbee212.png?fit=max&auto=format&n=le8ibYc8lBJsShSE&q=85&s=62a58348cde075a890d58f68a12a7ee3" width="1280" height="800" data-path="images/50473531-user_menu-5b7eb7088d966ada9e751e591dbee212.png" />
</Frame>

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

function AppBarOptionsUsers() {
  return (
    <CometChatUsers
      AppBarOptions={() => (
        <TouchableOpacity onPress={() => console.log("Settings pressed")}>
          <Text style={{ color: "#6852D6", fontWeight: "500" }}>Settings</Text>
        </TouchableOpacity>
      )}
    />
  );
}
```

### options

Custom context menu actions for each user item.

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

function OptionsUsers() {
  const getOptions = (user: CometChat.User) => [
    {
      text: "Block",
      onPress: () => console.log("Block:", user.getName()),
    },
    {
      text: "Report",
      onPress: () => console.log("Report:", user.getName()),
    },
  ];

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

***

## Common Patterns

### Custom empty state with CTA

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

function EmptyStateUsers() {
  return (
    <CometChatUsers
      EmptyView={() => (
        <View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 40 }}>
          <Text style={{ fontSize: 16, marginBottom: 16 }}>No users found</Text>
          <TouchableOpacity
            style={{ backgroundColor: "#6852D6", paddingHorizontal: 20, paddingVertical: 10, borderRadius: 8 }}
            onPress={() => console.log("Invite users")}>
            <Text style={{ color: "white" }}>Invite users</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}
```

### Friends-only list

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

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

### Multi-select with submit

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

function MultiSelectUsers() {
  const handleSubmit = (users: Array<CometChat.User>) => {
    console.log("Selected users:", users.length);
  };

  return (
    <CometChatUsers
      selectionMode="multiple"
      hideSubmitButton={false}
      onSubmit={handleSubmit}
    />
  );
}
```

### Hide all chrome — minimal list

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

function MinimalUsers() {
  return (
    <CometChatUsers
      hideSearch={true}
      usersStatusVisibility={false}
      stickyHeaderVisibility={false}
      hideHeader={true}
    />
  );
}
```

***

## Styling

The component uses the theme system from `CometChatThemeProvider`. Pass a `style` prop to customize the appearance.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/G6Puyz_3Zlaowa9R/images/c8909b74-users_styling-3acb1ffef7870b6903a070fd83b5103f.png?fit=max&auto=format&n=G6Puyz_3Zlaowa9R&q=85&s=18397b1b8f7cf63001b55db0f37d161d" width="1280" height="800" data-path="images/c8909b74-users_styling-3acb1ffef7870b6903a070fd83b5103f.png" />
</Frame>

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

function StyledUsers() {
  return (
    <CometChatUsers
      style={{
        titleStyle: {
          color: "#FBAA75",
        },
        titleSeparatorStyle: {
          borderBottomColor: "#FBAA75",
        },
        itemStyle: {
          avatarStyle: {
            containerStyle: {
              borderRadius: 8,
              backgroundColor: "#FBAA75",
            },
            imageStyle: {
              borderRadius: 8,
            },
          },
        },
      }}
    />
  );
}
```

### Style Properties

| Property              | Type        | Description                                                                  |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| `containerStyle`      | `ViewStyle` | Style for the root container                                                 |
| `headerStyle`         | `ViewStyle` | Style for the header section                                                 |
| `titleStyle`          | `TextStyle` | Style for the header title                                                   |
| `titleSeparatorStyle` | `ViewStyle` | Style for section header separators                                          |
| `itemStyle`           | `object`    | Style for list items (includes `avatarStyle`, `titleStyle`, `subtitleStyle`) |
| `searchStyle`         | `object`    | Style for the search bar                                                     |

***

## Props

All props are optional unless noted.

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

***

### hideError

Hides the error state view.

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

***

### hideHeader

Hides the entire header bar.

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

***

### hideLoadingState

Hides the loading state while fetching users.

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

***

### hideSearch

Hides the search bar.

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

***

### hideSubmitButton

Hides the submit button when selection mode is enabled.

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

***

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

***

### onBack

Callback fired when the back button is pressed.

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

***

### 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` |
| Default | `undefined`                                     |

***

### onItemLongPress

Callback fired when a user row is long-pressed.

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

***

### onItemPress

Callback fired when a user row is tapped.

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

***

### onLoad

Callback fired when users are loaded.

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

***

### onSelection

Callback fired when users are selected/deselected. Requires `selectionMode` to be set.

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

***

### onSubmit

Callback fired when the submit button is pressed. Requires `selectionMode` to be set.

|         |                                         |
| ------- | --------------------------------------- |
| Type    | `(list: Array<CometChat.User>) => void` |
| Default | `undefined`                             |

***

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

***

### selectionMode

Enables single or multi-select mode on list items.

|         |                                    |
| ------- | ---------------------------------- |
| Type    | `"single" \| "multiple" \| "none"` |
| Default | `"none"`                           |

***

### showBackButton

Shows the back button in the header.

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

***

### stickyHeaderVisibility

Shows/hides alphabetical section headers (A, B, C…).

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

***

### 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()`.

***

### usersStatusVisibility

Shows/hides the online/offline status indicator.

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

***

### title

Custom title for the header.

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

***

### AppBarOptions

Custom component for the header bar options.

|         |                     |
| ------- | ------------------- |
| Type    | `() => JSX.Element` |
| Default | `undefined`         |

***

### addOptions

Function to append additional menu items to the default context menu.

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

***

### options

Function to replace the default context menu items entirely.

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

***

### searchPlaceholderText

Placeholder text for the search input.

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/ui-kit/react-native/conversations">
    Display and manage the list of recent chats
  </Card>

  <Card title="Groups" icon="user-group" href="/ui-kit/react-native/groups">
    Display and manage group conversations
  </Card>

  <Card title="Message List" icon="message" href="/ui-kit/react-native/message-list">
    Display the full chat interface after selecting a user
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/react-native/component-styling">
    Customize the appearance of UI Kit components
  </Card>
</CardGroup>