> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups

> Scrollable list of all available groups with search, avatars, group type indicators, and member counts.

`CometChatGroups` renders a scrollable list of all available groups with real-time updates for group events, search, avatars, group type indicators (public/private/password), and member counts.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/2SVOPiSpm0QEqRoz/images/e877cb7b-groups-dc2d2ca999ff476db4925ab838df28b9.png?fit=max&auto=format&n=2SVOPiSpm0QEqRoz&q=85&s=ad8970d0b253580664a8831ba04e00e4" width="2560" height="1600" data-path="images/e877cb7b-groups-dc2d2ca999ff476db4925ab838df28b9.png" />
</Frame>

***

## Where It Fits

`CometChatGroups` is a list component. It renders all available groups and emits the selected `Group` via `onItemTap`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a group chat layout.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onItemTap: (context, group) {
        // Navigate to group chat
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatGroups()));
    ```
  </Tab>
</Tabs>

Embedding as a widget:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    @override
    Widget build(BuildContext context) {
      return Scaffold(
        body: SafeArea(
          child: CometChatGroups(),
        ),
      );
    }
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added.

***

## Filtering Groups

Pass a `GroupsRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsRequestBuilder: GroupsRequestBuilder()
        ..limit = 10
        ..searchKeyword = "team",
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe             | Builder property           |
| ------------------ | -------------------------- |
| Limit per page     | `..limit = 10`             |
| Search by keyword  | `..searchKeyword = "team"` |
| Joined groups only | `..joinedOnly = true`      |
| Filter by tags     | `..tags = ["project"]`     |
| With tags          | `..withTags = true`        |

***

## Actions and Events

### Callback Methods

#### `onItemTap`

