Group Chat Setup - CometChat Docs

Goal

By the end of this guide you will have a working group chat where users can create a group of any type (public, password-protected, or private), add and remove members with role-based permissions, join or leave a group, transfer ownership, and exchange messages in real time using the CometChat components.

Prerequisites

Completed the Integration Guide guide
A running CometChatProvider setup with valid credentials
Familiarity with the Conversations and Message List components

Components Used

Component / API	Purpose
`CometChatConversations`	Lists existing conversations including groups
`CometChatGroupMembers`	Built-in member list with role-gated kick / ban / scope-change actions
`CometChatMessageHeader`	Displays group name, avatar, and member count
`CometChatMessageList`	Renders group messages in real time
`CometChatMessageComposer`	Text input for sending messages to the group
`CometChat.createGroup()`	SDK method to create a new group
`CometChat.joinGroup()`	SDK method to join a public or password-protected group
`CometChat.addMembersToGroup()`	SDK method to add members
`CometChat.kickGroupMember()` / `banGroupMember()`	SDK methods to remove or ban a member
`CometChat.updateGroupMemberScope()`	SDK method to change a member’s role
`CometChat.leaveGroup()`	SDK method to leave a group
`CometChat.transferGroupOwnership()`	SDK method to hand ownership to another member

Step 1: Set up the app shell

Wrap your application in CometChatProvider and create a layout with a sidebar for conversations and a main area for messages.

App.tsx

import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatProvider } from "@cometchat/chat-uikit-react";
import { GroupChat } from "./GroupChat";

function App() {
  return (
    <CometChatProvider>
      <GroupChat />
    </CometChatProvider>
  );
}

export default App;

Step 2: Create a group

A group has one of three types, and the type decides how other users can get in. Choose the right one up front — it changes both the create call and how (or whether) users can join.

Type	Constant	How users get in
Public	`CometChat.GROUP_TYPE.PUBLIC`	Anyone can join, no password.
Password-protected	`CometChat.GROUP_TYPE.PASSWORD`	Users must supply the correct password to join.
Private	`CometChat.GROUP_TYPE.PRIVATE`	Add-only. Users cannot join — not even with a password. An admin or moderator must add them.

Create a group with CometChat.createGroup(). The CometChat.Group constructor takes a fourth password argument — it is required for password-protected groups and ignored for the other two types.

async function createGroup(
  name: string,
  type: string,
  password = "" // only used when type is PASSWORD
) {
  const group = new CometChat.Group(
    "group-" + Date.now(), // unique GUID
    name,
    type,                  // PUBLIC | PASSWORD | PRIVATE
    password
  );

  try {
    const createdGroup = await CometChat.createGroup(group);
    console.log("Group created:", createdGroup.getName());
    return createdGroup;
  } catch (error) {
    console.error("Group creation failed:", error);
  }
}

For a password-protected group you must pass the password as the fourth argument. new CometChat.Group(guid, name, CometChat.GROUP_TYPE.PASSWORD) with no password creates a group nobody can join.

When a group is created through the UI Kit’s built-in flow, it publishes the ui:group/created event on the Event System. Subscribe with useCometChatEvents if other components need to react to new groups being created.

Step 3: Add members

The creator becomes the group owner (with admin privileges). Add members with CometChat.addMembersToGroup() — each member is a CometChat.GroupMember with a UID and a scope (ADMIN, MODERATOR, or PARTICIPANT).

async function addMembers(guid: string, memberUids: string[]) {
  const members = memberUids.map(
    (uid) =>
      new CometChat.GroupMember(uid, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT)
  );

  try {
    const response = await CometChat.addMembersToGroup(guid, members, []);
    console.log("Members added:", response);
  } catch (error) {
    console.error("Failed to add members:", error);
  }
}

Adding members requires an admin or moderator scope in the target group — a participant cannot add members. Assign PARTICIPANT by default and only grant ADMIN/MODERATOR when a member needs management rights. For private groups this is the only way in — there is no join. To let a user pick who to add, render CometChatUsers in selection mode and pass the chosen UIDs to addMembersToGroup().

Step 4: Join a group

How a user joins depends on the group type:

async function joinGroup(group: CometChat.Group, password = "") {
  const guid = group.getGuid();
  const type = group.getType();

  // Private groups cannot be joined — the user must be added (Step 3).
  if (type === CometChat.GROUP_TYPE.PRIVATE) {
    console.warn("Private groups are add-only; joining is not allowed.");
    return;
  }

  try {
    // Pass the password only for password-protected groups; "" for public.
    const joined = await CometChat.joinGroup(guid, type, password);
    console.log("Joined group:", joined.getName());
    return joined;
  } catch (error) {
    // A wrong password for a PASSWORD group rejects here.
    console.error("Failed to join group:", error);
  }
}

Only public and password-protected groups can be joined. A private group is add-only — calling joinGroup() on it fails; add the user via Step 3 instead. The built-in CometChatGroups list surfaces a password prompt for password-protected groups automatically.

