Upgrading From V5 - CometChat Docs

This guide helps you migrate from CometChat Flutter UI Kit V5 to V6. V6 is a major architectural refactor that introduces clean architecture with BLoC state management while maintaining the same user-facing widget APIs.

Key Changes

Area	V5	V6
State Management	Controllers (e.g. `CometChatUsersController`)	BLoC (`flutter_bloc: ^8.1.0`)
Architecture	Flat layout with controllers	Clean Architecture (bloc/data/domain/di)
Data Access	DataSource decorator chain	`MessageTemplateUtils` static methods
Extensions	Registered via `UIKitSettings`	Built-in, no registration needed
Shared UI	External `cometchat_uikit_shared` package	Single `cometchat_chat_uikit` package

Step-by-Step Migration

1. Update Imports

// V5 — two imports needed
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:cometchat_uikit_shared/cometchat_uikit_shared.dart';

// V6 — single import covers everything
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

2. Update Initialization

// V5
UIKitSettings settings = (UIKitSettingsBuilder()
  ..appId = "..."
  ..region = "..."
  ..authKey = "..."
  ..extensions = CometChatUIKitChatExtensions.getDefaultExtensions()
  ..aiFeature = CometChatUIKitChatAIFeatures.getDefaultAiFeatures()
).build();

// V6 — remove extensions and aiFeature
UIKitSettings settings = (UIKitSettingsBuilder()
  ..appId = "..."
  ..region = "..."
  ..authKey = "..."
).build();

3. Replace DataSource Calls

// V5
CometChatUIKit.getDataSource().getTextMessageBubble(msg, ctx, align);
ChatConfigurator.getDataSource().getAllMessageTemplates();

// V6
MessageTemplateUtils.getTextMessageBubble(msg, ctx, align);
MessageTemplateUtils.getAllMessageTemplates();

4. Update Dependencies

Install V6 via CLI (hosted on Cloudsmith):

dart pub add cometchat_chat_uikit:6.0.0-beta1 --hosted-url https://dart.cloudsmith.io/cometchat/cometchat/

Or add manually to pubspec.yaml:

dependencies:
  cometchat_chat_uikit:
    hosted: https://dart.cloudsmith.io/cometchat/cometchat/
    version: 6.0.0-beta1

5. State Management Migration (Advanced)

If you were directly using controllers:

// V5 — Controller
CometChatUsersController controller = CometChatUsersController(...);

// V6 — BLoC
BlocProvider(
  create: (_) => UsersBloc()..add(LoadUsers()),
  child: BlocBuilder<UsersBloc, UsersState>(
    builder: (context, state) {
      if (state is UsersLoaded) return buildUI(state.users);
      return const CircularProgressIndicator();
    },
  ),
);

Controller → BLoC Mapping

V5 Controller	V6 BLoC
`CometChatConversationsController`	`ConversationsBloc`
`CometChatUsersController`	`UsersBloc`
`CometChatGroupsController`	`GroupsBloc`
`CometChatGroupMembersController`	`GroupMembersBloc`
`CometChatMessageComposerController`	`MessageComposerBloc`
`CometChatMessageHeaderController`	`MessageHeaderBloc`
`CometChatMessageListController`	`MessageListBloc`

Migration Checklist

☐ Replace all CometChatXxxController usage with XxxBloc
☐ Replace CometChatUIKit.getDataSource().xxx() with MessageTemplateUtils.xxx()
☐ Remove extensions and aiFeature from UIKitSettings
☐ Replace cometchat_uikit_shared imports with cometchat_chat_uikit
☐ Test all features after migration

Property Changes

This section outlines the property changes between V5 and V6. V6 introduces BLoC-based state management and consolidates styling into ThemeData extensions.

Architectural Changes

Aspect	V5	V6
State Management	Controllers	BLoC
Data Source	`CometChatUIKit.getDataSource()`	`MessageTemplateUtils`
Extension Registration	`UIKitSettings.extensions`	Handled internally
Rich Text	Not available	Built-in rich text formatting
Code Blocks	Not available	Built-in code block support

Conversations

New Properties (V6)

Name	Type	Description
conversationsBloc	ConversationsBloc?	Provide a custom BLoC instance
routeObserver	RouteObserver?	Freeze rebuilds during navigation
hideSearch	bool?	Hide the search bar
searchReadOnly	bool?	Make search bar read-only
onSearchTap	VoidCallback?	Callback when search is tapped

Removed Properties (from V5)

Name	Description
theme	Replaced by ThemeData extensions
errorStateText, emptyStateText, loadingStateText	Use custom state views instead
stateCallBack	Use BLoC events instead
avatarStyle, statusIndicatorStyle, badgeStyle, receiptStyle, dateStyle	Consolidated into CometChatConversationsStyle
hideSeparator	Controlled via style
disableTyping	Handled internally
deleteConversationDialogStyle	Integrated into main style
disableMentions	Handled via text formatters

Message List

New Properties (V6)

Name	Type	Description
messageListBloc	MessageListBloc?	Provide a custom BLoC instance
enableConversationStarters	bool	Enable AI conversation starters
enableSmartReplies	bool	Enable AI smart replies
addTemplate	List<CometChatMessageTemplate>?	Add custom templates to existing ones
hideModerationView	bool	Hide moderation view

Removed Properties (from V5)

