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

# Upgrade the CometChat Flutter UI Kit from V5 to V6

> Upgrade from CometChat Flutter UI Kit V5 to V6 with package changes, initialization updates, BLoC clean architecture, and step-by-step migration instructions.

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

```dart theme={null}
// 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

```dart theme={null}
// 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

```dart theme={null}
// V5
CometChatUIKit.getDataSource().getTextMessageBubble(msg, ctx, align);
ChatConfigurator.getDataSource().getAllMessageTemplates();

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

### 4. Update Dependencies

```yaml pubspec.yaml theme={null}
dependencies:
  cometchat_chat_uikit: ^6.0.5
```

### 5. State Management Migration (Advanced)

If you were directly using controllers:

```dart theme={null}
// 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

1. ☐ Replace all `CometChatXxxController` usage with `XxxBloc`
2. ☐ Replace `CometChatUIKit.getDataSource().xxx()` with `MessageTemplateUtils.xxx()`
3. ☐ Remove `extensions` and `aiFeature` from `UIKitSettings`
4. ☐ Replace `cometchat_uikit_shared` imports with `cometchat_chat_uikit`
5. ☐ 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 |