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

RecipeCode
Friends onlynew CometChat.UsersRequestBuilder().friendsOnly(true)
Online users onlynew CometChat.UsersRequestBuilder().setStatus("online")
Limit to 15 per pagenew CometChat.UsersRequestBuilder().setLimit(15)
Search by keywordnew CometChat.UsersRequestBuilder().setSearchKeyword("alice")
Hide blocked usersnew CometChat.UsersRequestBuilder().hideBlockedUsers(true)
Filter by rolesnew CometChat.UsersRequestBuilder().setRoles(["admin", "moderator"])
Filter by tagsnew CometChat.UsersRequestBuilder().setTags(["vip"])
Specific UIDsnew 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 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.
EventFires whenPayload
ccUserBlockedThe logged-in user blocks another userCometChat.User
ccUserUnblockedThe logged-in user unblocks another userCometChat.User

SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.
SDK ListenerInternal behavior
onUserOnlineUpdates the user’s status dot to online
onUserOfflineUpdates 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.
SlotSignatureReplaces
ItemView(user: CometChat.User) => JSX.ElementEntire list item row
LeadingView(user: CometChat.User) => JSX.ElementAvatar / left section
TitleView(user: CometChat.User) => JSX.ElementName / title text
SubtitleView(user: CometChat.User) => JSX.ElementSubtitle text
TrailingView(user: CometChat.User) => JSX.ElementRight section
LoadingView() => JSX.ElementLoading spinner
EmptyView() => JSX.ElementEmpty state
ErrorView() => JSX.ElementError state
AppBarOptions() => JSX.ElementHeader bar options

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

PropertyTypeDescription
containerStyleViewStyleStyle for the root container
headerStyleViewStyleStyle for the header section
titleStyleTextStyleStyle for the header title
titleSeparatorStyleViewStyleStyle for section header separators
itemStyleobjectStyle for list items (includes avatarStyle, titleStyle, subtitleStyle)
searchStyleobjectStyle for the search bar

Props

All props are optional unless noted.

EmptyView

Custom component displayed when there are no users.
Type() => JSX.Element
DefaultBuilt-in empty state

ErrorView

Custom component displayed when an error occurs.
Type() => JSX.Element
DefaultBuilt-in error state

hideError

Hides the error state view.
Typeboolean
Defaultfalse

hideHeader

Hides the entire header bar.
Typeboolean
Defaultfalse

hideLoadingState

Hides the loading state while fetching users.
Typeboolean
Defaultfalse

hideSearch

Hides the search bar.
Typeboolean
Defaultfalse

hideSubmitButton

Hides the submit button when selection mode is enabled.
Typeboolean
Defaulttrue

ItemView

Custom renderer for the entire list item row.
Type(user: CometChat.User) => JSX.Element
DefaultBuilt-in list item

LeadingView

Custom renderer for the avatar / left section.
Type(user: CometChat.User) => JSX.Element
DefaultBuilt-in avatar

LoadingView

Custom component displayed during the loading state.
Type() => JSX.Element
DefaultBuilt-in loading indicator

onBack

Callback fired when the back button is pressed.
Type() => void
Defaultundefined

onEmpty

Callback fired when the user list is empty.
Type() => void
Defaultundefined

onError

Callback fired when the component encounters an error.
Type(error: CometChat.CometChatException) => void
Defaultundefined

onItemLongPress

Callback fired when a user row is long-pressed.
Type(user: CometChat.User) => void
Defaultundefined

onItemPress

Callback fired when a user row is tapped.
Type(user: CometChat.User) => void
Defaultundefined

onLoad

Callback fired when users are loaded.
Type(list: CometChat.User[]) => void
Defaultundefined

onSelection

Callback fired when users are selected/deselected. Requires selectionMode to be set.
Type(list: CometChat.User[]) => void
Defaultundefined

onSubmit

Callback fired when the submit button is pressed. Requires selectionMode to be set.
Type(list: Array<CometChat.User>) => void
Defaultundefined

searchKeyword

Pre-fills the search and filters the user list.
Typestring
Default""

searchRequestBuilder

Request builder with search parameters to fetch users.
TypeCometChat.UsersRequestBuilder
Defaultundefined

selectionMode

Enables single or multi-select mode on list items.
Type"single" | "multiple" | "none"
Default"none"

showBackButton

Shows the back button in the header.
Typeboolean
Defaultfalse

stickyHeaderVisibility

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

SubtitleView

Custom renderer for the subtitle text.
Type(user: CometChat.User) => JSX.Element
Defaultundefined

TitleView

Custom renderer for the name / title text.
Type(user: CometChat.User) => JSX.Element
DefaultBuilt-in title

TrailingView

Custom renderer for the right section.
Type(user: CometChat.User) => JSX.Element
DefaultBuilt-in trailing view

usersRequestBuilder

Controls which users load and in what order.
TypeCometChat.UsersRequestBuilder
DefaultSDK default (30 per page)
Pass the builder instance, not the result of .build().

usersStatusVisibility

Shows/hides the online/offline status indicator.
Typeboolean
Defaulttrue

title

Custom title for the header.
Typestring
Default"Users"

AppBarOptions

Custom component for the header bar options.
Type() => JSX.Element
Defaultundefined

addOptions

Function to append additional menu items to the default context menu.
Type(user: CometChat.User) => MenuItemInterface[]
Defaultundefined

options

Function to replace the default context menu items entirely.
Type(user: CometChat.User) => MenuItemInterface[]
Defaultundefined

searchPlaceholderText

Placeholder text for the search input.
Typestring
Default"Search"

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