CometChatGroups

A scrollable, searchable list of groups with real-time group events, group type indicators, selection modes, and infinite scroll pagination.

Overview

CometChatGroups displays a real-time list of groups in your CometChat app. It supports infinite scroll pagination, search with debounce, group type indicators (public/private/password-protected), single/multiple selection modes with shift-click range selection, and group mutations (create, join, leave, delete).

It offers two usage modes:

• Flat API — pass convenience props directly to <CometChatGroups /> for quick customization
• Compound API — use <CometChatGroups.Root> with sub-components for full layout control

Import

import { CometChatGroups } from '@cometchat/chat-uikit-react';

Quick Start

Flat API (Simple)

The flat API is the simplest way to render a group list. Pass props directly to <CometChatGroups />:

<CometChatGroups
  onItemClick={(group) => console.log('Selected:', group.getName())}
  subtitleView={(group) => <span>{group.getMembersCount()} members</span>}
/>

Compound API (Advanced)

Use the compound API for full control over layout and rendering. Place only the sub-components you need inside <CometChatGroups.Root>:

<CometChatGroups.Root selectionMode="multiple" onSelect={handleSelect}>
  <CometChatGroups.Header />
  <CometChatGroups.SearchBar />
  <CometChatGroups.LoadingState />
  <CometChatGroups.ErrorState />
  <CometChatGroups.EmptyState />
  <CometChatGroups.List />
</CometChatGroups.Root>

State sub-components (LoadingState, ErrorState, EmptyState) are self-managing — they read fetchState from context and automatically show/hide themselves. You don’t need conditional rendering.

Sub-Components

Component	Description
CometChatGroups.Root	Provider + default layout. Wraps children with context.
CometChatGroups.Header	Header with title text (defaults to “Groups”).
CometChatGroups.SearchBar	Debounced search input (300ms).
CometChatGroups.List	Group list with infinite scroll. Self-manages visibility based on fetch state.
CometChatGroups.Item	Individual group item (avatar, name, member count, type badge, selection control).
CometChatGroups.EmptyState	Self-managing — only renders when fetchState === 'empty'.
CometChatGroups.ErrorState	Self-managing — only renders when fetchState === 'error'.
CometChatGroups.LoadingState	Self-managing — only renders when fetchState === 'loading'.

Props

Flat API (<CometChatGroups />)

All Root props below, plus these convenience view props:

Prop	Type	Description
leadingView	(group: CometChat.Group) => ReactNode	Custom leading view per item (replaces avatar).
titleView	(group: CometChat.Group) => ReactNode	Custom title view per item.
subtitleView	(group: CometChat.Group) => ReactNode	Custom subtitle view per item.
trailingView	(group: CometChat.Group) => ReactNode	Custom trailing view per item.
itemView	(group: CometChat.Group) => ReactNode	Fully custom item (overrides all above).
headerView	ReactNode	Custom header (replaces default).
loadingView	ReactNode	Custom loading content.
errorView	ReactNode	Custom error content.
emptyView	ReactNode	Custom empty content.

CometChatGroups.Root

Prop	Type	Default	Description
requestBuilder	CometChat.GroupsRequestBuilder	limit 30	Custom request builder for fetching groups.
searchRequestBuilder	CometChat.GroupsRequestBuilder	—	Custom request builder for search queries.
searchKeyword	string	''	Initial search keyword.
hideGroupType	boolean	false	Whether to hide the group type badge (public/private/password).
selectionMode	'none' | 'single' | 'multiple'	'none'	Selection mode.
activeGroup	CometChat.Group	—	Group to highlight as active.
options	(group: CometChat.Group) => CometChatGroupOption[]	—	Context menu options per group.
onItemClick	(group: CometChat.Group) => void	—	Callback when a group is clicked. Used for sibling component communication.
onSelect	(group: CometChat.Group, selected: boolean) => void	—	Callback when selection changes.
onError	(error: unknown) => void	—	Callback when an error occurs.
onEmpty	() => void	—	Callback when the list is empty.
showScrollbar	boolean	false	Show the native scrollbar on the list.
children	ReactNode	—	Custom layout. If omitted, renders default.

CometChatGroups.Header

Prop	Type	Default	Description
title	string	'Groups'	Custom title text.
children	ReactNode	—	Custom header content (replaces default).

CometChatGroups.SearchBar

Prop	Type	Default	Description
placeholder	string	'Search groups'	Placeholder text for the search input.

CometChatGroups.List

Prop	Type	Default	Description
itemView	(group: CometChat.Group) => ReactNode	—	Custom render function for each group item.

CometChatGroups.Item

Prop	Type	Default	Description
group	CometChat.Group	required	The group to render.
isActive	boolean	—	Override active state.
leadingView	ReactNode	—	Custom leading view (replaces avatar).
titleView	ReactNode	—	Custom title view.
subtitleView	ReactNode	—	Custom subtitle view (replaces member count).
trailingView	ReactNode	—	Custom trailing view (replaces selection control).

CometChatGroups.EmptyState

Prop	Type	Default	Description
children	ReactNode	—	Custom empty state content (replaces default).

CometChatGroups.ErrorState

Prop	Type	Default	Description
children	ReactNode	—	Custom error state content (replaces default).

CometChatGroups.LoadingState

Prop	Type	Default	Description
children	ReactNode	—	Custom loading state content (replaces default shimmer).

Sibling Communication with onItemClick

The onItemClick callback enables communication between sibling components. The parent component owns the shared state and passes it down:

