Groups - CometChat Docs

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.

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.

Dart

CometChatGroups(
  onItemTap: (context, group) {
    // Navigate to group chat
  },
)

Quick Start

Using Navigator:

Dart

Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatGroups()));

Embedding as a widget:

Dart

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SafeArea(
      child: CometChatGroups(),
    ),
  );
}

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:

Dart

CometChatGroups(
  groupsRequestBuilder: GroupsRequestBuilder()
    ..limit = 10
    ..searchKeyword = "team",
)

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.

Dart

CometChatGroups(
  onItemTap: (context, group) {
    // Navigate to group chat screen
  },
)

`onItemLongPress`

Fires when a group row is long-pressed.

Dart

CometChatGroups(
  onItemLongPress: (context, group) {
    // Show context menu
  },
)

`onBack`

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

Dart

CometChatGroups(
  onBack: () {
    Navigator.pop(context);
  },
)

`onSelection`

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

Dart

CometChatGroups(
  selectionMode: SelectionMode.multiple,
  onSelection: (selectedGroups, context) {
    // Handle selected groups
  },
)

`onError`

Fires on internal errors.

Dart

CometChatGroups(
  onError: (e) {
    debugPrint("Error: ${e.message}");
  },
)

`onLoad`

Fires when the list is successfully fetched and loaded.

Dart

CometChatGroups(
  onLoad: (groupList) {
    debugPrint("Loaded ${groupList.length} groups");
  },
)

`onEmpty`

Fires when the list is empty after loading.

Dart

CometChatGroups(
  onEmpty: () {
    debugPrint("No groups found");
  },
)

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.

Dart

CometChatGroups(
  leadingView: (context, group) {
    return CircleAvatar(
      child: Text(group.name?[0] ?? "G"),
    );
  },
)

Title View

Replace the group name / title text.

Dart

CometChatGroups(
  titleView: (context, group) {
    return Text(
      group.name ?? "",
      style: TextStyle(fontWeight: FontWeight.bold),
    );
  },
)

Subtitle View

Replace the subtitle text below the group name.

Dart

CometChatGroups(
  subtitleView: (context, group) {
    return Text(
      "${group.membersCount} members",
      style: TextStyle(color: Color(0xFF727272), fontSize: 14),
    );
  },
)

Trailing View

Replace the right section of each group item.

Dart

CometChatGroups(
  trailingView: (context, group) {
    return Text(group.type ?? "");
  },
)

List Item View

Replace the entire list item row.

Dart

CometChatGroups(
  listItemView: (group) {
    return ListTile(
      leading: CircleAvatar(child: Text(group.name?[0] ?? "G")),
      title: Text(group.name ?? ""),
      subtitle: Text("${group.membersCount} members"),
    );
  },
)

State Views

Dart

CometChatGroups(
  emptyStateView: (context) => Center(child: Text("No groups found")),
  errorStateView: (context) => Center(child: Text("Something went wrong")),
  loadingStateView: (context) => Center(child: CircularProgressIndicator()),
)

Common Patterns

Minimal list — hide all chrome

Dart

CometChatGroups(
  hideAppbar: true,
  hideSearch: true,
)

Joined groups only

Dart

CometChatGroups(
  groupsRequestBuilder: GroupsRequestBuilder()
    ..joinedOnly = true,
)

Advanced

BLoC Access

Provide a custom GroupsBloc to override behavior:

Dart

CometChatGroups(
  groupsBloc: CustomGroupsBloc(),
)

Extending GroupsBloc

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

Dart

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);
  }
}

For ListBase override hooks (onItemAdded, onItemRemoved, onItemUpdated, onListCleared, onListReplaced), see 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

Dart

CometChatGroups(
  groupsStyle: CometChatGroupsStyle(
    avatarStyle: CometChatAvatarStyle(
      borderRadius: BorderRadius.circular(8),
      backgroundColor: Color(0xFFFBAA75),
    ),
    statusIndicatorStyle: CometChatStatusIndicatorStyle(),
  ),
)

Style Properties

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

See Component Styling for the full reference.

Next Steps

Group Members

View and manage group members

Conversations

Browse recent conversations

Component Styling

Detailed styling reference

Group Chat Guide

Complete group chat implementation

​Where It Fits

​Quick Start

​Filtering Groups

​Filter Recipes

​Actions and Events

​Callback Methods

​onItemTap

​onItemLongPress

​onBack

​onSelection

​onError

​onLoad

​onEmpty

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​Leading View

​Title View

​Subtitle View

​Trailing View

​List Item View

​State Views

​Common Patterns

​Minimal list — hide all chrome

​Joined groups only

​Advanced

​BLoC Access

​Extending GroupsBloc

​Public BLoC Events

​Style

​Style Properties

​Next Steps