cometchat-flutter-v5-users-groups

name	cometchat-flutter-v5-users-groups
description	Use when working with CometChat Flutter UIKit v5 user and group list components. Triggers on CometChatUsers, CometChatGroups, CometChatGroupMembers, CometChatChangeScope.
license	MIT
compatibility	cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3
metadata	{"author":"CometChat","version":"3.0.0","tags":"cometchat flutter v5 users groups members scope contacts"}

Ground truth: cometchat_chat_uikit: ^5.2 (legacy/maintenance-only; calls via raw cometchat_calls_sdk ^5.0.2) — pub-cache source + ui-kit/flutter/v5. Official docs: https://www.cometchat.com/docs/ui-kit/flutter/v5/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

CometChat Flutter UIKit v5 — Users & Groups

Components for displaying and managing users, groups, and group members.

CometChatUsers

Displays a list of users, sorted alphabetically.

Key Props

Prop	Type	Default	Description
usersRequestBuilder	UsersRequestBuilder?	—	Custom fetch builder
usersStyle	CometChatUsersStyle	const CometChatUsersStyle()	Visual styling
onItemTap	Function(BuildContext, User)?	—	Tap callback (includes BuildContext)
onItemLongPress	Function(BuildContext, User)?	—	Long press callback
subtitleView	Widget? Function(BuildContext, User)?	—	Custom subtitle
title	String?	—	List title
showBackButton	bool	true	Show back button
hideSearch	bool	false	Hide search bar
selectionMode	SelectionMode?	—	Enable selection mode
onSelection	Function(List<User>?, BuildContext)?	—	Selection callback
usersStatusVisibility	bool?	true	Show online status
hideAppbar	bool?	false	Hide app bar
appBarOptions	List<Widget> Function(BuildContext)?	—	App bar trailing widgets
controllerTag

Usage

CometChatUsers(
  onItemTap: (context, user) {
    Navigator.push(context, MaterialPageRoute(
      builder: (_) => MessagesScreen(user: user),
    ));
  },
)

// With custom request builder
CometChatUsers(
  usersRequestBuilder: UsersRequestBuilder()
    ..limit = 30
    ..friendsOnly = true,
)

// Filter by role (e.g., AI agents)
CometChatUsers(
  title: "Agents",
  usersRequestBuilder: UsersRequestBuilder()
    ..roles = [AIConstants.aiRole],
  onItemTap: (context, user) { ... },
)

CometChatGroups

Displays a list of groups with type indicators.

Key Props

Prop	Type	Default	Description
groupsRequestBuilder	GroupsRequestBuilder?	—	Custom fetch builder
groupsStyle	CometChatGroupsStyle?	—	Visual styling
onItemTap	Function(BuildContext, Group)?	—	Tap callback (includes BuildContext)
onItemLongPress	Function(BuildContext, Group)?	—	Long press callback
subtitleView	Widget? Function(BuildContext, Group)?	—	Custom subtitle
title	String?	—	List title
showBackButton	bool	true	Show back button
hideSearch	bool	false	Hide search bar
selectionMode	SelectionMode?	—	Enable selection mode
groupTypeVisibility	bool	true	Show group type icon
hideAppbar	bool?	false	Hide app bar
appBarOptions	List<Widget> Function(BuildContext)?	—	App bar trailing widgets
controllerTag	String?	—	Custom GetX controller tag

Usage

CometChatGroups(
  onItemTap: (context, group) {
    Navigator.push(context, MaterialPageRoute(
      builder: (_) => MessagesScreen(group: group),
    ));
  },
)

CometChatGroupMembers

Displays members of a specific group with role indicators.

CometChatGroupMembers(
  group: group,
  onItemTap: (member) {
    debugPrint('Tapped: ${member.name}, role: ${member.scope}');
  },
)

Key props: group (required), groupMembersRequestBuilder, style (CometChatGroupMembersStyle? — prop name is style, NOT groupMembersStyle; verified cometchat_group_members.dart:25/88), subtitleView, trailingView, onItemTap (Function(GroupMember)? — no BuildContext), selectionMode, onSelection (Function(List<GroupMember>?)? — no BuildContext).

CometChatChangeScope

Widget for changing a group member's scope/role.

CometChatChangeScope(group: group, member: member)

Callback Signature Differences

Component	onItemTap signature
CometChatConversations	Function(Conversation)? — no BuildContext
CometChatUsers	Function(BuildContext, User)? — has BuildContext
CometChatGroups	Function(BuildContext, Group)? — has BuildContext
CometChatGroupMembers	Function(GroupMember)? — no BuildContext

This is a common source of confusion.

Anti-Patterns

// ❌ WRONG — missing BuildContext in Users/Groups onItemTap
CometChatUsers(onItemTap: (user) { ... }) // Missing BuildContext!

// ✅ CORRECT
CometChatUsers(onItemTap: (context, user) { ... })
CometChatGroups(onItemTap: (context, group) { ... })

Checklist — Users & Groups

• onItemTap callback signature includes BuildContext for Users/Groups
• Custom request builders set appropriate limits
• Let widgets manage their own GetX controller lifecycle