Groups - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatGroups",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatGroups } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Searchable, scrollable list of groups with selection support and real-time membership updates.",
  "cssRootClass": ".cometchat-groups",
  "primaryOutput": {
    "prop": "onItemClick",
    "type": "(group: CometChat.Group) => void"
  },
  "props": {
    "data": {
      "groupsRequestBuilder": {
        "type": "CometChat.GroupsRequestBuilder",
        "default": "SDK default (30 per page)",
        "note": "Pass the builder instance, not the result of .build()"
      },
      "searchRequestBuilder": {
        "type": "CometChat.GroupsRequestBuilder",
        "default": "undefined"
      },
      "searchKeyword": {
        "type": "string",
        "default": "undefined"
      },
      "activeGroup": {
        "type": "CometChat.Group",
        "default": "undefined"
      }
    },
    "callbacks": {
      "onItemClick": "(group: CometChat.Group) => void",
      "onSelect": "(group: CometChat.Group, selected: boolean) => void",
      "onError": "((error: CometChat.CometChatException) => void) | null",
      "onEmpty": "() => void"
    },
    "visibility": {
      "hideGroupType": { "type": "boolean", "default": false },
      "hideSearch": { "type": "boolean", "default": false },
      "showScrollbar": { "type": "boolean", "default": false }
    },
    "selection": {
      "selectionMode": {
        "type": "CometChatGroupsSelectionMode",
        "values": ["'none'", "'single'", "'multiple'"],
        "default": "'none'"
      }
    },
    "viewSlots": {
      "itemView": "(group: CometChat.Group) => ReactNode",
      "leadingView": "(group: CometChat.Group) => ReactNode",
      "titleView": "(group: CometChat.Group) => ReactNode",
      "subtitleView": "(group: CometChat.Group) => ReactNode",
      "trailingView": "(group: CometChat.Group) => ReactNode",
      "headerView": "ReactNode",
      "loadingView": "ReactNode",
      "emptyView": "ReactNode",
      "errorView": "ReactNode",
      "options": "(group: CometChat.Group) => CometChatGroupOption[]"
    }
  },
  "events": [],
  "eventsReceived": [
    {
      "name": "ui:group/created",
      "payload": "{ group: CometChat.Group }",
      "description": "Adds the new group to the list"
    },
    {
      "name": "ui:group/deleted",
      "payload": "{ group: CometChat.Group }",
      "description": "Removes the group from the list"
    },
    {
      "name": "ui:group/left",
      "payload": "{ group: CometChat.Group }",
      "description": "Removes (private) or updates (public) the group"
    },
    {
      "name": "ui:group/member-joined",
      "payload": "{ joinedGroup: CometChat.Group }",
      "description": "Updates the group (member count)"
    },
    {
      "name": "ui:group/member-added",
      "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }",
      "description": "Updates the group"
    },
    {
      "name": "ui:group/member-kicked",
      "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
      "description": "Updates the group"
    },
    {
      "name": "ui:group/member-banned",
      "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }",
      "description": "Updates the group"
    },
    {
      "name": "ui:group/member-scope-changed",
      "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }",
      "description": "Updates the group"
    },
    {
      "name": "ui:group/ownership-changed",
      "payload": "{ group: CometChat.Group }",
      "description": "Updates the group"
    }
  ],
  "sdkListeners": [
    "onGroupMemberJoined",
    "onGroupMemberLeft",
    "onGroupMemberKicked",
    "onGroupMemberBanned",
    "onMemberAddedToGroup"
  ],
  "types": {
    "CometChatGroupOption": {
      "id": "string",
      "title": "string",
      "iconURL": "string | undefined",
      "onClick": "(group: CometChat.Group) => void"
    },
    "CometChatGroupsSelectionMode": "'none' | 'single' | 'multiple'"
  }
}

Overview

CometChatGroups is a list component that renders all available groups in the app. It emits the selected CometChat.Group via onItemClick. Wire it to CometChatMessages or use it as a group picker in flows like “join group” or “group details.”

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

The component handles:

Paginated fetching with infinite scroll
Real-time membership updates (joins, leaves, kicks, bans)
Search filtering
Swipe/hover options
Selection mode (single/multiple)

Usage

Flat API

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

function GroupList() {
  return (
    <CometChatGroups
      onItemClick={(group) => {
        console.log("Selected group:", group.getName());
      }}
    />
  );
}

Compound Composition

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

function GroupList() {
  return (
    <CometChatGroups.Root onItemClick={handleClick}>
      <CometChatGroups.Header title="Groups" />
      <CometChatGroups.SearchBar placeholder="Search groups..." />
      <CometChatGroups.LoadingState />
      <CometChatGroups.ErrorState />
      <CometChatGroups.EmptyState>
        <p>No groups found. Create one!</p>
      </CometChatGroups.EmptyState>
      <CometChatGroups.List />
    </CometChatGroups.Root>
  );
}

Full Layout Example

import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatGroups,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

function GroupChat() {
  const [group, setGroup] = useState<CometChat.Group | undefined>();

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatGroups onItemClick={(g) => setGroup(g)} activeGroup={group} />
      </div>
      {group && (
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          <CometChatMessageHeader group={group} />
          <CometChatMessageList group={group} />
          <CometChatMessageComposer group={group} />
        </div>
      )}
    </div>
  );
}

Filtering

Pass a CometChat.GroupsRequestBuilder to groupsRequestBuilder to control which groups load. Pass the builder instance — not the result of .build().