Name	Description
theme	Replaced by ThemeData extensions
scrollToBottomOnNewMessages	Handled internally
timestampAlignment	Controlled via style
messageInformationConfiguration	Handled via BLoC
reactionListConfiguration, reactionsConfiguration	Simplified

Message Composer

New Properties (V6)

Name	Type	Description
messageComposerBloc	MessageComposerBloc?	Provide a custom BLoC instance
hideSendButton	bool?	Hide send button
hideAttachmentButton	bool?	Hide attachment button
hideStickersButton	bool?	Hide sticker button
hideImageAttachmentOption	bool?	Hide image attachment
hideVideoAttachmentOption	bool?	Hide video attachment
hideAudioAttachmentOption	bool?	Hide audio attachment
hideFileAttachmentOption	bool?	Hide file attachment
hidePollsOption	bool?	Hide polls option
hideCollaborativeDocumentOption	bool?	Hide collaborative document
hideCollaborativeWhiteboardOption	bool?	Hide collaborative whiteboard
hideTakePhotoOption	bool?	Hide take photo option

Removed Properties (from V5)

Name	Description
theme	Replaced by ThemeData extensions
hideLiveReaction, liveReactionIcon, liveReactionIconURL	Feature removed
mediaRecorderStyle	Integrated into main style

Message Header

New Properties (V6)

Name	Type	Description
titleView	Widget? Function(Group?, User?, BuildContext)?	Custom title widget
leadingStateView	Widget? Function(Group?, User?, BuildContext)?	Custom leading widget
auxiliaryButtonView	Widget? Function(Group?, User?, BuildContext)?	Custom auxiliary button
hideVideoCallButton	bool?	Hide video call button
hideVoiceCallButton	bool?	Hide voice call button

Removed Properties (from V5)

Name	Description
theme	Replaced by ThemeData extensions
avatarStyle, statusIndicatorStyle	Consolidated into CometChatMessageHeaderStyle
privateGroupIcon, protectedGroupIcon	Handled via style
disableTyping	Handled internally

Users

New Properties (V6)

Name	Type	Description
usersBloc	UsersBloc?	Provide a custom BLoC instance
setOptions	Function?	Set long press actions
addOptions	Function?	Add to long press actions
trailingView	Widget? Function(BuildContext, User)?	Custom trailing widget
leadingView	Widget? Function(BuildContext, User)?	Custom leading widget
titleView	Widget? Function(BuildContext, User)?	Custom title widget

Removed Properties (from V5)

Name	Description
theme	Replaced by ThemeData extensions
listItemStyle, avatarStyle, statusIndicatorStyle	Consolidated into CometChatUsersStyle
options	Replaced by setOptions/addOptions

Groups

New Properties (V6)

Name	Type	Description
groupsBloc	GroupsBloc?	Provide a custom BLoC instance
groupTypeVisibility	bool	Hide group type icon
setOptions	Function?	Set long press actions
addOptions	Function?	Add to long press actions
trailingView	Widget? Function(BuildContext, Group)?	Custom trailing widget
leadingView	Widget? Function(BuildContext, Group)?	Custom leading widget
titleView	Widget? Function(BuildContext, Group)?	Custom title widget

Removed Properties (from V5)

Name	Description
theme	Replaced by ThemeData extensions
listItemStyle, avatarStyle, statusIndicatorStyle	Consolidated into CometChatGroupsStyle
options	Replaced by setOptions/addOptions

Group Members

New Properties (V6)

Name	Type	Description
hideKickMemberOption	bool?	Control kick member visibility
hideBanMemberOption	bool?	Control ban member visibility
hideScopeChangeOption	bool?	Control scope change visibility
usersStatusVisibility	bool	Control status indicator visibility

Renamed Properties

V5 Name	V6 Name	Description
tailView	trailingView	Custom trailing widget
disableUsersPresence	usersStatusVisibility	Inverted logic
groupMemberStyle	style	Type changed to CometChatGroupMembersStyle

​Key Changes

​Step-by-Step Migration

​1. Update Imports

​2. Update Initialization

​3. Replace DataSource Calls

​4. Update Dependencies

​5. State Management Migration (Advanced)

​Controller → BLoC Mapping

​Migration Checklist

​Property Changes

​Architectural Changes

​Conversations

​New Properties (V6)

​Removed Properties (from V5)

​Message List

​New Properties (V6)

​Removed Properties (from V5)

​Message Composer

​New Properties (V6)

​Removed Properties (from V5)

​Message Header

​New Properties (V6)

​Removed Properties (from V5)

​Users

​New Properties (V6)

​Removed Properties (from V5)

​Groups

​New Properties (V6)

​Removed Properties (from V5)

​Group Members

​New Properties (V6)

​Renamed Properties

Key Changes

Step-by-Step Migration

1. Update Imports

2. Update Initialization

3. Replace DataSource Calls

4. Update Dependencies

5. State Management Migration (Advanced)

Controller → BLoC Mapping

Migration Checklist

Property Changes

Architectural Changes

Conversations

New Properties (V6)

Removed Properties (from V5)

Message List

New Properties (V6)

Removed Properties (from V5)

Message Composer

New Properties (V6)

Removed Properties (from V5)

Message Header

New Properties (V6)

Removed Properties (from V5)

Users

New Properties (V6)

Removed Properties (from V5)

Groups

New Properties (V6)

Removed Properties (from V5)

Group Members

New Properties (V6)

Renamed Properties