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

# Group Members

> Scrollable list of members in a group with scope indicators, search, and member management actions.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Component | `CometChatGroupMembers` |
  | Package | `cometchat_chat_uikit` |
  | Import | `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';` |
  | Purpose | Scrollable list of members in a group with scope indicators, search, and member management actions. |
  | Data props | `groupMembersRequestBuilder` · `group` · `searchKeyword` |
  | Actions | `onSelection` · `onError` · `onBack` · `onItemTap` · `onItemLongPress` · `onLoad` · `onEmpty` — [details](#actions-and-events) |
  | View slots | `subtitleView` · `listItemView` · `loadingStateView` · `emptyStateView` · `errorStateView` · `trailingView` · `leadingView` · `titleView` — [details](#custom-view-slots) |
  | Styling | `style` — the app `ThemeData` does not reach inside a kit widget, so scope colours here. |
  | Layout | Fills its parent — place it in an `Expanded` (or a sized box) inside a `Column`, or layout throws an unbounded-height error at render. |
  | Prerequisites | `CometChatUIKit` initialised and a user logged in. |
  | Full props | [45 props](#functionality) |
</Accordion>

`CometChatGroupMembers` renders a scrollable list of members in a specific group with real-time updates, scope indicators (owner/admin/moderator/participant), search, and member management actions (kick, ban, change scope).

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/cTCXebw8IhR7IiJw/images/3e09e39d-group_members-697dfef4da0b9d955ec567bd58b54bfb.png?fit=max&auto=format&n=cTCXebw8IhR7IiJw&q=85&s=73e8bb18a5fdb1acd9039a0f1b00feec" width="2560" height="1600" data-path="images/3e09e39d-group_members-697dfef4da0b9d955ec567bd58b54bfb.png" />
</Frame>

***

## Where It Fits

`CometChatGroupMembers` is a list component that requires a `Group` object. It renders group members and supports actions like kick, ban, and scope change based on the logged-in user's permissions.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onItemTap: (groupMember) {
        // Navigate to member profile or chat
      },
    )
    ```
  </Tab>
</Tabs>

***

## Quick Start

Using Navigator:

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

Embedding as a widget:

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

Prerequisites: CometChat SDK initialized, a user logged in, and a valid `Group` object.

***

## Filtering Members

Pass a `GroupMembersRequestBuilder` to control what loads:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      groupMembersRequestBuilder: GroupMembersRequestBuilder(group.guid)
        ..limit = 20
        ..searchKeyword = "john",
    )
    ```
  </Tab>
</Tabs>

### Filter Recipes

| Recipe | Builder property |
| - | - |
| Limit per page | `..limit = 20` |
| Search by name | `..searchKeyword = "john"` |
| Filter by scopes | `..scopes = ["admin", "moderator"]` |

***

## Actions and Events

### Callback Methods

#### `onItemTap`

Fires when a member row is tapped.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onItemTap: (groupMember) {
        // Navigate to member profile
      },
    )
    ```
  </Tab>
</Tabs>

#### `onItemLongPress`

Fires when a member row is long-pressed. By default shows the member action menu (kick/ban/scope change).

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onItemLongPress: (groupMember) {
        // Custom long press behavior
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBack`

Fires when the user presses the back button.

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

