Cometchat flutter v5 conversations

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 — Conversations

The CometChatConversations component displays a list of recent conversations.

Key Props

Prop	Type	Default	Description
conversationsRequestBuilder	ConversationsRequestBuilder?	—	Custom fetch builder
conversationsStyle	CometChatConversationsStyle	const CometChatConversationsStyle()	Visual styling
onItemTap	Function(Conversation)?	—	Tap callback (no BuildContext)
onItemLongPress	Function(Conversation)?	—	Long press callback
subtitleView	Widget? Function(BuildContext, Conversation)?	—	Custom subtitle
listItemView	Widget Function(Conversation)?	—	Custom list item (replaces the whole row)
leadingView	Widget? Function(BuildContext, Conversation)?	—	Custom leading widget (avatar slot)
titleView	Widget? Function(BuildContext, Conversation)?	—	Custom title widget
trailingView	Widget? Function(Conversation)?	—	Custom trailing widget (single-arg — asymmetric with the other slots)
title	String?	—	List title
showBackButton	bool	false	Show back button
onBack	VoidCallback?	—	Back button callback
hideAppbar	bool?	false	Hide app bar
appBarOptions	List<Widget>?	—	App bar trailing widgets
usersStatusVisibility	bool?	true	Show online status
receiptsVisibility	bool?	true	Show read receipts
textFormatters	List<CometChatTextFormatter>?	—	Text formatters for subtitles
controllerTag	String?	—	Custom GetX controller tag
hideSearch	bool?	—	Hide search bar
searchReadOnly	bool	false	Read-only search
onSearchTap	GestureTapCallback?	—	Search tap callback
deleteConversationOptionVisibility	bool?	true	Show delete option
loadingStateView	WidgetBuilder?	—	Custom loading state
emptyStateView	WidgetBuilder?	—	Custom empty state
errorStateView	WidgetBuilder?	—	Custom error state
setOptions	Function?	—	Replace long-press options
addOptions	Function?	—	Add to long-press options

Basic Usage

CometChatConversations(
  onItemTap: (conversation) {
    User? user;
    Group? group;
    if (conversation.conversationWith is User) {
      user = conversation.conversationWith as User;
    } else {
      group = conversation.conversationWith as Group;
    }
    Navigator.push(context, MaterialPageRoute(
      builder: (_) => MessagesScreen(user: user, group: group),
    ));
  },
)

Custom Request Builder

CometChatConversations(
  conversationsRequestBuilder: ConversationsRequestBuilder()
    ..limit = 30
    ..conversationType = ConversationType.user,
)

Internal Architecture (GetX)

The component creates CometChatConversationsController via Get.put() in initState() and deletes it in dispose() (unless controllerTag is provided externally).

Theme values are cached in didChangeDependencies() (unconditionally, no flag):

@override
void didChangeDependencies() {
  typography = CometChatThemeHelper.getTypography(context);
  colorPalette = CometChatThemeHelper.getColorPalette(context);
  spacing = CometChatThemeHelper.getSpacing(context);
  style = CometChatThemeHelper.getTheme<CometChatConversationsStyle>(
      context: context, defaultTheme: CometChatConversationsStyle.of)
    .merge(widget.conversationsStyle);
  super.didChangeDependencies();
}

Anti-Patterns

// ❌ WRONG — trying to access controller before component mounts
final controller = Get.find<CometChatConversationsController>();

// ❌ WRONG — manually creating controller outside the widget
Get.put(CometChatConversationsController(...));

// ❌ WRONG — not extracting User/Group from conversation
onItemTap: (conversation) {
  Navigator.push(context, MaterialPageRoute(
    builder: (_) => MessagesScreen(user: conversation.conversationWith), // Type error
  ));
}

Checklist — Conversations

• onItemTap extracts User/Group from conversation.conversationWith with type check
• Navigation to messages screen passes extracted user or group
• Let the widget manage its own GetX controller lifecycle