Step 5: Manage members — remove, ban, and change roles

The CometChatGroupMembers component renders the member list with built-in kick, ban, and change-scope actions. It shows or hides those actions based on the logged-in user’s role, so you don’t have to gate them yourself.

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

function GroupMembersPanel({ group }: { group: CometChat.Group }) {
  return (
    <CometChatGroupMembers
      group={group}
      onBack={() => {/* close the panel */}}
    />
  );
}

Group actions are scope-based — a participant can never perform them:

Action	Participant	Moderator	Admin / Owner
Send & receive messages	✅	✅	✅
Add members	❌	✅	✅
Kick / ban participants	❌	✅	✅
Kick / ban admins & moderators	❌	❌	✅
Change a member’s scope	❌	participants only	✅
Update / delete the group	❌	update only	✅
Transfer ownership	❌	❌	Owner only

If you build your own controls instead of using the component’s menu, the SDK methods are:

// Remove a member from the group
await CometChat.kickGroupMember(guid, uid);

// Ban a member (kicked and blocked from rejoining)
await CometChat.banGroupMember(guid, uid);

// Promote / demote a member
await CometChat.updateGroupMemberScope(
  guid,
  uid,
  CometChat.GROUP_MEMBER_SCOPE.MODERATOR
);

Calling these as a participant — or a moderator acting on an admin — rejects with a permission error. Let the acting user’s scope drive which controls you render. The component already does this for its default kick/ban/scope menu.

Step 6: Leave a group and transfer ownership

Any member can leave with CometChat.leaveGroup() — except the owner. An owner must hand ownership to another member with CometChat.transferGroupOwnership() first; leaving before transferring rejects with an error.

async function leaveGroup(group: CometChat.Group, loggedInUid: string) {
  const guid = group.getGuid();
  const isOwner = group.getOwner() === loggedInUid;

  try {
    if (isOwner) {
      // Owners cannot leave until ownership is transferred.
      const newOwnerUid = await pickAnotherMember(guid); // your UI: choose a member
      if (!newOwnerUid) return; // no one to hand off to — block the leave
      await CometChat.transferGroupOwnership(guid, newOwnerUid);
    }

    await CometChat.leaveGroup(guid);
    console.log("Left group:", group.getName());
  } catch (error) {
    console.error("Failed to leave group:", error);
  }
}

Wiring “Leave Group” straight to leaveGroup() throws for the owner. Detect the owner (group.getOwner() === loggedInUser.getUid()), show an ownership-transfer step (a member picker — CometChatGroupMembers in selection mode works well), call transferGroupOwnership(), and only then leaveGroup(). See the SDK Transfer Group Ownership and Leave Group references.

Step 7: Display conversations and select a group

Use CometChatConversations to show the user’s conversations. When a group conversation is selected, pass the group object to the message components.

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

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

  function handleConversationClick(conversation: CometChat.Conversation) {
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.Group) {
      setActiveGroup(entity);
    }
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: "320px", borderRight: "1px solid #e0e0e0" }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1 }}>
        {activeGroup && <GroupMessageView group={activeGroup} />}
      </div>
    </div>
  );
}

Step 8: Render the group message view

Combine CometChatMessageList and CometChatMessageComposer to display messages and allow sending within the selected group.

import {
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatMessageHeader,
} from "@cometchat/chat-uikit-react";

function GroupMessageView({ group }: { group: CometChat.Group }) {
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader group={group} />

      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList group={group} />
      </div>

      <CometChatMessageComposer group={group} />
    </div>
  );
}

Step 9: Add a create-group form

Provide a UI for users to create groups on the fly. Show a password field only when the selected type is password-protected, and pass it through to createGroup from Step 2.

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

function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => void }) {
  const [name, setName] = useState("");
  const [type, setType] = useState<string>(CometChat.GROUP_TYPE.PUBLIC);
  const [password, setPassword] = useState("");

  const isPasswordType = type === CometChat.GROUP_TYPE.PASSWORD;

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!name.trim()) return;
    if (isPasswordType && !password) return; // password is required for this type

    const group = new CometChat.Group(
      "group-" + Date.now(),
      name.trim(),
      type,
      isPasswordType ? password : ""
    );

    try {
      const createdGroup = await CometChat.createGroup(group);
      onCreate(createdGroup);
      setName("");
      setPassword("");
    } catch (error) {
      console.error("Group creation failed:", error);
    }
  }

  return (
    <form onSubmit={handleSubmit} style={{ padding: "12px" }}>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Group name"
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      />
      <select
        value={type}
        onChange={(e) => setType(e.target.value)}
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      >
        <option value={CometChat.GROUP_TYPE.PUBLIC}>Public</option>
        <option value={CometChat.GROUP_TYPE.PRIVATE}>Private (add-only)</option>
        <option value={CometChat.GROUP_TYPE.PASSWORD}>Password Protected</option>
      </select>
      {isPasswordType && (
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Group password"
          style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
        />
      )}
      <button type="submit" style={{ width: "100%", padding: "8px" }}>
        Create Group
      </button>
    </form>
  );
}

