AI Agent Component Spec
AI Agent Component Spec
Where It Fits
CometChatGroups is a directory list widget. It renders available groups and emits the selected Group via onItemTap. Wire it to CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer to build a group chat layout.
- Dart

Minimal Render
- Dart
Navigator.push:
Filtering Groups
Pass aGroupsRequestBuilder to groupsRequestBuilder. Pass the builder instance — not the result of .build().
- Dart
Filter Recipes
Default page size is 30. The component uses infinite scroll — the next page loads as the user scrolls to the bottom.
GroupsRequestBuilder Properties
Refer to GroupsRequestBuilder for the full builder API.
Actions and Events
Callback Props
onItemTap
Fires when a group row is tapped. Primary navigation hook — set the active group and render the message view.- Dart
onItemLongPress
Fires when a group row is long-pressed. Useful for showing context menus or custom actions.- Dart
onSelection
Fires when groups are selected in multi-select mode. RequiresselectionMode to be set.
- Dart
onError
Fires on internal errors (network failure, auth issue, SDK exception).- Dart
onBack
Fires when the back button is pressed.- Dart
onLoad
Fires when the group list is successfully loaded.- Dart
onEmpty
Fires when the group list is empty.- Dart
Global UI Events
CometChatGroupEvents emits events subscribable from anywhere in the application. Add a listener in initState and remove it in dispose.
When to use: sync external UI with group state changes. For example, update a group count badge when a group is created or deleted.
- Dart
SDK Events (Real-Time, Automatic)
The component listens to these SDK events internally. No manual attachment needed unless additional side effects are required.
Automatic: group membership changes, member count updates.
Custom View Slots
Each slot replaces a section of the default UI. Slots that accept a group parameter receive theGroup object for that row.
listItemView
Replace the entire list item row.
- Dart
leadingView
Replace the avatar / left section. Joined status badge example.- Dart
titleView
Replace the name / title text. Group type badge inline example.- Dart
subtitleView
Replace the member count subtitle text.
- Dart
trailingView
Replace the right section. Join status button example.- Dart
setOptions
Replace the context menu / long-press actions on each group item.- Dart
addOptions
Add to the existing context menu actions without removing defaults.- Dart
appBarOptions
Add custom widgets to the app bar.
- Dart
Styling
SetCometChatGroupsStyle to customize the appearance.
- Dart

Style Properties
Common Patterns
Custom empty state with CTA
- Dart
Joined groups only
- Dart
Multi-select with selection callback
- Dart
Hide all chrome — minimal list
- Dart
Accessibility
The component renders a scrollable list of interactive items. Each group row supports:- Tap gesture for selection/navigation
- Long-press gesture for context menu actions
- Checkbox selection in multi-select mode with proper touch targets
- Group type indicators (public/private/password) with visual icons
- Group names are readable as list item titles
- Group type indicators use icons — consider adding
Semanticswidgets vialeadingViewif screen reader descriptions are needed - Selection state is communicated through checkbox widgets
Props
All props are optional unless noted.activateSelection
Controls when selection mode activates.
Values:
ActivateSelection.onClick, ActivateSelection.onLongClick
addOptions
Adds additional context menu actions to the default options.appBarOptions
Custom widgets to display in the app bar.backButton
Custom back button widget.controllerTag
Identifier tag for controller management.emptyStateView
Custom view displayed when there are no groups.errorStateView
Custom view displayed when an error occurs.groupsProtocol
Custom protocol for fetching groups.groupsRequestBuilder
Controls which groups load and in what order.
Pass the builder instance, not the result of
.build().
groupsStyle
Styling options for the groups list.groupTypeVisibility
Shows or hides the group type icon (public/private/password) on group avatars.height
Height of the widget.hideAppbar
Hides the app bar including title and search.hideError
Hides the error state view.hideSearch
Hides the search input box.leadingView
Custom renderer for the avatar / left section.listItemView
Custom renderer for the entire list item row.loadingStateView
Custom view displayed during loading state.onBack
Callback triggered when the back button is pressed.onEmpty
Callback triggered when the group list is empty.onError
Callback triggered when an error occurs.onItemLongPress
Callback triggered on long press of a group item.onItemTap
Callback triggered when tapping a group item.onLoad
Callback triggered when the list is successfully loaded.onSelection
Callback triggered when groups are selected. RequiresselectionMode to be set.
passwordGroupIcon
Custom icon widget for password-protected groups.privateGroupIcon
Custom icon widget for private groups.scrollController
Controller for scrolling the list.searchBoxIcon
Custom search box icon widget.searchKeyword
Pre-fills the search and filters the group list.searchPlaceholder
Placeholder text for the search input box.selectionMode
Enables single or multi-select mode.
Values:
SelectionMode.single, SelectionMode.multiple, SelectionMode.none
setOptions
Replaces the default context menu actions.showBackButton
Shows or hides the back button.stateCallBack
Callback to access controller functions from parent.submitIcon
Custom submit icon widget for selection mode.subtitleView
Custom renderer for the member count subtitle.title
Title text displayed in the app bar.titleView
Custom renderer for the name / title text.trailingView
Custom renderer for the right section.width
Width of the widget.Events
CometChatGroups subscribes to CometChatGroupEvents:
Customization Matrix
Users
Display and manage user contacts
Conversations
Display recent one-on-one and group conversations
Group Members
Display and manage members of a group
Theming
Learn how to customize the look and feel