Skip to main content

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.

Minimal Render


Filtering Users

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

Filter Recipes

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

onItemLongPress

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

onSelection

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

onEmpty

Fires when the user list fetch returns zero results.

onError

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

onLoad

Fires when the list is successfully fetched and loaded.

Global UI Events

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

SDK Events (Real-Time, Automatic)

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

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.

ItemView

Replace the entire list item row.

LeadingView

Replace the avatar / left section.

SubtitleView

Replace the subtitle text.

TrailingView

Replace the right section.

AppBarOptions

Custom view for the header bar options.

options

Custom context menu actions for each user item.

Common Patterns

Custom empty state with CTA

Friends-only list

Multi-select with submit

Hide all chrome — minimal list


Styling

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

Style Properties


Props

All props are optional unless noted.

EmptyView

Custom component displayed when there are no users.

ErrorView

Custom component displayed when an error occurs.

hideError

Hides the error state view.

hideHeader

Hides the entire header bar.

hideLoadingState

Hides the loading state while fetching users.

hideSearch

Hides the search bar.

hideSubmitButton

Hides the submit button when selection mode is enabled.

ItemView

Custom renderer for the entire list item row.

LeadingView

Custom renderer for the avatar / left section.

LoadingView

Custom component displayed during the loading state.

onBack

Callback fired when the back button is pressed.

onEmpty

Callback fired when the user list is empty.

onError

Callback fired when the component encounters an error.

onItemLongPress

Callback fired when a user row is long-pressed.

onItemPress

Callback fired when a user row is tapped.

onLoad

Callback fired when users are loaded.

onSelection

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

onSubmit

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

searchKeyword

Pre-fills the search and filters the user list.

searchRequestBuilder

Request builder with search parameters to fetch users.

selectionMode

Enables single or multi-select mode on list items.

showBackButton

Shows the back button in the header.

stickyHeaderVisibility

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

SubtitleView

Custom renderer for the subtitle text.

TitleView

Custom renderer for the name / title text.

TrailingView

Custom renderer for the right section.

usersRequestBuilder

Controls which users load and in what order. Pass the builder instance, not the result of .build().

usersStatusVisibility

Shows/hides the online/offline status indicator.

title

Custom title for the header.

AppBarOptions

Custom component for the header bar options.

addOptions

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

options

Function to replace the default context menu items entirely.

searchPlaceholderText

Placeholder text for the search input.

Next Steps

Conversations

Display and manage the list of recent chats

Groups

Display and manage group conversations

Message List

Display the full chat interface after selecting a user

Component Styling

Customize the appearance of UI Kit components