Complete Example

The “New Group” button lives in the conversation list’s headerView slot — not in a separate <div> stacked above the list — so the list header stays intact and the layout doesn’t shift. Because headerView replaces the entire default header, re-render the default title (“Chats”) alongside the button.

GroupChat.tsx

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

function CreateGroupForm({ onCreate }: { onCreate: (group: CometChat.Group) => void }) {
  const [name, setName] = useState("");
  const [type, setType] = useState<string>(CometChat.GROUP_TYPE.PUBLIC);
  const [password, setPassword] = useState("");

  const isPasswordType = type === CometChat.GROUP_TYPE.PASSWORD;

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!name.trim()) return;
    if (isPasswordType && !password) return;

    const group = new CometChat.Group(
      "group-" + Date.now(),
      name.trim(),
      type,
      isPasswordType ? password : ""
    );

    try {
      const createdGroup = await CometChat.createGroup(group);
      onCreate(createdGroup);
      setName("");
      setPassword("");
    } catch (error) {
      console.error("Group creation failed:", error);
    }
  }

  return (
    <form onSubmit={handleSubmit} style={{ padding: "12px" }}>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Group name"
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      />
      <select
        value={type}
        onChange={(e) => setType(e.target.value)}
        style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
      >
        <option value={CometChat.GROUP_TYPE.PUBLIC}>Public</option>
        <option value={CometChat.GROUP_TYPE.PRIVATE}>Private (add-only)</option>
        <option value={CometChat.GROUP_TYPE.PASSWORD}>Password Protected</option>
      </select>
      {isPasswordType && (
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Group password"
          style={{ width: "100%", marginBottom: "8px", padding: "8px" }}
        />
      )}
      <button type="submit" style={{ width: "100%", padding: "8px" }}>
        Create Group
      </button>
    </form>
  );
}

function GroupMessageView({ group }: { group: CometChat.Group }) {
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <CometChatMessageHeader group={group} />

      <div style={{ flex: 1, overflow: "hidden" }}>
        <CometChatMessageList group={group} />
      </div>

      <CometChatMessageComposer group={group} />
    </div>
  );
}

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

  function handleConversationClick(conversation: CometChat.Conversation) {
    const entity = conversation.getConversationWith();
    if (entity instanceof CometChat.Group) {
      setActiveGroup(entity);
    }
  }

  function handleGroupCreated(group: CometChat.Group) {
    setActiveGroup(group);
    setShowCreateForm(false);
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: "320px", borderRight: "1px solid #e0e0e0", display: "flex", flexDirection: "column" }}>
        {showCreateForm && <CreateGroupForm onCreate={handleGroupCreated} />}

        <div style={{ flex: 1, overflow: "hidden" }}>
          <CometChatConversations
            onItemClick={handleConversationClick}
            headerView={
              // headerView replaces the whole default header, so re-render the "Chats" title next to the button
              <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", padding: "8px 16px" }}>
                <span style={{ fontWeight: "bold" }}>Chats</span>
                <button onClick={() => setShowCreateForm(!showCreateForm)}>
                  {showCreateForm ? "Cancel" : "New Group"}
                </button>
              </div>
            }
          />
        </div>
      </div>

      <div style={{ flex: 1 }}>
        {activeGroup ? (
          <GroupMessageView group={activeGroup} />
        ) : (
          <div style={{ display: "flex", alignItems: "center", justifyContent: "center", height: "100%" }}>
            <p>Select a group conversation or create a new group</p>
          </div>
        )}
      </div>
    </div>
  );
}

function App() {
  return (
    <CometChatProvider>
      <GroupChat />
    </CometChatProvider>
  );
}

export default App;

Next Steps

Groups — browse and join existing groups
Group Members — manage group membership with role-based actions
Kick / Ban Members · Change Member Scope · Transfer Ownership — SDK references
Message Header — customize the group header
Event System — react to ui:group/created and other group action events
CometChatProvider — configure the root provider

​Goal

​Prerequisites

​Components Used

​Step 1: Set up the app shell

​Step 2: Create a group

​Step 3: Add members

​Step 4: Join a group

​Step 5: Manage members — remove, ban, and change roles

​Step 6: Leave a group and transfer ownership

​Step 7: Display conversations and select a group

​Step 8: Render the group message view

​Step 9: Add a create-group form

​Complete Example

​Next Steps

Goal

Prerequisites

Components Used

Step 1: Set up the app shell

Step 2: Create a group

Step 3: Add members

Step 4: Join a group

Step 5: Manage members — remove, ban, and change roles

Step 6: Leave a group and transfer ownership

Step 7: Display conversations and select a group

Step 8: Render the group message view

Step 9: Add a create-group form

Complete Example

Next Steps