Group Members - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatGroupMembers",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatGroupMembers } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Scrollable list of members for a specific group with role-based actions like kick, ban, and scope change.",
  "cssRootClass": ".cometchat-group-members",
  "primaryOutput": {
    "prop": "onItemClick",
    "type": "(member: CometChat.GroupMember) => void"
  },
  "props": {
    "data": {
      "group": {
        "type": "CometChat.Group",
        "default": "none (required)",
        "note": "The group whose members to display"
      },
      "groupMemberRequestBuilder": {
        "type": "CometChat.GroupMembersRequestBuilder",
        "default": "SDK default (30 per page)",
        "note": "Pass the builder instance, not the result of .build()"
      },
      "searchRequestBuilder": {
        "type": "CometChat.GroupMembersRequestBuilder",
        "default": "undefined"
      },
      "searchKeyword": {
        "type": "string",
        "default": "undefined"
      }
    },
    "callbacks": {
      "onItemClick": "(member: CometChat.GroupMember) => void",
      "onSelect": "(member: CometChat.GroupMember, selected: boolean) => void",
      "onError": "((error: CometChat.CometChatException) => void) | null",
      "onEmpty": "() => void",
      "onBack": "() => void"
    },
    "visibility": {
      "hideUserStatus": { "type": "boolean", "default": false },
      "hideSearch": { "type": "boolean", "default": false },
      "hideKickMemberOption": { "type": "boolean", "default": false },
      "hideBanMemberOption": { "type": "boolean", "default": false },
      "hideScopeChangeOption": { "type": "boolean", "default": false },
      "showScrollbar": { "type": "boolean", "default": false }
    },
    "selection": {
      "selectionMode": {
        "type": "CometChatGroupMembersSelectionMode",
        "values": ["'none'", "'single'", "'multiple'"],
        "default": "'none'"
      }
    },
    "viewSlots": {
      "itemView": "(member: CometChat.GroupMember) => ReactNode",
      "leadingView": "(member: CometChat.GroupMember) => ReactNode",
      "titleView": "(member: CometChat.GroupMember) => ReactNode",
      "subtitleView": "(member: CometChat.GroupMember) => ReactNode",
      "trailingView": "(member: CometChat.GroupMember) => ReactNode",
      "headerView": "ReactNode",
      "loadingView": "ReactNode",
      "emptyView": "ReactNode",
      "errorView": "ReactNode",
      "options": "(member: CometChat.GroupMember) => CometChatGroupMemberOption[]"
    }
  },
  "events": [],
  "eventsReceived": [
    {
      "name": "ui:group/member-added",
      "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }",
      "description": "Adds new members to the list"
    },
    {
      "name": "ui:group/member-kicked",
      "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
      "description": "Removes the kicked member from the list"
    },
    {
      "name": "ui:group/member-banned",
      "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
      "description": "Removes the banned member from the list"
    },
    {
      "name": "ui:group/member-scope-changed",
      "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }",
      "description": "Updates the member's scope/role display"
    }
  ],
  "sdkListeners": [
    "onGroupMemberJoined",
    "onGroupMemberLeft",
    "onGroupMemberKicked",
    "onGroupMemberBanned",
    "onGroupMemberScopeChanged",
    "onMemberAddedToGroup"
  ],
  "types": {
    "CometChatGroupMemberOption": {
      "id": "string",
      "title": "string",
      "iconURL": "string | undefined",
      "onClick": "(member: CometChat.GroupMember) => void"
    },
    "CometChatGroupMembersSelectionMode": "'none' | 'single' | 'multiple'"
  }
}

Overview

CometChatGroupMembers is a list component that renders all members of a specific group. It provides role-based actions (kick, ban, scope change) for admins and moderators, and emits the selected CometChat.GroupMember via onItemClick. Use it inside group details panels or as a standalone member management view.

Live Preview — interact with the default group members list.Open in Storybook ↗

The component handles:

Paginated fetching with infinite scroll
Real-time membership updates (joins, leaves, kicks, bans, scope changes)
Search filtering
Role-based action menus (kick, ban, change scope)
Selection mode (single/multiple)

Usage

Flat API

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

function MemberList({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onItemClick={(member) => {
        console.log("Selected member:", member.getName());
      }}
    />
  );
}

Compound Composition

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

function MemberList({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers.Root group={group} onItemClick={handleClick}>
      <CometChatGroupMembers.Header title="Members" onBack={goBack} />
      <CometChatGroupMembers.SearchBar placeholder="Search members..." />
      <CometChatGroupMembers.LoadingState />
      <CometChatGroupMembers.ErrorState />
      <CometChatGroupMembers.EmptyState>
        <p>No members found.</p>
      </CometChatGroupMembers.EmptyState>
      <CometChatGroupMembers.List />
    </CometChatGroupMembers.Root>
  );
}

