Groups - CometChat Docs

Overview

CometChatGroups functions as a standalone Component, showcasing an accessible list of all available groups. It provides an integral search functionality, allowing you to locate any specific groups swiftly and easily. For each group listed, the group name is displayed by default, in conjunction with the group icon when available. Additionally, it provides a useful feature by displaying the number of members in each group as a subtitle, offering valuable context about group size and activity level.

Usage

Integration

The following code snippet illustrates how you can can launch CometChatGroups.

App.tsx

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
return <CometChatGroups />;

Actions

Actions dictate how a component functions. They are divided into two types: Predefined and Group-defined. You can override either type, allowing you to tailor the behavior of the component to fit your specific needs.

onItemPress

Function invoked when a Group item is clicked, typically used to open a Group profile or chat screen.

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

const onPressHandler = (user: CometChat.Group) => {
  //code
};

return <CometChatGroups onItemPress={onPressHandler} />;

onItemLongPress

Function executed when a Group item is long-pressed, allowing additional actions like delete or block.

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

const onLongPressHandler = (user: CometChat.Group) => {
  //code
};

return <CometChatGroups onItemLongPress={onLongPressHandler} />;

onBack

onBack is triggered when you press the back button in the app bar. It has a predefined behavior; when clicked, it navigates to the previous activity. However, you can override this action using the following code snippet.

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

const onBackHandler = () => {
  //code
};

return <CometChatGroups showBackButton={true} onBack={onBackHandler} />;

onSelection

Called when a item from the fetched list is selected, useful for multi-selection features.

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

const onSelectionHandler = (selection: Array<CometChat.Group>) => {
  //code
};

return (
  <CometChatGroups selectionMode={"single"} onSelection={onSelectionHandler} />
);

onError

This action doesn’t change the behavior of the component but rather listens for any errors that occur in the groups component.

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

const onErrorHandler = (error: CometChat.CometChatException) => {
  console.log("Error");
};

return <CometChatGroups onError={onErrorHandler} />;

Filters

Filters allow you to customize the data displayed in a list within a Component. You can filter the list based on your specific criteria, allowing for a more customized. Filters can be applied using RequestBuilders of Chat SDK.

1. GroupsRequestBuilder

The GroupsRequestBuilder enables you to filter and customize the group list based on available parameters in GroupsRequestBuilder. This feature allows you to create more specific and targeted queries when fetching groups. The following are the parameters available in GroupsRequestBuilder

Methods	Type	Description
setLimit	number	sets the number groups that can be fetched in a single request, suitable for pagination
setSearchKeyword	string	used for fetching groups matching the passed string
joinedOnly	boolean	to fetch only joined groups
friendsOnly	boolean	used for fetching only those users in which logged in user is a member
setTags	Array<string>	used for fetching groups containing the passed tags
withTags	boolean	used to fetch tags data along with the list of groups

Example In the example below, we are applying a filter to the Group List based on only joined groups and setting the limit to ten.

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

function App(): React.JSX.Element {
  const groupsRequestBuilder = new CometChat.GroupsRequestBuilder()
    .setLimit(10)
    .joinedOnly(true);

  return (
    <CometChatGroups
      groupsRequestBuilder={groupsRequestBuilder}
    />
  );
}

2. SearchRequestBuilder

The SearchRequestBuilder uses GroupsRequestBuilder enables you to filter and customize the search list based on available parameters in GroupsRequestBuilder. Example

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

function App(): React.JSX.Element {
  const searchRequestBuilder = new CometChat.GroupsRequestBuilder()
    .setLimit(10)
    .setSearchKeyword("custom-keyword");

  return (
    <CometChatGroups
      searchRequestBuilder={searchRequestBuilder}
    />
  );
}

Events

Events are emitted by a Component. By using event you can extend existing functionality. Being global events, they can be applied in Multiple Locations and are capable of being Added or Removed. The list of events emitted by the Groups component is as follows.

