CometChatGroupMembers - CometChat Docs

Overview

CometChatGroupMembers displays a real-time list of members within a specific CometChat group. It supports infinite scroll pagination, search with debounce, role badges (owner/admin/moderator), role-based context menus (kick, ban, promote, demote), online/offline presence indicators, single/multiple selection modes, and member mutations. It offers two usage modes:

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

Import

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

Quick Start

Flat API (Simple)

Pass props directly — no sub-component imports needed:

<CometChatGroupMembers
  group={group}
  onItemClick={(member) => console.log(member)}
  subtitleView={(member) => <span>{member.getScope()}</span>}
/>

Compound API (Advanced)

Full control via sub-components — compose only what you need:

<CometChatGroupMembers.Root group={group} selectionMode="multiple">
  <CometChatGroupMembers.Header title="Group Members" />
  <CometChatGroupMembers.SearchBar />
  <CometChatGroupMembers.LoadingState />
  <CometChatGroupMembers.ErrorState />
  <CometChatGroupMembers.EmptyState />
  <CometChatGroupMembers.List />
</CometChatGroupMembers.Root>

State sub-components (LoadingState, ErrorState, EmptyState) and List are self-managing — they read fetchState from context and automatically show/hide themselves. You can place them all in the tree without conditional rendering.

Sub-Components

Component	Description
`CometChatGroupMembers.Root`	Provider + default layout. Wraps children with context.
`CometChatGroupMembers.Header`	Header with title text (defaults to “Members”).
`CometChatGroupMembers.SearchBar`	Debounced search input (300ms).
`CometChatGroupMembers.List`	Member list with infinite scroll. Self-manages visibility.
`CometChatGroupMembers.Item`	Individual member item (avatar, name, status, role badge, action menu).
`CometChatGroupMembers.EmptyState`	Self-managing — only renders when `fetchState === 'empty'`.
`CometChatGroupMembers.ErrorState`	Self-managing — only renders when `fetchState === 'error'`.
`CometChatGroupMembers.LoadingState`	Self-managing — only renders when `fetchState === 'loading'`.

Props

Flat API (`<CometChatGroupMembers />`)

All Root props below, plus these convenience view props:

Prop	Type	Description
`leadingView`	`(member: CometChat.GroupMember) => ReactNode`	Custom leading view per item (replaces avatar).
`titleView`	`(member: CometChat.GroupMember) => ReactNode`	Custom title view per item.
`subtitleView`	`(member: CometChat.GroupMember) => ReactNode`	Custom subtitle view per item.
`trailingView`	`(member: CometChat.GroupMember) => ReactNode`	Custom trailing view per item (replaces role badge + action menu).
`itemView`	`(member: CometChat.GroupMember) => 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.

CometChatGroupMembers.Root

Prop	Type	Default	Description
`group`	`CometChat.Group`	required	The group whose members to display.
`requestBuilder`	`CometChat.GroupMembersRequestBuilder`	limit 30	Custom request builder for fetching members.
`searchRequestBuilder`	`CometChat.GroupMembersRequestBuilder`	—	Custom request builder for search queries.
`searchKeyword`	`string`	`''`	Initial search keyword.
`hideUserStatus`	`boolean`	`false`	Hide online/offline status indicators.
`hideKickMemberOption`	`boolean`	`false`	Hide the kick member option in the context menu.
`hideBanMemberOption`	`boolean`	`false`	Hide the ban member option in the context menu.
`hideScopeChangeOption`	`boolean`	`false`	Hide the scope change option in the context menu.
`selectionMode`	`'none' \| 'single' \| 'multiple'`	`'none'`	Selection mode.
`showScrollbar`	`boolean`	`false`	Show the native scrollbar on the list.
`options`	`(member) => CometChatGroupMemberOption[]`	—	Custom context menu options per member.
`onItemClick`	`(member: CometChat.GroupMember) => void`	—	Callback when a member is clicked.
`onSelect`	`(member, selected) => void`	—	Callback when selection changes.
`onError`	`(error: unknown) => void`	—	Callback when an error occurs.
`onEmpty`	`() => void`	—	Callback when the list is empty.
`onBack`	`() => void`	—	Callback when back button is clicked.
`children`	`ReactNode`	—	Custom layout. If omitted, renders default.

CometChatGroupMembers.Header

Prop	Type	Default	Description
`title`	`string`	`"Members"`	Custom title text.
`children`	`ReactNode`	—	Custom header content (replaces default).

CometChatGroupMembers.SearchBar

Prop	Type	Default	Description
`placeholder`	`string`	`"Search members"`	Placeholder text.

CometChatGroupMembers.List

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

CometChatGroupMembers.Item

Prop	Type	Default	Description
`member`	`CometChat.GroupMember`	required	The member to render.
`hideUserStatus`	`boolean`	—	Override status visibility.
`isActive`	`boolean`	—	Override active state.
`leadingView`	`ReactNode`	—	Custom leading view (replaces avatar).
`titleView`	`ReactNode`	—	Custom title view.
`subtitleView`	`ReactNode`	—	Custom subtitle view.
`trailingView`	`ReactNode`	—	Custom trailing view (replaces role badge + menu).

CometChatGroupMembers.EmptyState / ErrorState / LoadingState

Prop	Type	Default	Description
`children`	`ReactNode`	—	Custom content (replaces default rendering).

Sibling Communication with onItemClick

Use onItemClick to coordinate CometChatGroupMembers with sibling components. The parent owns shared state and passes it down:

function GroupView({ group }: { group: CometChat.Group }) {
  const [selectedMember, setSelectedMember] = useState<CometChat.GroupMember | null>(null);

  return (
    <div style={{ display: 'flex' }}>
      <CometChatGroupMembers
        group={group}
        onItemClick={(member) => setSelectedMember(member)}
      />
      {selectedMember && (
        <MemberProfile member={selectedMember} />
      )}
    </div>
  );
}

Custom Request Builder

Use requestBuilder to customize the SDK query for fetching group members:

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

const builder = new CometChat.GroupMembersRequestBuilder('group-guid')
  .setLimit(50)
  .setScopes(['admin', 'moderator']);

<CometChatGroupMembers group={group} requestBuilder={builder} />

Use searchRequestBuilder for custom search behavior:

const searchBuilder = new CometChat.GroupMembersRequestBuilder('group-guid')
  .setLimit(20)
  .setSearchKeyword('john');

<CometChatGroupMembers group={group} searchRequestBuilder={searchBuilder} />

Role Badges

Each member displays a role badge based on their scope:

Scope	Badge	Style
Owner	”Owner”	Primary color filled pill
Admin	”Admin”	Outlined pill with highlight color
Moderator	”Moderator”	Subtle background pill
Participant	No badge	—

The context menu displayed for each member depends on the logged-in user’s scope vs the target member’s scope. Actions are only available for members with a lower scope than the logged-in user.

Scope Hierarchy

owner > admin > moderator > participant

Action Visibility

Logged-in Scope	Target Scope	Available Actions
Owner	Admin	Kick, Ban, Demote to Moderator, Demote to Participant
Owner	Moderator	Kick, Ban, Promote to Admin, Demote to Participant
Owner	Participant	Kick, Ban, Promote to Admin, Promote to Moderator
Admin	Moderator	Kick, Ban, Demote to Participant
Admin	Participant	Kick, Ban, Promote to Moderator
Moderator	Participant	Kick, Ban
Any	Owner	No actions
Any	Same/higher scope	No actions

Hiding Specific Actions

Use the hide*Option boolean props to suppress individual actions:

<CometChatGroupMembers
  group={group}
  hideKickMemberOption
  hideBanMemberOption
/>

Custom Options

Override the default action menu with custom options:

<CometChatGroupMembers
  group={group}
  options={(member) => [
    {
      id: 'message',
      title: 'Send Message',
      onClick: (m) => openChat(m),
    },
    {
      id: 'profile',
      title: 'View Profile',
      onClick: (m) => openProfile(m),
    },
  ]}
/>

Selection Modes

None (default)

No selection controls. Clicking a member triggers onItemClick. Context menu with actions is shown on hover.

Single

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

Multiple

Checkboxes appear in the trailing view. Multiple members can be selected.

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

Context Hook

Access the group members context from any child component:

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

function MemberCount() {
  const { members, fetchState } = useCometChatGroupMembersContext();
  if (fetchState !== 'loaded') return null;
  return <span>{members.length} members</span>;
}

Available Context Values

The context exposes state, configuration, and action methods:

const {
  // State
  group,
  members,
  fetchState,       // 'idle' | 'loading' | 'loaded' | 'error' | 'empty'
  hasMore,
  error,
  selectedMemberIds,
  activeMemberId,
  searchText,
  loggedInUser,
  loggedInUserScope,

  // Actions
  fetchNext,
  setSearchText,
  selectMember,
  deselectMember,
  clearSelection,
  kickMember,
  banMember,
  unbanMember,
  changeScope,
} = useCometChatGroupMembersContext();

Member Mutations

The context exposes mutation methods for member management:

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

function MemberActions({ uid }: { uid: string }) {
  const { kickMember, banMember, changeScope } = useCometChatGroupMembersContext();

  return (
    <div>
      <button onClick={() => kickMember(uid)}>Kick</button>
      <button onClick={() => banMember(uid)}>Ban</button>
      <button onClick={() => changeScope(uid, 'admin')}>Promote to Admin</button>
    </div>
  );
}

Accessibility

List container: role="listbox" with aria-label="Group members list"
Member items: role="option" with aria-selected and descriptive aria-label (includes name, role, and status)
Role badges: aria-hidden="true" (info is in the item’s aria-label)
Action menu trigger: accessible via keyboard (Tab to reach, Enter to open)
Loading state: aria-busy="true", aria-live="polite"
Empty/Error states: role="status" / role="alert"
Keyboard: Tab to focus, Enter/Space to select, Escape to close menus
All interactive elements have :focus-visible styles

CSS Customization

The component uses CSS custom properties for theming:

/* Override in your app */
: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-error-color: #f44336;
}

Real-Time Updates

The component automatically handles:

Member joined — adds new member to the list
Member left — removes member from the list
Member banned — removes member from the list
Member kicked — removes member from the list
Scope changed — updates the member’s role badge
User online — shows online status indicator
User offline — shows offline status indicator
Connection recovery — re-fetches members on network reconnect
Selection persistence — selections persist across search operations

Documentation Index

​Overview

​Import

​Quick Start

​Flat API (Simple)

​Compound API (Advanced)

​Sub-Components

​Props

​Flat API (<CometChatGroupMembers />)

​CometChatGroupMembers.Root

​CometChatGroupMembers.Header

​CometChatGroupMembers.SearchBar

​CometChatGroupMembers.List

​CometChatGroupMembers.Item

​CometChatGroupMembers.EmptyState / ErrorState / LoadingState

​Sibling Communication with onItemClick

​Custom Request Builder

​Role Badges

​Role-Based Action Menu

​Scope Hierarchy

​Action Visibility

​Hiding Specific Actions

​Custom Options

​Selection Modes

​None (default)

​Single

​Multiple

​Context Hook

​Available Context Values

​Member Mutations

​Accessibility

​CSS Customization

​Real-Time Updates

Overview

Import

Quick Start

Flat API (Simple)

Compound API (Advanced)

Sub-Components

Props

Flat API (`<CometChatGroupMembers />`)

CometChatGroupMembers.Root

CometChatGroupMembers.Header

CometChatGroupMembers.SearchBar

CometChatGroupMembers.List

CometChatGroupMembers.Item

CometChatGroupMembers.EmptyState / ErrorState / LoadingState

Sibling Communication with onItemClick

Custom Request Builder

Role Badges

Role-Based Action Menu

Scope Hierarchy

Action Visibility

Hiding Specific Actions

Custom Options

Selection Modes

None (default)

Single

Multiple

Context Hook

Available Context Values

Member Mutations

Accessibility

CSS Customization

Real-Time Updates