Skip to main content

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.

Minimal Render

You can also launch it using Navigator.push:

Filtering Groups

Pass a GroupsRequestBuilder to groupsRequestBuilder. Pass the builder instance — not the result of .build().

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.

onItemLongPress

Fires when a group row is long-pressed. Useful for showing context menus or custom actions.

onSelection

Fires when groups are selected in multi-select mode. Requires selectionMode to be set.

onError

Fires on internal errors (network failure, auth issue, SDK exception).

onBack

Fires when the back button is pressed.

onLoad

Fires when the group list is successfully loaded.

onEmpty

Fires when the group list is empty.

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.

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 the Group object for that row.

listItemView

Replace the entire list item row.

leadingView

Replace the avatar / left section. Joined status badge example.

titleView

Replace the name / title text. Group type badge inline example.

subtitleView

Replace the member count subtitle text.

trailingView

Replace the right section. Join status button example.

setOptions

Replace the context menu / long-press actions on each group item.

addOptions

Add to the existing context menu actions without removing defaults.

appBarOptions

Add custom widgets to the app bar.

Styling

Set CometChatGroupsStyle to customize the appearance.

Style Properties


Common Patterns

Custom empty state with CTA

Joined groups only

Multi-select with selection callback

Hide all chrome — minimal list


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
For screen readers:
  • Group names are readable as list item titles
  • Group type indicators use icons — consider adding Semantics widgets via leadingView if screen reader descriptions are needed
  • Selection state is communicated through checkbox widgets
The component respects system accessibility settings including text scaling and high contrast modes.

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. Requires selectionMode 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