Events	Description
`ccGroupCreated`	This will get triggered when the logged in user creates a group
`ccGroupDeleted`	This will get triggered when the logged in user deletes a group
`ccGroupLeft`	This will get triggered when the logged in user leaves a group
`ccGroupMemberScopeChanged`	This will get triggered when the logged in user changes the scope of another group member
`ccGroupMemberBanned`	This will get triggered when the logged in user bans a group member from the group
`ccGroupMemberKicked`	This will get triggered when the logged in user kicks another group member from the group
`ccGroupMemberUnbanned`	This will get triggered when the logged in user unbans a user banned from the group
`ccGroupMemberJoined`	This will get triggered when the logged in user joins a group
`ccGroupMemberAdded`	This will get triggered when the logged in user add new members to the group
`ccOwnershipChanged`	This will get triggered when the logged in user transfer the ownership of their group to some other member

1. Add `CometChatGroupEvents` Listener’s

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

CometChatUIEventHandler.addGroupListener("GROUP_LISTENER_ID", {
  ccGroupLeft: ({ leftGroup }) => {
    //code
  },
});

CometChatUIEventHandler.addGroupListener("GROUP_LISTENER_ID", {
  ccGroupDeleted: ({ group }) => {
    //code
  },
});

2. Removing `CometChatGroupEvents` Listener’s

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

CometChatUIEventHandler.removeGroupListener("GROUP_LISTENER_ID");

Customization

To fit your app’s design requirements, you can customize the appearance of the groups component. We provide exposed methods that allow you to modify the experience and behavior according to your specific needs.

Style

Using Style you can customize the look and feel of the component in your app, These parameters typically control elements such as the color, size, shape, and fonts used within the component.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
return (
  <CometChatGroups
    style={{
      titleStyle: {
        color: "#FBAA75",
      },
      titleSeparatorStyle: {
        borderBottomColor: "#FBAA75",
      },
      itemStyle: {
        avatarStyle: {
          containerStyle: {
            borderRadius: 8,
            backgroundColor: "#FBAA75",
          },
          imageStyle: {
            borderRadius: 8,
          },
        },
      },
    }}
  />
);

Functionality

These are a set of small functional customizations that allow you to fine-tune the overall experience of the component. With these, you can change text, set custom icons, and toggle the visibility of UI elements. Below is a list of customizations along with corresponding code snippets

Property	Description	Code
hideHeader	Used to toggle visibility for the toolbar/header	`hideHeader?: boolean`
showBackButton	Used to toggle visibility for back button	`showBackButton?: boolean`
hideSearch	Used to toggle visibility for search box	`hideSearch?: boolean`
hideError	Used to hide error on fetching users	`hideError?: boolean`
selectionMode	This method determines the selection mode for groups, enabling users to select either a single user or multiple groups at once.	`selectionMode='multiple'`
hideSubmitButton	Used to toggle the visibility of the submit button when selectionMode is enabled.	`hideSubmitButton={true}`
searchPlaceholderText	Used to set search placeholder text	`searchPlaceholderText=''`

Advanced

For advanced-level customization, you can set custom views to the component. This lets you tailor each aspect of the component to fit your exact needs and application aesthetics. You can create and define your views, layouts, and UI elements and then incorporate those into the component.

LoadingView

Configures a custom loading view displayed while groups are being fetched. Use Cases:

Show a spinner with “Loading groups…” text.
Display a skeleton loader for a smooth UI experience.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getLoadingView = (): JSX.Element => {
  //your custom loading view
  //return jsx;
};
return <CometChatGroups LoadingView={getLoadingView} />;

EmptyView

Defines a view that appears when no groups are available. Use Cases:

Show a message like “No groups found, create one now!”.
Display an illustration with a “Create New Group” button.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getEmptyView = (): JSX.Element => {
  //your custom empty view
  //return jsx;
};
return <CometChatGroups EmptyView={getEmptyView} />;

ErrorView

Configures the UI when an error occurs while fetching groups. Use Cases:

Display a retry button with “Failed to load groups, try again.”.
Show a friendly error illustration.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getErrorView = (): JSX.Element => {
  //your custom error view
  //return jsx;
};
return <CometChatGroups ErrorView={getErrorView} />;

LeadingView

Sets a custom leading view that appears at the start of each group item. Use Cases:

