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.

---

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