import { CometChatGroups } from '@cometchat/chat-uikit-react';
import { CometChatMessageList } from '@cometchat/chat-uikit-react';
import { useState } from 'react';
import { CometChat } from '@cometchat/chat-sdk-javascript';

function ChatApp() {
  const [activeGroup, setActiveGroup] = useState<CometChat.Group | null>(null);

  return (
    <div style={{ display: 'flex' }}>
      <CometChatGroups onItemClick={setActiveGroup} activeGroup={activeGroup} />

      {activeGroup && (
        <CometChatMessageList group={activeGroup} />
      )}
    </div>
  );
}

Custom Request Builder

Use requestBuilder to customize the SDK query for fetching groups:

import { CometChat } from '@cometchat/chat-sdk-javascript';

const builder = new CometChat.GroupsRequestBuilder()
  .setLimit(50)
  .joinedOnly(true);

<CometChatGroups requestBuilder={builder} />

You can also provide a separate searchRequestBuilder for search queries:

const searchBuilder = new CometChat.GroupsRequestBuilder()
  .setLimit(30)
  .setSearchKeyword('');  // keyword will be set dynamically

<CometChatGroups.Root
  requestBuilder={builder}
  searchRequestBuilder={searchBuilder}
/>

Group Types

Each group displays a type badge at the bottom-right of the avatar (unless hideGroupType is set to true):

Type	Badge	Description
Public	No badge	Open group, anyone can join.
Private	Orange circle + shield icon	Invite-only group.
Password	Green circle + lock icon	Requires password to join.

// Hide the group type badge
<CometChatGroups hideGroupType />

Selection Modes

None (default)

No selection controls are shown. Clicking a group triggers onItemClick.

Single

Radio buttons appear in the trailing view. Only one group can be selected at a time.

Multiple

Checkboxes appear in the trailing view. Multiple groups can be selected. Supports shift-click range selection.

<CometChatGroups.Root
  selectionMode="multiple"
  onSelect={(group, selected) => {
    console.log(group.getName(), selected ? 'selected' : 'deselected');
  }}
>
  <CometChatGroups.Header />
  <CometChatGroups.SearchBar />
  <CometChatGroups.List />
</CometChatGroups.Root>

Group Mutations

The context exposes mutation methods for group operations:

import { useCometChatGroupsContext } from '@cometchat/chat-uikit-react';

function GroupActions() {
  const { createGroup, joinGroup, leaveGroup, deleteGroup } = useCometChatGroupsContext();

  const handleJoin = async (guid: string) => {
    await joinGroup(guid, 'public');
  };

  const handleJoinPassword = async (guid: string, password: string) => {
    await joinGroup(guid, 'password', password);
  };

  const handleLeave = async (guid: string) => {
    await leaveGroup(guid);
  };

  const handleDelete = async (guid: string) => {
    await deleteGroup(guid);
  };

  return null;
}

Context Hook

Access the groups context from any child component inside CometChatGroups.Root:

import { useCometChatGroupsContext } from '@cometchat/chat-uikit-react';

function CustomGroupCount() {
  const { groups, fetchState } = useCometChatGroupsContext();
  if (fetchState !== 'loaded') return null;
  return <span>{groups.length} groups</span>;
}

The context provides:

Property	Type	Description
groups	CometChat.Group[]	List of fetched groups.
fetchState	'idle' | 'loading' | 'loaded' | 'error' | 'empty'	Current fetch lifecycle state.
hasMore	boolean	Whether more pages are available.
error	string | null	Error message (if fetchState is ‘error’).
selectedGroupIds	string[]	GUIDs of selected groups.
searchText	string	Current search text.
fetchNext	() => Promise<void>	Fetch next page of groups.
setSearchText	(text: string) => void	Set search text (triggers re-fetch).
selectGroup	(group: CometChat.Group) => void	Select a group.
deselectGroup	(groupId: string) => void	Deselect a group by GUID.
clearSelection	() => void	Clear all selections.
createGroup	(group: CometChat.Group) => Promise<CometChat.Group>	Create a new group.
joinGroup	(guid, groupType, password?) => Promise<CometChat.Group>	Join a group.
leaveGroup	(guid: string) => Promise<boolean>	Leave a group.
deleteGroup	(guid: string) => Promise<boolean>	Delete a group.

Accessibility

• List container: role="listbox" with aria-label="Groups list"
• Group items: role="option" with aria-selected
• Group type badges: aria-label describing the type (e.g., “Private group”, “Password protected group”)
• Loading state: aria-busy="true"
• Empty/Error states: role="status"
• Keyboard: Tab to focus, ArrowUp/ArrowDown to navigate, Enter/Space to select, Escape to clear search
• All icon-only buttons have aria-label

CSS Customization

The component uses CSS custom properties for theming:

:root {
  --cometchat-primary-color: #6851d6;
  --cometchat-background-color-01: #ffffff;
  --cometchat-text-color-primary: #141414;
  --cometchat-text-color-secondary: #727272;
  --cometchat-success-color: #09c26f;
  --cometchat-warning-color: #ffab00;
}

Real-Time Updates

The component automatically handles:

• Member joined — updates member count
• Member left — updates member count; removes group if logged-in user left
• Member banned/kicked — updates member count; removes group if logged-in user was banned/kicked
• Scope changed — updates group in list
• Group deleted — removes group from list
• Connection recovery — re-fetches groups on network reconnect
• Selection persistence — selections persist across search operations