Fires when a group row is tapped. Primary navigation hook.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onItemTap: (context, group) {
        // Navigate to group chat screen
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a group row is long-pressed.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onItemLongPress: (context, group) {
        // Show context menu
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button in the app bar.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onBack: () {
        Navigator.pop(context);
      },
    )
    ```
  </Tab>
</Tabs>

#### `onSelection`

Fires when groups are selected/deselected in multi-select mode.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      selectionMode: SelectionMode.multiple,
      onSelection: (selectedGroups, context) {
        // Handle selected groups
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onError: (e) {
        debugPrint("Error: ${e.message}");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onLoad`

Fires when the list is successfully fetched and loaded.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onLoad: (groupList) {
        debugPrint("Loaded ${groupList.length} groups");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      onEmpty: () {
        debugPrint("No groups found");
      },
    )
    ```
  </Tab>
</Tabs>

### SDK Events (Real-Time, Automatic)

The component listens to these SDK events internally. No manual setup needed.

| SDK Listener           | Internal behavior                                                      |
| ---------------------- | ---------------------------------------------------------------------- |
| `onGroupMemberJoined`  | Updates group member count                                             |
| `onGroupMemberLeft`    | Updates group member count                                             |
| `onGroupMemberKicked`  | Updates group member count, removes group if logged-in user was kicked |
| `onGroupMemberBanned`  | Updates group member count, removes group if logged-in user was banned |
| `onMemberAddedToGroup` | Updates group member count                                             |
| `ccGroupCreated`       | Adds new group to list                                                 |
| `ccGroupDeleted`       | Removes group from list                                                |
| Connection reconnected | Triggers silent refresh                                                |

***

## Functionality

| Property            | Type             | Default | Description                                    |
| ------------------- | ---------------- | ------- | ---------------------------------------------- |
| `title`             | `String?`        | `null`  | Custom app bar title                           |
| `showBackButton`    | `bool`           | `true`  | Toggle back button                             |
| `hideAppbar`        | `bool?`          | `false` | Toggle app bar visibility                      |
| `hideSearch`        | `bool`           | `false` | Toggle search bar                              |
| `selectionMode`     | `SelectionMode?` | `null`  | Enable selection mode (`single` or `multiple`) |
| `searchPlaceholder` | `String?`        | `null`  | Search placeholder text                        |

***

## Custom View Slots

### Leading View

Replace the avatar / left section.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      leadingView: (context, group) {
        return CircleAvatar(
          child: Text(group.name?[0] ?? "G"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Title View

Replace the group name / title text.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      titleView: (context, group) {
        return Text(
          group.name ?? "",
          style: TextStyle(fontWeight: FontWeight.bold),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Subtitle View

Replace the subtitle text below the group name.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      subtitleView: (context, group) {
        return Text(
          "${group.membersCount} members",
          style: TextStyle(color: Color(0xFF727272), fontSize: 14),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

Replace the right section of each group item.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      trailingView: (context, group) {
        return Text(group.type ?? "");
      },
    )
    ```
  </Tab>
</Tabs>

### List Item View

Replace the entire list item row.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      listItemView: (group) {
        return ListTile(
          leading: CircleAvatar(child: Text(group.name?[0] ?? "G")),
          title: Text(group.name ?? ""),
          subtitle: Text("${group.membersCount} members"),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      emptyStateView: (context) => Center(child: Text("No groups found")),
      errorStateView: (context) => Center(child: Text("Something went wrong")),
      loadingStateView: (context) => Center(child: CircularProgressIndicator()),
    )
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Minimal list — hide all chrome

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      hideAppbar: true,
      hideSearch: true,
    )
    ```
  </Tab>
</Tabs>

### Joined groups only

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsRequestBuilder: GroupsRequestBuilder()
        ..joinedOnly = true,
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `GroupsBloc` to override behavior:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsBloc: CustomGroupsBloc(),
    )
    ```
  </Tab>
</Tabs>

### Extending GroupsBloc

`GroupsBloc` uses the `ListBase<Group>` mixin with override hooks:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class CustomGroupsBloc extends GroupsBloc {
      @override
      void onItemAdded(Group item, List<Group> updatedList) {
        // Custom sorting logic
        super.onItemAdded(item, updatedList);
      }

      @override
      void onListReplaced(List<Group> previousList, List<Group> newList) {
        // Filter out specific groups
        final filtered = newList.where((g) => g.membersCount > 0).toList();
        super.onListReplaced(previousList, filtered);
      }
    }
    ```
  </Tab>
</Tabs>

For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/ui-kit/flutter/customization-bloc-data#listbase-hooks).

### Public BLoC Events

| Event                                 | Description                                                      |
| ------------------------------------- | ---------------------------------------------------------------- |
| `LoadGroups({searchKeyword, silent})` | Load initial groups. `silent: true` keeps existing list visible. |
| `LoadMoreGroups()`                    | Load next page (pagination)                                      |
| `RefreshGroups()`                     | Refresh the list                                                 |
| `SearchGroups(keyword)`               | Search groups with debouncing                                    |

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroups(
      groupsStyle: CometChatGroupsStyle(
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        statusIndicatorStyle: CometChatStatusIndicatorStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/FGBCGWXGo5d9bVxR/images/c43fe4f4-groups_styling-107ad9e9a3daa796d657515d719c04f6.png?fit=max&auto=format&n=FGBCGWXGo5d9bVxR&q=85&s=189d45b8fd4f19fb3adb5066f1d12546" width="2560" height="1600" data-path="images/c43fe4f4-groups_styling-107ad9e9a3daa796d657515d719c04f6.png" />
</Frame>

### Style Properties

| Property               | Description           |
| ---------------------- | --------------------- |
| `backgroundColor`      | List background color |
| `avatarStyle`          | Avatar appearance     |
| `statusIndicatorStyle` | Group type indicator  |
| `searchBoxStyle`       | Search box appearance |

See [Component Styling](/ui-kit/flutter/component-styling) for the full reference.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Group Members" icon="users" href="/ui-kit/flutter/group-members">
    View and manage group members
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/flutter/conversations">
    Browse recent conversations
  </Card>

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Detailed styling reference
  </Card>

  <Card title="Group Chat Guide" icon="book" href="/ui-kit/flutter/guide-group-chat">
    Complete group chat implementation
  </Card>
</CardGroup>