<CometChatGroups
  groupsRequestBuilder={
    new CometChat.GroupsRequestBuilder()
      .setLimit(15)
      .joinedOnly(true)
  }
/>

Search

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

<CometChatGroups
  searchRequestBuilder={
    new CometChat.GroupsRequestBuilder().setLimit(30).setSearchKeyword("")
  }
/>

Filter Recipes

Recipe	Code
Only joined groups	`new CometChat.GroupsRequestBuilder().joinedOnly(true)`
Only public groups	`new CometChat.GroupsRequestBuilder().setType("public")`
Only private groups	`new CometChat.GroupsRequestBuilder().setType("private")`
Limit page size	`new CometChat.GroupsRequestBuilder().setLimit(10)`
With tags	`new CometChat.GroupsRequestBuilder().setTags(["team"])`

Actions and Events

Callback Props

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

Events Emitted

This component does not emit any UI events.

Events Received

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

Event	Payload	Behavior
`ui:group/created`	`{ group }`	Adds the new group to the list
`ui:group/deleted`	`{ group }`	Removes the group from the list
`ui:group/left`	`{ group }`	Removes (private) or updates (public) the group
`ui:group/member-joined`	`{ joinedGroup }`	Updates the group (member count)
`ui:group/member-added`	`{ group, members, messages }`	Updates the group
`ui:group/member-kicked`	`{ group, user, message }`	Updates the group
`ui:group/member-banned`	`{ group, user, message }`	Updates the group
`ui:group/member-scope-changed`	`{ group, user, newScope }`	Updates the group
`ui:group/ownership-changed`	`{ group }`	Updates the group

SDK Listeners (Automatic)

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

Groups: onGroupMemberJoined, onGroupMemberLeft, onGroupMemberKicked, onGroupMemberBanned, onMemberAddedToGroup

Customization

View Props

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

<CometChatGroups
  headerView={<MyCustomHeader />}
  itemView={(group) => <MyCustomGroupItem group={group} />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
/>

Slot	Signature	Replaces
`itemView`	`(group) => ReactNode`	Entire group row
`leadingView`	`(group) => ReactNode`	Avatar section
`titleView`	`(group) => ReactNode`	Group name
`subtitleView`	`(group) => ReactNode`	Member count / description
`trailingView`	`(group) => ReactNode`	Trailing content (group type icon)
`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:

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

Available sub-components:

Sub-component	Description	Props	Flat API equivalent
`Root`	Context provider and container	All Root props + `children`	—
`List`	Scrollable group list	`itemView`, `className`	`itemView`
`Item`	Individual group 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-groups {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-groups__item--active {
  background: var(--cometchat-primary-color);
}

Props

All props are optional.

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.

groupsRequestBuilder

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


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

searchRequestBuilder

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


Type	`CometChat.GroupsRequestBuilder`
Default	`undefined`

searchKeyword

Initial search keyword to pre-filter groups on mount.


Type	`string`
Default	`undefined`

hideGroupType

Hide the group type indicator (public/private/password-protected) on group items.


Type	`boolean`
Default	`false`

hideSearch

Hide the search bar entirely.


Type	`boolean`
Default	`false`

showScrollbar

Show the native scrollbar on the group list.


Type	`boolean`
Default	`false`

selectionMode

Enable selection mode for single or multi-select operations.


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

activeGroup

The currently active/highlighted group. The matching item receives an active visual state.


Type	`CometChat.Group`
Default	`undefined`

options

Function that returns context menu options for each group item (shown on hover/swipe).


Type	`(group: CometChat.Group) => CometChatGroupOption[]`
Default	`undefined`

<CometChatGroups
  options={(group) => [
    {
      id: "leave",
      title: "Leave Group",
      iconURL: leaveIcon,
      onClick: (g) => leaveGroup(g),
    },
    {
      id: "info",
      title: "Group Info",
      iconURL: infoIcon,
      onClick: (g) => openGroupDetails(g),
    },
  ]}
/>

onItemClick

Callback when a group item is clicked.


Type	`(group: CometChat.Group) => void`
Default	`undefined`

onSelect

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


Type	`(group: CometChat.Group, 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 group list is empty after the initial fetch completes.


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

CSS Selectors

Target	Selector
Root container	`.cometchat-groups`
Header	`.cometchat-groups__header`
Search bar	`.cometchat-groups__search-bar`
List container	`.cometchat-groups__list`
Group item	`.cometchat-groups__item`
Active item	`.cometchat-groups__item--active`
Empty state	`.cometchat-groups__empty-state`
Error state	`.cometchat-groups__error-state`
Loading state	`.cometchat-groups__loading-state`

Next Steps

Group Members

View and manage members of a group

Conversations

View recent conversations including group chats

Message List

Display messages for the selected group

Theming

Customize colors, fonts, and spacing

Documentation Index

​Overview

​Usage

​Flat API

​Compound Composition

​Full Layout 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

​groupsRequestBuilder

​searchRequestBuilder

​searchKeyword

​hideGroupType

​hideSearch

​showScrollbar

​selectionMode

​activeGroup

​options

​onItemClick

​onSelect

​onError

​onEmpty

​CSS Selectors

​Next Steps

Group Members

Conversations

Message List

Theming

Overview

Usage

Flat API

Compound Composition

Full Layout 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

groupsRequestBuilder

searchRequestBuilder

searchKeyword

hideGroupType

hideSearch

showScrollbar

selectionMode

activeGroup

options

onItemClick

onSelect

onError

onEmpty

CSS Selectors

Next Steps