Group Details Example

import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatGroupMembers,
  CometChatMessages,
} from "@cometchat/chat-uikit-react";

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

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 320 }}>
        <CometChatGroupMembers
          group={group}
          onItemClick={(member) => setSelectedMember(member)}
          onBack={() => navigateBack()}
        />
      </div>
      {selectedMember && (
        <div style={{ flex: 1 }}>
          {/* Show member profile or start DM */}
        </div>
      )}
    </div>
  );
}

Filtering

Pass a CometChat.GroupMembersRequestBuilder to groupMemberRequestBuilder to control which members load. Pass the builder instance — not the result of .build().

<CometChatGroupMembers
  group={group}
  groupMemberRequestBuilder={
    new CometChat.GroupMembersRequestBuilder(group.getGuid())
      .setLimit(15)
      .setScopes(["admin", "moderator"])
  }
/>

Search

The component includes a built-in search bar. When the user types, it fetches matching members from the server. For custom search behavior, pass a searchRequestBuilder:

<CometChatGroupMembers
  group={group}
  searchRequestBuilder={
    new CometChat.GroupMembersRequestBuilder(group.getGuid())
      .setLimit(30)
      .setSearchKeyword("")
  }
/>

Filter Recipes

Recipe	Code
Only admins	`new CometChat.GroupMembersRequestBuilder(guid).setScopes(["admin"])`
Admins & moderators	`new CometChat.GroupMembersRequestBuilder(guid).setScopes(["admin", "moderator"])`
Limit page size	`new CometChat.GroupMembersRequestBuilder(guid).setLimit(10)`

Actions and Events

Callback Props

Prop	Signature	Fires when
`onItemClick`	`(member: CometChat.GroupMember) => void`	User clicks a member item
`onSelect`	`(member: CometChat.GroupMember, selected: boolean) => void`	Member selected/deselected (selection mode)
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs
`onEmpty`	`() => void`	List is empty after initial fetch
`onBack`	`() => void`	Back button is clicked

Events Emitted

This component does not emit any UI events directly. Kick, ban, and scope change actions are handled by internal action handlers that publish their own events.

Events Received

UI events this component subscribes to (published by other components):

Event	Payload	Behavior
`ui:group/member-added`	`{ group, members, messages }`	Adds new members to the list
`ui:group/member-kicked`	`{ group, user, message }`	Removes the kicked member from the list
`ui:group/member-banned`	`{ group, user, message }`	Removes the banned member from the list
`ui:group/member-scope-changed`	`{ group, user, newScope }`	Updates the member’s scope/role display

SDK Listeners (Automatic)

These SDK listeners are attached internally. The component updates its state automatically — no manual subscription needed:

Groups: onGroupMemberJoined, onGroupMemberLeft, onGroupMemberKicked, onGroupMemberBanned, onGroupMemberScopeChanged, onMemberAddedToGroup

Customization

View Props

Use view props to replace sections of the default UI while keeping the component’s behavior intact:

<CometChatGroupMembers
  group={group}
  headerView={<MyCustomHeader />}
  itemView={(member) => <MyCustomMemberItem member={member} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>

Slot	Signature	Replaces
`itemView`	`(member) => ReactNode`	Entire member row
`leadingView`	`(member) => ReactNode`	Avatar section
`titleView`	`(member) => ReactNode`	Member name
`subtitleView`	`(member) => ReactNode`	Status / role text
`trailingView`	`(member) => ReactNode`	Scope badge + action menu
`headerView`	`ReactNode`	Header area
`loadingView`	`ReactNode`	Loading shimmer
`emptyView`	`ReactNode`	Empty state
`errorView`	`ReactNode`	Error state

Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

<CometChatGroupMembers.Root group={group} onItemClick={handleClick}>
  {/* No Header or SearchBar — they won't render */}
  <CometChatGroupMembers.List />
</CometChatGroupMembers.Root>

Available sub-components:

Sub-component	Description	Props	Flat API equivalent
`Root`	Context provider and container	All Root props + `children`	—
`List`	Scrollable member list	`itemView`, `className`	`itemView`
`Item`	Individual member row	`leadingView`, `titleView`, `subtitleView`, `trailingView`, `className`	Per-item view props
`Header`	Header area	`title`, `children`	`headerView`
`SearchBar`	Search input	`placeholder`	—
`EmptyState`	Empty state	`children`	`emptyView`
`ErrorState`	Error state	`children`	`errorView`
`LoadingState`	Loading shimmer	`children`	`loadingView`

CSS Styling

Override design tokens on the component selector:

.cometchat-group-members {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-group-members__item-scope {
  color: var(--cometchat-primary-color);
  font-weight: 600;
}

Props

All props are optional unless marked Required.

View slot props (headerView, searchView, loadingView, emptyView, errorView, itemView, leadingView, titleView, subtitleView, trailingView) are convenience props available only on the flat API. In compound composition mode, use the corresponding sub-components directly.

group

Required. The group whose members to display.


Type	`CometChat.Group`
Default	—

groupMemberRequestBuilder

Custom request builder for fetching group members. Controls pagination, filtering, and sorting.


Type	`CometChat.GroupMembersRequestBuilder`
Default	SDK default (limit 30)

searchRequestBuilder

Custom request builder used specifically when the user searches. Separate from the main builder.


Type	`CometChat.GroupMembersRequestBuilder`
Default	`undefined`

searchKeyword

Initial search keyword to pre-filter members on mount.


Type	`string`
Default	`undefined`

hideUserStatus

Hide the online/offline status indicator on member avatars.


Type	`boolean`
Default	`false`

hideSearch

Hide the search bar entirely.


Type	`boolean`
Default	`false`

hideKickMemberOption

Hide the “Kick Member” option from the action menu (even for admins/owners).


Type	`boolean`
Default	`false`

hideBanMemberOption

Hide the “Ban Member” option from the action menu (even for admins/owners).


Type	`boolean`
Default	`false`

hideScopeChangeOption

Hide the “Change Scope” option from the action menu (even for admins/owners).


Type	`boolean`
Default	`false`

showScrollbar

Show the native scrollbar on the member list.


Type	`boolean`
Default	`false`

selectionMode

Enable selection mode for single or multi-select operations.


Type	`'none' \| 'single' \| 'multiple'`
Default	`'none'`

options

Function that returns context menu options for each member item (shown on hover/swipe). Overrides the default kick/ban/scope options.


Type	`(member: CometChat.GroupMember) => CometChatGroupMemberOption[]`
Default	Default options (kick, ban, change scope — based on logged-in user’s role)

<CometChatGroupMembers
  group={group}
  options={(member) => [
    {
      id: "message",
      title: "Message Privately",
      iconURL: messageIcon,
      onClick: (m) => openDirectMessage(m),
    },
    {
      id: "remove",
      title: "Remove",
      iconURL: removeIcon,
      onClick: (m) => kickMember(m),
    },
  ]}
/>

onItemClick

Callback when a member item is clicked.


Type	`(member: CometChat.GroupMember) => void`
Default	`undefined`

onSelect

Callback when a member is selected or deselected (only fires in selection mode).


Type	`(member: CometChat.GroupMember, selected: boolean) => void`
Default	`undefined`

onError

Callback when an SDK error occurs during fetch or real-time operations.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`null`

onEmpty

Callback when the member list is empty after the initial fetch completes.


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

onBack

Callback when the back button in the header is clicked.


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

CSS Selectors

Target	Selector
Root container	`.cometchat-group-members`
Header	`.cometchat-group-members__header`
Search bar	`.cometchat-group-members__search-bar`
List container	`.cometchat-group-members__list`
Member item	`.cometchat-group-members__item`
Scope badge	`.cometchat-group-members__item-scope`
Empty state	`.cometchat-group-members__empty-state`
Error state	`.cometchat-group-members__error-state`
Loading state	`.cometchat-group-members__loading-state`

Next Steps

Groups

Browse and select groups

Banned Members

View and unban banned group members

Add Members

Add new members to a group

Theming

Customize colors, fonts, and spacing

Documentation Index

​Overview

​Usage

​Flat API

​Compound Composition

​Group Details Example

​Filtering

​Search

​Filter Recipes

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​Compound Composition

​CSS Styling

​Props

​group

​groupMemberRequestBuilder

​searchRequestBuilder

​searchKeyword

​hideUserStatus

​hideSearch

​hideKickMemberOption

​hideBanMemberOption

​hideScopeChangeOption

​showScrollbar

​selectionMode

​options

​onItemClick

​onSelect

​onError

​onEmpty

​onBack

​CSS Selectors

​Next Steps

Groups

Banned Members

Add Members

Theming

Overview

Usage

Flat API

Compound Composition

Group Details Example

Filtering

Search

Filter Recipes

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

Compound Composition

CSS Styling

Props

group

groupMemberRequestBuilder

searchRequestBuilder

searchKeyword

hideUserStatus

hideSearch

hideKickMemberOption

hideBanMemberOption

hideScopeChangeOption

showScrollbar

selectionMode

options

onItemClick

onSelect

onError

onEmpty

onBack

CSS Selectors

Next Steps