Display the group profile picture.
Add an icon indicating Public or Private groups.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getLeadingView = (item: CometChat.Group): JSX.Element => {
  //your custom leading view
  //return jsx;
};
return <CometChatGroups LeadingView={getLeadingView} />;

TitleView

Customizes the title view of each group item, which typically displays the group name. Use Cases:

Style group names with custom fonts and colors.
Show a verified badge for official groups.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getTitleView = (item: CometChat.Group): JSX.Element => {
  //your custom title view
  //return jsx;
};
return <CometChatGroups TitleView={getTitleView} />;

TrailingView

Allows custom elements to be added at the end of each group item, such as buttons or indicators. Use Cases:

Show unread message counts.
Add a quick Join or Leave button.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getTrailingView = (item: CometChat.Group): JSX.Element => {
  //your custom Trailing view
  //return jsx;
};
return <CometChatGroups TrailingView={getTrailingView} />;

ItemView

Assigns a fully custom ListItem layout to the Groups component, replacing the default design. Use Cases:

Add a description below the group name.
Customize layout to include additional metadata.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getItemView = (item: CometChat.Group): JSX.Element => {
  //your custom Item view
  //return jsx;
};
return <CometChatGroups ItemView={getItemView} />;

Example

SubTitleView

Customizes the subtitle view for each group item, which typically displays extra information. Use Cases:

Show last message preview.
Display the number of members.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
const getSubtitleView = (item: CometChat.Group): JSX.Element => {
  //your custom Subtitle view
  //return jsx;
};
return <CometChatGroups SubtitleView={getSubtitleView} />;

Example

AppBarOptions

Customizes the overflow menu (three-dot ⋮ icon) with additional options. Use Cases:

Add options like “Invite Members”, “Report Group”.
Enable admin-specific options like “Manage Group Settings”.

import { CometChatGroups } from "@cometchat/chat-uikit-react-native";
//code
return (
  <CometChatGroups
    AppBarOptions={() => {
      return (
        <TouchableOpacity
          onPress={() => {
            //do something
          }}
        >
          <Text>Custom App Bar Options</Text>
        </TouchableOpacity>
      );
    }}
  />
);

Example

options

This method sets a predefined list of actions that users can perform when they long press a user in the list. These options typically include:

Enable actions like “Mute Notifications”, “Leave Group”, “Pin Group”.
Provide admin-only actions like “Manage Members”, “Delete Group”.

By customizing these options, developers can provide a streamlined and contextually relevant user experience

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

const setMyOptions = (group: CometChat.Group) => {
    return [
      //options
    ];
  };


return (
  <CometChatGroups
    options={setMyOptions}
  />
);

addOptions

This method extends the existing set of actions available when users long press a group item. Unlike setOptionsDefines, which replaces the default options, addOptionsAdds allows developers to append additional actions without removing the default ones. Example use cases include:

Adding a “Report Spam” action
Introducing a “Save to Notes” option
Integrating third-party actions such as “Share to Cloud Storage”

This method provides flexibility in modifying user interaction capabilities.

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

const addOptions = (group: CometChat.Group) => {
    return [
      //options
    ];
  };


return (
  <CometChatGroups
    addOptions={addOptions}
  />
);

​Overview

​Usage

​Integration

​Actions

onItemPress

onItemLongPress

onBack

onSelection

onError

​Filters

1. GroupsRequestBuilder

2. SearchRequestBuilder

​Events

1. Add CometChatGroupEvents Listener’s

2. Removing CometChatGroupEvents Listener’s

​Customization

​Style

​Functionality

​Advanced

​LoadingView

​EmptyView

​ErrorView

​LeadingView

​TitleView

​TrailingView

​ItemView

​SubTitleView

​AppBarOptions

​options

​addOptions

Overview

Usage

Integration

Actions

Filters

Events

1. Add `CometChatGroupEvents` Listener’s

2. Removing `CometChatGroupEvents` Listener’s

Customization

Style

Functionality

Advanced

LoadingView

EmptyView

ErrorView

LeadingView

TitleView

TrailingView

ItemView

SubTitleView

AppBarOptions

options

addOptions