#### `onSelection`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      selectionMode: SelectionMode.multiple,
      onSelection: (selectedMembers) {
        // Handle selected members
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

Fires on internal errors.

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

#### `onLoad`

Fires when the list is successfully fetched.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      onLoad: (memberList) {
        debugPrint("Loaded ${memberList.length} members");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onEmpty`

Fires when the list is empty after loading.

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

### Global Events

The component emits events via `CometChatGroupEvents`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    class _YourScreenState extends State<YourScreen> with CometChatGroupEventListener {
      @override
      void initState() {
        super.initState();
        CometChatGroupEvents.addGroupsListener("listenerId", this);
      }

      @override
      void dispose() {
        CometChatGroupEvents.removeGroupsListener("listenerId");
        super.dispose();
      }

      @override
      void ccGroupMemberKicked(Action action, User kickedUser, User kickedBy, Group kickedFrom) {
        // Handle member kicked
      }

      @override
      void ccGroupMemberBanned(Action action, User bannedUser, User bannedBy, Group bannedFrom) {
        // Handle member banned
      }

      @override
      void ccGroupMemberScopeChanged(Action action, User updatedUser, String scopeChangedTo, String scopeChangedFrom, Group group) {
        // Handle scope changed
      }
    }
    ```
  </Tab>
</Tabs>

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

| SDK Listener | Internal behavior |
| - | - |
| `onGroupMemberJoined` | Adds member to list |
| `onGroupMemberLeft` | Removes member from list |
| `onGroupMemberKicked` | Removes member from list |
| `onGroupMemberBanned` | Removes member from list |
| `onGroupMemberScopeChanged` | Updates member scope in list |
| `onUserOnline` / `onUserOffline` | Updates presence via per-member ValueNotifier (isolated rebuild) |
| Connection reconnected | Triggers silent refresh |

***

## Functionality

| Property | Type | Default | Description |
| - | - | - | - |
| `groupMembersProtocol` | `GroupMembersBuilderProtocol?` | `null` | Supplies the group-member list yourself instead of letting the widget fetch it. |
| `subtitleView` | `Widget? Function(BuildContext context, GroupMember groupMember)?` | `null` | Replaces the subtitle slot of each group member row. |
| `hideSeparator` | `bool?` | `null` | `hideSeparator` toggle separator visibility |
| `listItemView` | `Widget Function(GroupMember groupMember)?` | `null` | Replaces the entire group member row. Overrides the leading, title, subtitle and trailing slots. |
| `style` | `CometChatGroupMembersStyle?` | `null` | Style object for this widget. The app `ThemeData` does not reach inside a kit widget, so scope colours here. |
| `controller` | `ScrollController?` | `null` | Scroll controller for the list. |
| `searchPlaceholder` | `String?` | `null` | `searchPlaceholder` placeholder text of search input |
| `backButton` | `Widget?` | `null` | `backButton` back button |
| `showBackButton` | `bool` | `true` | Toggle back button |
| `searchBoxIcon` | `Widget?` | `null` | `searchBoxIcon` search box prefix icon |
| `hideSearch` | `bool` | `false` | Toggle search bar |
| `selectionMode` | `SelectionMode?` | `null` | Enable selection mode |
| `onSelection` | `Function(List<GroupMember>?)?` | `null` | Called with the selected group members when selection mode is confirmed. |
| `stateCallBack` | `Function(CometChatGroupMembersController controller)?` | `null` | Legacy stateCallBack — kept for backward compatibility. |
| `groupMembersRequestBuilder` | `GroupMembersRequestBuilder?` | `null` | Request builder used to fetch the group members. |
| `hideError` | `bool?` | `null` | `hideError` toggle visibility of error dialog |
| `loadingStateView` | `WidgetBuilder?` | `null` | `loadingStateView` is a parameter used to show the loading state view in case of loading |
| `emptyStateView` | `WidgetBuilder?` | `null` | `emptyStateView` returns view fow empty state |
| `errorStateView` | `WidgetBuilder?` | `null` | `errorStateView` is a parameter used to show the error state view in case of any error |
| `appBarOptions` | `List<Widget>?` | `null` | `appBarOptions` list of options to be visible in app bar |
| `options` | `List<CometChatOption>? Function( Group group, GroupMember member, CometChatGroupMembersController controller, BuildContext context, )?` | `null` | Legacy options callback — kept for backward compatibility. |
| `group` | `Group` | required | The group whose members to display |
| `trailingView` | `Function(BuildContext context, GroupMember groupMember)?` | `null` | Replaces the trailing slot of each group member row. |
| `selectIcon` | `Widget?` | `null` | Icon shown on a row while selection mode is active. |
| `submitIcon` | `Widget?` | `null` | `submitIcon` will override the default submit icon |
| `onError` | `OnError?` | `null` | Called when the list fails to load. |
| `onBack` | `VoidCallback?` | `null` | `onBack` callback triggered on closing a screen |
| `onItemTap` | `Function(GroupMember groupMember)?` | `null` | Called when a group member row is tapped. |
| `onItemLongPress` | `Function(GroupMember groupMember)?` | `null` | Called when a group member row is long-pressed. |
| `activateSelection` | `ActivateSelection?` | `null` | `activateSelection` lets the widget know if groups are allowed to be selected |
| `height` | `double?` | `null` | `height` provides height to the widget |
| `width` | `double?` | `null` | `width` provides width to the widget |
| `controllerTag` | `String?` | `null` | Group tag to create from, if this is passed its parent responsibility to close this @deprecated Use groupsBloc parameter for external bloc injection |
| `hideAppbar` | `bool?` | `null` | Toggle app bar visibility |
| `searchKeyword` | `String?` | `null` | `searchKeyword` Used to set searchKeyword to fetch initial list with |
| `onLoad` | `OnLoad<GroupMember>?` | `null` | Called once the first page of group members has loaded. |
| `onEmpty` | `OnEmpty?` | `null` | Called when the group member list resolves with no results. |
| `setOptions` | `List<CometChatOption>? Function( Group group, GroupMember groupMember, CometChatGroupMembersController controller, BuildContext context, )?` | `null` | Replaces the actions offered on a group member row. |
| `addOptions` | `List<CometChatOption>? Function( Group group, GroupMember groupMember, CometChatGroupMembersController controller, BuildContext context, )?` | `null` | Appends to the actions offered on a group member row. |
| `leadingView` | `Widget? Function(BuildContext context, GroupMember groupMember)?` | `null` | Replaces the leading slot of each group member row — the avatar area by default. |
| `titleView` | `Widget? Function(BuildContext context, GroupMember groupMember)?` | `null` | Replaces the title slot of each group member row. |
| `hideBanMemberOption` | `bool?` | `null` | Hide ban option in action menu |
| `hideKickMemberOption` | `bool?` | `null` | Hide kick option in action menu |
| `hideScopeChangeOption` | `bool?` | `null` | Hide scope change option |
| `usersStatusVisibility` | `bool?` | `true` | Show online/offline status |

***

## Custom View Slots

### Leading View

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

### Title View

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

### Subtitle View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      subtitleView: (context, groupMember) {
        return Text(
          groupMember.scope ?? "participant",
          style: TextStyle(color: Color(0xFF727272), fontSize: 14),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### Trailing View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      trailingView: (context, groupMember) {
        return Chip(label: Text(groupMember.scope ?? ""));
      },
    )
    ```
  </Tab>
</Tabs>

### List Item View

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      listItemView: (groupMember) {
        return ListTile(
          leading: CircleAvatar(child: Text(groupMember.name?[0] ?? "")),
          title: Text(groupMember.name ?? ""),
          subtitle: Text(groupMember.scope ?? "participant"),
          trailing: Chip(label: Text(groupMember.scope ?? "")),
        );
      },
    )
    ```
  </Tab>
</Tabs>

### State Views

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

***

## Menu Options

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    // Replace all options
    CometChatGroupMembers(
      group: group,
      setOptions: (groupMember, bloc, context) {
        return [
          CometChatOption(
            id: "message",
            iconWidget: Icon(Icons.message),
            title: "Message",
            onClick: () {
              // Open chat with this member
            },
          ),
        ];
      },
    )

    // Append to defaults
    CometChatGroupMembers(
      group: group,
      addOptions: (groupMember, bloc, context) {
        return [
          CometChatOption(
            id: "profile",
            iconWidget: Icon(Icons.person),
            title: "View Profile",
            onClick: () {
              // Open member profile
            },
          ),
        ];
      },
    )
    ```
  </Tab>
</Tabs>

***

## Advanced

### BLoC Access

Provide a custom `GroupMembersBloc`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      // Supply your own data source with groupMembersProtocol / groupMembersRequestBuilder,
      // and observe list state with stateCallBack — there is no `groupMembersBloc` parameter.
      groupMembersRequestBuilder: GroupMembersRequestBuilder(group.guid),
    )
    ```
  </Tab>
</Tabs>

### Public BLoC Events

| Event | Description |
| - | - |
| `LoadGroupMembers` | Load initial members |
| `LoadMoreGroupMembers` | Load next page (pagination) |
| `SearchGroupMembers(keyword)` | Search members |
| `KickMember(groupMember)` | Kick a member from the group |
| `BanMember(groupMember)` | Ban a member from the group |
| `ChangeMemberScope(groupMember, newScope)` | Change member's scope |
| `ToggleMemberSelection(uid)` | Toggle selection state |
| `ClearMemberSelection` | Clear all selections |

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

### Public BLoC Methods

| Method | Returns | Description |
| - | - | - |
| `getStatusNotifier(uid)` | `ValueNotifier<String>` | Per-member status notifier for isolated rebuilds |

### Permission-Based Actions

Member actions (kick, ban, scope change) are permission-aware based on the logged-in user's scope:

| Logged-in User Scope | Can Kick | Can Ban | Can Change Scope |
| - | - | - | - |
| Owner | All members | All members | All members |
| Admin | Moderators, Participants | Moderators, Participants | Moderators, Participants |
| Moderator | Participants | Participants | No |
| Participant | No | No | No |

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatGroupMembers(
      group: group,
      style: CometChatGroupMembersStyle(
        avatarStyle: CometChatAvatarStyle(
          borderRadius: BorderRadius.circular(8),
          backgroundColor: Color(0xFFFBAA75),
        ),
        statusIndicatorStyle: CometChatStatusIndicatorStyle(),
        changeScopeStyle: CometChatChangeScopeStyle(),
        confirmDialogStyle: CometChatConfirmDialogStyle(),
      ),
    )
    ```
  </Tab>
</Tabs>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/LUAnk4kNde8CLq7p/images/7dd6eb5e-group_members_styling-b9b1f40be76f7e4137dbd7dc7e10141c.png?fit=max&auto=format&n=LUAnk4kNde8CLq7p&q=85&s=3cf8e71e2feb3709aec5a1c9adeaa21c" width="2560" height="1600" data-path="images/7dd6eb5e-group_members_styling-b9b1f40be76f7e4137dbd7dc7e10141c.png" />
</Frame>

### Style Properties

| Property | Description |
| - | - |
| `avatarStyle` | Avatar appearance |
| `statusIndicatorStyle` | Online/offline indicator |
| `changeScopeStyle` | Scope change dialog style |
| `confirmDialogStyle` | Kick/ban confirmation dialog style |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Groups" icon="users" href="/ui-kit/flutter/groups">
    Browse available groups
  </Card>

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.