diff --git a/.mintlifyignore b/.mintlifyignore index 26f5c15f8..a6ba5f51b 100644 --- a/.mintlifyignore +++ b/.mintlifyignore @@ -1 +1,3 @@ .github +chat-uikit-flutter +chat-uikit-flutter/** diff --git a/docs.json b/docs.json index bc49984d3..46dec9aa0 100644 --- a/docs.json +++ b/docs.json @@ -2123,6 +2123,121 @@ } ] }, + { + "version": "v6‎‎‎‎", + "groups": [ + { + "group": " ", + "pages": [ + "ui-kit/flutter/v6/overview", + { + "group": "Getting Started", + "pages": [ + "ui-kit/flutter/v6/getting-started", + "ui-kit/flutter/v6/flutter-conversation", + "ui-kit/flutter/v6/flutter-one-to-one-chat", + "ui-kit/flutter/v6/flutter-tab-based-chat" + ] + }, + { + "group": "Features", + "pages": [ + { + "group": "Chat", + "pages": [ + "ui-kit/flutter/v6/core-features", + "ui-kit/flutter/v6/extensions" + ] + }, + "ui-kit/flutter/v6/call-features" + ] + }, + { + "group": "Theming", + "pages": [ + "ui-kit/flutter/v6/theme-introduction", + "ui-kit/flutter/v6/color-resources", + "ui-kit/flutter/v6/component-styling", + "ui-kit/flutter/v6/message-bubble-styling", + "ui-kit/flutter/v6/localize", + "ui-kit/flutter/v6/sound-manager" + ] + }, + { + "group": "Components", + "pages": [ + "ui-kit/flutter/v6/components-overview", + "ui-kit/flutter/v6/conversations", + "ui-kit/flutter/v6/users", + "ui-kit/flutter/v6/groups", + "ui-kit/flutter/v6/group-members", + "ui-kit/flutter/v6/message-header", + "ui-kit/flutter/v6/message-list", + "ui-kit/flutter/v6/message-composer", + "ui-kit/flutter/v6/threaded-messages-header", + "ui-kit/flutter/v6/incoming-call", + "ui-kit/flutter/v6/outgoing-call", + "ui-kit/flutter/v6/call-buttons", + "ui-kit/flutter/v6/call-logs", + "ui-kit/flutter/v6/search" + ] + }, + { + "group": "Reference", + "pages": [ + "ui-kit/flutter/v6/methods", + "ui-kit/flutter/v6/events" + ] + }, + { + "group": "Customization", + "pages": [ + "ui-kit/flutter/v6/customization-overview", + "ui-kit/flutter/v6/customization-view-slots", + "ui-kit/flutter/v6/customization-bloc-data", + "ui-kit/flutter/v6/customization-state-views", + "ui-kit/flutter/v6/customization-text-formatters", + "ui-kit/flutter/v6/customization-menu-options", + "ui-kit/flutter/v6/customization-datasource" + ] + }, + { + "group": "Advanced", + "pages": [ + "ui-kit/flutter/v6/message-template", + "ui-kit/flutter/v6/mentions-formatter-guide", + "ui-kit/flutter/v6/shortcut-formatter-guide", + "ui-kit/flutter/v6/custom-text-formatter-guide", + "ui-kit/flutter/v6/troubleshooting" + ] + }, + { + "group": "Guides", + "pages": [ + "ui-kit/flutter/v6/guide-overview", + "ui-kit/flutter/v6/guide-threaded-messages", + "ui-kit/flutter/v6/guide-block-unblock-user", + "ui-kit/flutter/v6/guide-new-chat", + "ui-kit/flutter/v6/guide-message-privately", + "ui-kit/flutter/v6/guide-call-log-details", + "ui-kit/flutter/v6/guide-group-chat", + "ui-kit/flutter/v6/guide-message-agentic-flow", + "ui-kit/flutter/v6/multi-tab-chat-ui-guide" + ] + }, + { + "group": "Migration Guide", + "pages": [ + "ui-kit/flutter/v6/upgrading-from-v5", + "ui-kit/flutter/v6/property-changes" + ] + }, + "ui-kit/flutter/link/sample", + "ui-kit/flutter/link/changelog" + ] + } + ] + }, { "version": "v4‎‎‎‎", "groups": [ diff --git a/ui-kit/flutter/overview.mdx b/ui-kit/flutter/overview.mdx index 5cf1f7c99..d73a14dab 100644 --- a/ui-kit/flutter/overview.mdx +++ b/ui-kit/flutter/overview.mdx @@ -4,6 +4,10 @@ sidebarTitle: "Overview" description: "Prebuilt Flutter widgets for chat, voice, and video calling. Works on iOS and Android." --- + +🚀 **V6 Beta Available** — The Flutter UI Kit V6 is now available in beta with BLoC state management, clean architecture, and improved performance. [Check out the V6 Overview →](/ui-kit/flutter/v6/overview) + + | Field | Value | diff --git a/ui-kit/flutter/v6/call-buttons.mdx b/ui-kit/flutter/v6/call-buttons.mdx new file mode 100644 index 000000000..fdef3d6c4 --- /dev/null +++ b/ui-kit/flutter/v6/call-buttons.mdx @@ -0,0 +1,131 @@ +--- +title: "Call Buttons" +--- + +## Overview + +The `CometChatCallButtons` widget provides users with the ability to make calls, access call-related functionalities, and control call settings. + +## Usage + +### Integration + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart'; +import 'package:flutter/material.dart'; + +class CallButtonsExample extends StatefulWidget { + const CallButtonsExample({super.key}); + + @override + State createState() => _CallButtonsExampleState(); +} + +class _CallButtonsExampleState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: Center(child: CometChatCallButtons()), + ), + ); + } +} +``` + + + +*** + +### Actions + +##### onError + + + +```dart +CometChatCallButtons( + onError: (e) { + // Handle error + }, +) +``` + + + +*** + +### Events + +| Event | Description | +|---|---| +| ccCallAccepted | Triggers when the outgoing call is accepted | +| ccCallRejected | Triggers when the outgoing call is rejected | + + + +```dart +class _YourScreenState extends State with CometChatCallEventListener { + @override + void initState() { + super.initState(); + CometChatCallEvents.addCallEventsListener("unique_listener_ID", this); + } + + @override + void dispose() { + super.dispose(); + CometChatCallEvents.removeCallEventsListener("unique_listener_ID"); + } + + @override + void ccCallAccepted(Call call) { + // Handle call accepted + } + + @override + void ccCallRejected(Call call) { + // Handle call rejected + } +} +``` + + + +*** + +## Customization + +### Style + + + +```dart +CometChatCallButtons( + callButtonsStyle: CometChatCallButtonsStyle( + voiceCallIconColor: Color(0xFF6852D6), + videoCallIconColor: Color(0xFF6852D6), + voiceCallButtonColor: Color(0xFFEDEAFA), + videoCallButtonColor: Color(0xFFEDEAFA), + voiceCallButtonBorderRadius: BorderRadius.circular(12.5), + videoCallButtonBorderRadius: BorderRadius.circular(12.5), + ), +) +``` + + + +### Functionality + +| Property | Description | Code | +|---|---|---| +| User | Set User object | `user: User?` | +| Group | Set Group object | `group: Group?` | +| CallSettingsBuilder | Configure call settings | `callSettingsBuilder: CallSettingsBuilder?` | +| Hide Video Call | Hide video call button | `hideVideoCallButton: bool?` | +| Hide Voice Call | Hide voice call button | `hideVoiceCallButton: bool?` | +| Video Call Icon | Custom video call icon | `videoCallIcon: Icon?` | +| Voice Call Icon | Custom voice call icon | `voiceCallIcon: Icon?` | +| Outgoing Call Configuration | Configure outgoing call | `outgoingCallConfiguration: CometChatOutgoingCallConfiguration?` | diff --git a/ui-kit/flutter/v6/call-features.mdx b/ui-kit/flutter/v6/call-features.mdx new file mode 100644 index 000000000..916cd9bf9 --- /dev/null +++ b/ui-kit/flutter/v6/call-features.mdx @@ -0,0 +1,173 @@ +--- +title: "Call" +--- + +## Overview + +CometChat's Calls feature allows you to integrate one-on-one and group audio/video calling capabilities into your application. In V6, calling is built into the `cometchat_chat_uikit` package — no separate calls dependency needed. + +## Integration + +### Step 1: Add Dependency + +Since V6 is hosted on Cloudsmith, install via CLI: + + + +```bash +dart pub add cometchat_chat_uikit:6.0.0-beta1 --hosted-url https://dart.cloudsmith.io/cometchat/cometchat/ +``` + + + +Or add manually to `pubspec.yaml`: + + + +```yaml +dependencies: + cometchat_chat_uikit: + hosted: https://dart.cloudsmith.io/cometchat/cometchat/ + version: 6.0.0-beta1 +``` + + + +*** + +### Step 2: Update build.gradle + +Set `minSdkVersion` to at least 24 in `android/app/build.gradle`: + + + +```gradle +defaultConfig { + minSdkVersion 24 + targetSdkVersion flutter.targetSdkVersion + versionCode flutterVersionCode.toInteger() + versionName flutterVersionName +} +``` + + + +*** + +### Step 3: Update iOS Podfile + +In `ios/Podfile`, set the minimum iOS version to 12: + +``` +platform :ios, '12.0' +``` + +*** + +### Step 4: Modify UIKitSettings + +Activate calling features by setting `enableCalls` to `true` in UIKitSettings: + + + +```dart +UIKitSettings uiKitSettings = (UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..region = "REGION" + ..appId = "APP_ID" + ..authKey = "AUTH_KEY" + ..enableCalls = true + ..callingConfiguration = CallingConfiguration() +).build(); + +CometChatUIKit.init(uiKitSettings: uiKitSettings, + onSuccess: (successMessage) {}, + onError: (e) {}, +); +``` + + + +To allow launching the Incoming Call screen from any widget, provide the navigator key: + + + +```dart +MaterialApp( + navigatorKey: CallNavigationContext.navigatorKey, + home: YourHomeScreen(), +) +``` + + + +### Listeners + +Register call listeners for top-level widgets: + + + +```dart +class _YourClassNameState extends State with CallListener { + @override + void initState() { + super.initState(); + CometChat.addCallListener(listenerId, this); + } + + @override + void dispose() { + super.dispose(); + CometChat.removeCallListener(listenerId); + } + + @override + void onIncomingCallReceived(Call call) { + debugPrint("onIncomingCallReceived"); + } + + @override + void onOutgoingCallAccepted(Call call) { + debugPrint("onOutgoingCallAccepted"); + } + + @override + void onOutgoingCallRejected(Call call) { + debugPrint("onOutgoingCallRejected"); + } + + @override + void onIncomingCallCancelled(Call call) { + debugPrint("onIncomingCallCancelled"); + } + + @override + void onCallEndedMessageReceived(Call call) { + debugPrint("onCallEndedMessageReceived"); + } + + @override + Widget build(BuildContext context) { + return const Placeholder(); + } +} +``` + + + +*** + +## Features + +### Incoming Call + +The Incoming Call widget lets users receive real-time audio and video calls. When a call is received, it displays caller information with accept/reject options. + +### Outgoing Call + +The Outgoing Call widget manages the outgoing call process. It displays recipient information and call status, and automatically transitions to the ongoing call screen when accepted. + +### Call Logs + +The [Call Logs](/ui-kit/flutter/v6/call-logs) widget displays records of call events including caller, time, and duration. diff --git a/ui-kit/flutter/v6/call-logs.mdx b/ui-kit/flutter/v6/call-logs.mdx new file mode 100644 index 000000000..6e68801d5 --- /dev/null +++ b/ui-kit/flutter/v6/call-logs.mdx @@ -0,0 +1,628 @@ +--- +title: "Call Logs" +description: "Scrollable list of call history showing caller info, call type, status, and timestamps." +--- + +`CometChatCallLogs` renders a scrollable list of call history with call type indicators (audio/video), call status (incoming/outgoing/missed), timestamps, and pagination support. + + + + + +The `CometChatCallLogs` widget is composed of the following base widgets: + +| Widget | Description | +|---|---| +| CometChatListBase | Container widget with title, background options, and list integration | +| CometChatListItem | Displays call log data on a card with title and subtitle | + +--- + +## Where It Fits + +`CometChatCallLogs` is a list component. It renders call history and emits the selected `CallLog` via `onItemClick`. Wire it to a detail screen or use `onCallLogIconClicked` to initiate a call directly from the log. + + + +```dart +CometChatCallLogs( + onItemClick: (callLog) { + // Navigate to call log details or open chat + Navigator.push( + context, + MaterialPageRoute( + builder: (context) => CometChatCallLogDetails(callLog: callLog), + ), + ); + }, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatCallLogs())); +``` + + + +Embedding as a widget: + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart'; +import 'package:flutter/material.dart'; + +class CallLogsExample extends StatefulWidget { + const CallLogsExample({super.key}); + + @override + State createState() => _CallLogsExampleState(); +} + +class _CallLogsExampleState extends State { + @override + Widget build(BuildContext context) { + return const Scaffold( + body: SafeArea(child: CometChatCallLogs()), + ); + } +} +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the Calls UIKit dependency added. See [Call Features](/ui-kit/flutter/call-features) for setup. + +--- + +## Filtering Call Logs + +Pass a `CallLogRequestBuilder` to control what loads: + + + +```dart +CometChatCallLogs( + callLogsRequestBuilder: CallLogRequestBuilder() + ..limit = 10 + ..hasRecording = true, +) +``` + + + +### Filter Recipes + +| Recipe | Builder property | +|---|---| +| Limit per page | `..limit = 10` | +| Audio calls only | `..callType = "audio"` | +| Video calls only | `..callType = "video"` | +| Missed calls only | `..callStatus = "missed"` | +| Incoming calls only | `..callDirection = "incoming"` | +| Outgoing calls only | `..callDirection = "outgoing"` | +| Calls with recording | `..hasRecording = true` | +| Calls for specific user | `..uid = "user_uid"` | +| Calls for specific group | `..guid = "group_guid"` | +| Call category (call/meet) | `..callCategory = "call"` | + +### Filter Properties + +| Property | Type | Description | +|---|---|---| +| `authToken` | `String?` | Authentication token | +| `callCategory` | `String?` | Category: `"call"` or `"meet"` | +| `callDirection` | `String?` | Direction: `"incoming"` or `"outgoing"` | +| `callStatus` | `String?` | Status: `"ongoing"`, `"busy"`, `"rejected"`, `"cancelled"`, `"ended"`, `"missed"`, `"initiated"`, `"unanswered"` | +| `callType` | `String?` | Type: `"audio"`, `"video"`, or `"audio/video"` | +| `guid` | `String?` | Group ID filter | +| `hasRecording` | `bool` | Filter calls with recordings | +| `limit` | `int` | Max results per request | +| `uid` | `String?` | User ID filter | + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemClick` + +Fires when a call log item is tapped. Primary navigation hook. + + + +```dart +CometChatCallLogs( + onItemClick: (callLog) { + // Navigate to call details or chat + }, +) +``` + + + +#### `onItemLongPress` + +Fires when a call log item is long-pressed, allowing additional actions. + + + +```dart +CometChatCallLogs( + onItemLongPress: (CallLog callLog) { + // Show context menu + }, +) +``` + + + +#### `onBack` + +Fires when the user presses the back button in the app bar. + + + +```dart +CometChatCallLogs( + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onError` + +Fires on internal errors (network failure, SDK exception). + + + +```dart +CometChatCallLogs( + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + +```dart +CometChatCallLogs( + onLoad: (list) { + debugPrint("Loaded ${list.length} call logs"); + }, +) +``` + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + +```dart +CometChatCallLogs( + onEmpty: () { + debugPrint("No call logs found"); + }, +) +``` + + + +#### `onCallLogIconClicked` + +Fires when the call icon on a call log item is tapped, typically used to initiate a call back. + + + +```dart +CometChatCallLogs( + onCallLogIconClicked: (CallLog callLog) { + // Initiate call back to this contact + }, +) +``` + + + +### Events + +The `CometChatCallLogs` widget does not emit global events. + +--- + +## Functionality + +| Property | Type | Default | Description | +|---|---|---|---| +| `showBackButton` | `bool?` | `true` | Toggle back button visibility | +| `hideAppbar` | `bool?` | `false` | Toggle app bar visibility | +| `backButton` | `Widget?` | `null` | Custom back button widget | +| `datePattern` | `String?` | `null` | Format pattern for date display | +| `dateSeparatorPattern` | `String?` | `null` | Format pattern for date separator | +| `hideSeparator` | `bool` | `false` | Hide separator between items | +| `emptyStateText` | `String?` | `null` | Text for empty state | +| `errorStateText` | `String?` | `null` | Text for error state | +| `incomingAudioCallIcon` | `Icon?` | `null` | Custom icon for incoming audio calls | +| `incomingVideoCallIcon` | `Icon?` | `null` | Custom icon for incoming video calls | +| `outgoingAudioCallIcon` | `Icon?` | `null` | Custom icon for outgoing audio calls | +| `outgoingVideoCallIcon` | `Icon?` | `null` | Custom icon for outgoing video calls | +| `missedAudioCallIcon` | `Icon?` | `null` | Custom icon for missed audio calls | +| `missedVideoCallIcon` | `Icon?` | `null` | Custom icon for missed video calls | +| `infoIconUrl` | `String?` | `null` | URL for the info icon | +| `loadingIconUrl` | `String?` | `null` | URL for the loading icon | + +**Example — custom back button:** + + + +```dart +CometChatCallLogs( + backButton: Icon(Icons.arrow_back_ios, color: Color(0xFF6851D6)), +) +``` + + + +![Image](/images/b63f7edc-call_logs_functionality_cometchat_screens-9440a7269b6a247eec0ea0b0be9853d7.png) +![Image](/images/7d1ac343-call_logs_functionality_cometchat_screens-6da1c65caba38476d7a76ef530beef6d.png) + +--- + +## Custom View Slots + +### List Item View + +Replace the entire list item row with a custom widget. + + + +```dart +CometChatCallLogs( + listItemView: (callLog, context) { + final status = getCallStatus(context, callLog, CometChatUIKit.loggedInUser); + IconData icon = Icons.call; + Color? color; + Color? textColor; + + if (status == "Incoming Call") { + icon = Icons.phone_callback_rounded; + color = Color(0xFF6852D6); + } else if (status == "Outgoing Call") { + icon = Icons.phone_forwarded; + color = Color(0xFF6852D6); + } else if (status == "Missed Call") { + icon = Icons.phone_missed; + color = Colors.red; + textColor = Colors.red; + } + + String name = _getCallLogName(callLog); + String formattedDate = DateFormat('d MMM, hh:mm a').format( + DateTime.fromMillisecondsSinceEpoch((callLog.initiatedAt ?? 0) * 1000), + ); + + return ListTile( + leading: CircleAvatar( + backgroundColor: Color(0xFFEDEAFA), + child: Icon(icon, color: color, size: 24), + ), + title: Text(name, style: TextStyle( + fontSize: 16, fontWeight: FontWeight.w500, + color: textColor ?? Color(0xFF141414), + )), + subtitle: Text(status, style: TextStyle( + color: Color(0xFF727272), fontSize: 14, + )), + trailing: Text(formattedDate, style: TextStyle( + color: Color(0xFF727272), fontSize: 14, + )), + ); + }, +) +``` + + +```dart +static String getCallStatus(BuildContext context, CallLog callLog, User? loggedInUser) { + String callMessageText = ""; + if (callLog.receiverType == ReceiverTypeConstants.user) { + CallUser initiator = callLog.initiator as CallUser; + bool isMe = initiator.uid == loggedInUser?.uid; + + switch (callLog.status) { + case CallStatusConstants.initiated: + callMessageText = isMe ? "Outgoing Call" : "Incoming Call"; + break; + case CallStatusConstants.ongoing: + callMessageText = "Call Accepted"; + break; + case CallStatusConstants.ended: + callMessageText = "Call Ended"; + break; + case CallStatusConstants.unanswered: + case CallStatusConstants.cancelled: + case CallStatusConstants.rejected: + case CallStatusConstants.busy: + callMessageText = isMe ? "Call ${callLog.status}" : "Missed Call"; + break; + } + } + return callMessageText; +} +``` + + + + + + + +### Title View + +Replace the caller name / title text. + + + +```dart +CometChatCallLogs( + titleView: (callLog, context) { + return Text( + _getCallLogName(callLog), + style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16), + ); + }, +) +``` + + + +### Leading View + +Replace the avatar / left section. + + + +```dart +CometChatCallLogs( + leadingView: (callLog, context) { + return CircleAvatar( + backgroundColor: Color(0xFFEDEAFA), + child: Icon(Icons.call, color: Color(0xFF6852D6)), + ); + }, +) +``` + + + +### Subtitle View + +Replace the call status text below the name. + + + +```dart +CometChatCallLogs( + subTitleView: (callLog, context) { + return Row( + children: [ + _getCallIcon(callLog, CometChatUIKit.loggedInUser), + SizedBox(width: 4), + Text( + getCallStatus(context, callLog, CometChatUIKit.loggedInUser), + style: TextStyle(color: Color(0xFF727272), fontSize: 14), + ), + ], + ); + }, +) +``` + + +```dart +static Widget _getCallIcon(CallLog callLog, User? loggedInUser) { + bool isMe = (callLog.initiator as CallUser?)?.uid == loggedInUser?.uid; + + Widget incoming = Icon(Icons.call_received_outlined, color: Colors.red, size: 16); + Widget outgoing = Icon(Icons.call_made_outlined, color: Color(0xFF09C26F), size: 16); + Widget missed = Icon(Icons.call_received_outlined, color: Colors.red, size: 16); + + switch (callLog.status) { + case CallStatusConstants.initiated: + case CallStatusConstants.ongoing: + case CallStatusConstants.ended: + return isMe ? outgoing : incoming; + case CallStatusConstants.unanswered: + case CallStatusConstants.cancelled: + case CallStatusConstants.rejected: + case CallStatusConstants.busy: + return isMe ? outgoing : missed; + default: + return const SizedBox(); + } +} +``` + + + + + + + +### Trailing View + +Replace the timestamp / right section. + + + +```dart +CometChatCallLogs( + trailingView: (context, callLog) { + String formattedDate = DateFormat('d MMM, hh:mm a').format( + DateTime.fromMillisecondsSinceEpoch((callLog.initiatedAt ?? 0) * 1000), + ); + return Text( + formattedDate, + style: TextStyle(color: Color(0xFF727272), fontSize: 14), + ); + }, +) +``` + + + + + + + +### State Views + + + +```dart +CometChatCallLogs( + emptyStateView: (context) => Center(child: Text("No call logs yet")), + errorStateView: (context) => Center(child: Text("Something went wrong")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), +) +``` + + + +--- + +## Menu Options + + + +```dart +// Replace all options +CometChatCallLogs( + setOptions: (callLog, controller, context) { + return [ + CometChatOption( + id: "callback", + iconWidget: Icon(Icons.call), + title: "Call Back", + onClick: () { + // Initiate call back + }, + ), + ]; + }, +) + +// Append to defaults +CometChatCallLogs( + addOptions: (callLog, controller, context) { + return [ + CometChatOption( + id: "block", + iconWidget: Icon(Icons.block), + title: "Block Number", + onClick: () { + // Block this contact + }, + ), + ]; + }, +) +``` + + + +--- + +## Style + + + +```dart +CometChatCallLogs( + callLogsStyle: CometChatCallLogsStyle( + titleTextColor: Color(0xFFF76808), + separatorColor: Color(0xFFF76808), + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + ), +) +``` + + + + + + + +--- + +## Configurations + +### Outgoing Call + +Customize the outgoing call component that appears when a call is initiated from a call log: + + + +```dart +CometChatCallLogs( + outgoingCallConfiguration: OutgoingCallConfiguration( + subtitle: "Outgoing Call", + outgoingCallStyle: OutgoingCallStyle( + background: Color(0xFFE4EBF5), + ), + ), +) +``` + + + +![Image](/images/e8884743-call_logs_outgoing_call_config_cometchat_screens-74adaf62cb240d32b466c122d66e98d2.png) +![Image](/images/de8acec6-call_logs_outgoing_call_config_cometchat_screens-836ab1ccf71553f8991268445fb70852.png) + +All exposed properties of `OutgoingCallConfiguration` can be found under [Outgoing Call](/ui-kit/flutter/outgoing-call). + +--- + +## Next Steps + + + + Build a call log details screen + + + Add voice and video call buttons + + + Detailed styling reference + + + Browse recent conversations + + diff --git a/ui-kit/flutter/v6/color-resources.mdx b/ui-kit/flutter/v6/color-resources.mdx new file mode 100644 index 000000000..a66658fd0 --- /dev/null +++ b/ui-kit/flutter/v6/color-resources.mdx @@ -0,0 +1,108 @@ +--- +title: "Color Resources" +--- + +## Introducing CometChatColorPalette + +The `CometChatColorPalette` class allows you to customize the colors used throughout your app. It works the same way in V6 as in V5 — you assign it to the `extensions` property of your `ThemeData`. + +Here's what you can customize: + +* Primary Colors — Main color scheme of your app +* Neutral Colors — Balanced base for visuals +* Alert Colors — Informative, warning, success, and error messages +* Background Colors — Background shades for different areas +* Text Colors — Text element colors for readability +* Border Colors — Borders for buttons and cards +* Icon Colors — App icon colors +* Button Colors — Button background and text colors +* Shimmer Colors — Loading animation colors + +### Light Mode + + + +```dart +ThemeData( + extensions: [ + CometChatColorPalette( + textSecondary: Color(0xFF727272), + background1: Color(0xFFFFFFFF), + textPrimary: Color(0xFF141414), + borderLight: Color(0xFFF5F5F5), + borderDark: Color(0xFFDCDCDC), + iconSecondary: Color(0xFFA1A1A1), + success: Color(0xFF09C26F), + iconHighlight: Color(0xFF6852D6), + extendedPrimary500: Color(0xFFAA9EE8), + warning: Color(0xFFFAAB00), + messageSeen: Color(0xFF56E8A7), + neutral900: Color(0xFF141414), + neutral600: Color(0xFF727272), + neutral300: Color(0xFFE8E8E8), + primary: Color(0xFF6852D6), + ), + ], +) +``` + + + +### Dark Mode + + + +```dart +ThemeData( + extensions: [ + CometChatColorPalette( + textSecondary: Color(0xFF989898), + background1: Color(0xFF1A1A1A), + textPrimary: Color(0xFFFFFFFF), + borderLight: Color(0xFF272727), + iconSecondary: Color(0xFF858585), + success: Color(0xFF0B9F5D), + iconHighlight: Color(0xFF6852D6), + extendedPrimary500: Color(0xFF3E3180), + warning: Color(0xFFD08D04), + messageSeen: Color(0xFF56E8A7), + neutral900: Color(0xFFFFFFFF), + neutral600: Color(0xFF989898), + neutral300: Color(0xFF383838), + primary: Color(0xFF6852D6), + ), + ], +) +``` + + + +### Custom Colors + + + +```dart +ThemeData( + extensions: [ + CometChatColorPalette( + textSecondary: Color(0xFF727272), + background1: Color(0xFFFFFFFF), + textPrimary: Color(0xFF141414), + borderLight: Color(0xFFF5F5F5), + borderDark: Color(0xFFDCDCDC), + iconSecondary: Color(0xFFA1A1A1), + success: Color(0xFF09C26F), + iconHighlight: Color(0xFFF76808), + extendedPrimary500: Color(0xFFFBAA75), + warning: Color(0xFFFAAB00), + messageSeen: Color(0xFF56E8A7), + neutral900: Color(0xFF141414), + neutral600: Color(0xFF727272), + neutral300: Color(0xFFE8E8E8), + primary: Color(0xFFF76808), + ), + ], +) +``` + + diff --git a/ui-kit/flutter/v6/component-styling.mdx b/ui-kit/flutter/v6/component-styling.mdx new file mode 100644 index 000000000..e917226dc --- /dev/null +++ b/ui-kit/flutter/v6/component-styling.mdx @@ -0,0 +1,562 @@ +--- +title: "Component Styling" +sidebarTitle: "Component Styling" +description: "Customize visual appearance using ThemeData extensions or component-level style objects." +--- + +The Flutter UI Kit uses `ThemeExtension` for styling. You can apply styles globally via `ThemeData` or pass style objects directly to components. + +## Two Approaches + +### 1. Global Theming via ThemeData + +Apply styles across your entire app by adding `ThemeExtension` objects to your `MaterialApp` theme: + + + +```dart +MaterialApp( + theme: ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + CometChatIncomingMessageBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + ), + CometChatActionBubbleStyle( + textStyle: TextStyle(color: Color(0xFFF76808)), + backgroundColor: Color(0xFFFEEDE1), + ), + ], + ), + home: YourApp(), +) +``` + + + +### 2. Component-Level Styles + +Pass style objects directly to a component. These override global theme values: + + + +```dart +CometChatMessageList( + user: user, + style: CometChatMessageListStyle( + backgroundColor: Color(0xFFFEEDE1), + outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle( + backgroundColor: Colors.white, + ), + ), +) +``` + + + +## Style Precedence + +``` +Component style prop > ThemeData extension > Default theme +``` + +--- + +## Style Classes by Component + +| Component | Style Class | +|---|---| +| `CometChatConversations` | `CometChatConversationsStyle` | +| `CometChatUsers` | `CometChatUsersStyle` | +| `CometChatGroups` | `CometChatGroupsStyle` | +| `CometChatGroupMembers` | `CometChatGroupMembersStyle` | +| `CometChatMessageList` | `CometChatMessageListStyle` | +| `CometChatMessageComposer` | `CometChatMessageComposerStyle` | +| `CometChatMessageHeader` | `CometChatMessageHeaderStyle` | + +## Message Bubble Styles + +The message list style contains nested styles for incoming and outgoing bubbles: + + + +```dart +CometChatMessageListStyle( + outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle( + textBubbleStyle: CometChatTextBubbleStyle(...), + imageBubbleStyle: CometChatImageBubbleStyle(...), + videoBubbleStyle: CometChatVideoBubbleStyle(...), + audioBubbleStyle: CometChatAudioBubbleStyle(...), + fileBubbleStyle: CometChatFileBubbleStyle(...), + deletedBubbleStyle: CometChatDeletedBubbleStyle(...), + pollsBubbleStyle: CometChatPollsBubbleStyle(...), + stickerBubbleStyle: CometChatStickerBubbleStyle(...), + collaborativeWhiteboardBubbleStyle: CometChatCollaborativeBubbleStyle(...), + collaborativeDocumentBubbleStyle: CometChatCollaborativeBubbleStyle(...), + linkPreviewBubbleStyle: CometChatLinkPreviewBubbleStyle(...), + videoCallBubbleStyle: CometChatCallBubbleStyle(...), + ), + incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle( + // Same nested style structure + ), +) +``` + + + +See [Message Bubble Styling](/ui-kit/flutter/v6/message-bubble-styling) for per-bubble-type examples. + +--- + +## Component Style Examples + +### Conversations + + + +```dart +ThemeData( + fontFamily: 'Times New Roman', + extensions: [ + CometChatConversationsStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + badgeStyle: CometChatBadgeStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### Message List + + + +```dart +ThemeData( + extensions: [ + CometChatMessageListStyle( + backgroundColor: Color(0xFFFEEDE1), + outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### Message Composer + + + +```dart +ThemeData( + extensions: [ + CometChatMessageComposerStyle( + sendButtonIconBackgroundColor: Color(0xFFF76808), + secondaryButtonIconColor: Color(0xFFF76808), + auxiliaryButtonIconColor: Color(0xFFF76808), + ), + ], +) +``` + + + +### Message Header + + + +```dart +ThemeData( + extensions: [ + CometChatMessageHeaderStyle( + avatarStyle: CometChatAvatarStyle( + backgroundColor: Color(0xFFFBAA75), + borderRadius: BorderRadius.circular(6.67), + ), + ), + ], +) +``` + + + +### Users + + + +```dart +ThemeData( + extensions: [ + CometChatUsersStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + titleTextColor: Color(0xFFF76808), + separatorColor: Color(0xFFF76808), + backgroundColor: Color(0xFFFFF9F5), + ), + ], +) +``` + + + +### Groups + + + +```dart +ThemeData( + extensions: [ + CometChatGroupsStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + titleTextColor: Color(0xFFF76808), + separatorColor: Color(0xFFF76808), + backgroundColor: Color(0xFFFFF9F5), + ), + ], +) +``` + + + +### Group Members + + + +```dart +ThemeData( + extensions: [ + CometChatGroupMembersStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + titleStyle: TextStyle(color: Color(0xFFF76808)), + separatorColor: Color(0xFFF76808), + ownerMemberScopeBackgroundColor: Color(0xFFF76808), + adminMemberScopeBackgroundColor: Color(0xFFFEEDE1), + adminMemberScopeBorder: Border.all(color: Color(0xFFF76808)), + adminMemberScopeTextColor: Color(0xFFF76808), + ), + ], +) +``` + + + +### AI Assistant Chat History + + + +```dart +final ccColor = CometChatThemeHelper.getColorPalette(context); +CometChatAIAssistantChatHistory( + user: user, + style: CometChatAIAssistantChatHistoryStyle( + backgroundColor: const Color(0xFFFFFAF6), + headerBackgroundColor: const Color(0xFFFFFAF6), + headerTitleTextColor: ccColor.textPrimary, + ), +) +``` + + + +--- + +## Base Component Styles + + +### Avatar + + + +```dart +ThemeData( + extensions: [ + CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + ], +) +``` + + + +### Status Indicator + + + +```dart +ThemeData( + extensions: [ + CometChatStatusIndicatorStyle( + backgroundColor: Color(0xFFFFAB00), + borderRadius: BorderRadius.circular(2), + ), + ], +) +``` + + + +### Badge + + + +```dart +ThemeData( + extensions: [ + CometChatBadgeStyle( + borderRadius: BorderRadius.circular(4), + backgroundColor: Color(0xFFF44649), + ), + ], +) +``` + + + +### Receipts + + + +```dart +ThemeData( + extensions: [ + CometChatMessageReceiptStyle( + readIconColor: Color(0xFFFFAB00), + ), + ], +) +``` + + + +### Media Recorder + + + +```dart +ThemeData( + extensions: [ + CometChatMediaRecorderStyle( + recordIndicatorBackgroundColor: Color(0xFFF44649), + recordIndicatorBorderRadius: BorderRadius.circular(20), + pauseButtonBorderRadius: BorderRadius.circular(8), + deleteButtonBorderRadius: BorderRadius.circular(8), + stopButtonBorderRadius: BorderRadius.circular(8), + ), + ], +) +``` + + + +### Reactions + + + +```dart +ThemeData( + extensions: [ + CometChatReactionsStyle( + borderRadius: BorderRadius.circular(8), + ), + ], +) +``` + + + +### Reaction List + + + +```dart +ThemeData( + extensions: [ + CometChatReactionListStyle( + activeTabTextColor: Color(0xFFF76808), + activeTabIndicatorColor: Color(0xFFF76808), + ), + ], +) +``` + + + +### Conversation Starter + + + +```dart +ThemeData( + extensions: [ + CometChatAIConversationStarterStyle( + backgroundColor: Color(0xFFFEEDE1), + border: Border.all(color: Color(0xFFFBBB90)), + ), + ], +) +``` + + + +### Conversation Summary + + + +```dart +ThemeData( + extensions: [ + CometChatAIConversationSummaryStyle( + backgroundColor: Color(0xFFFEEDE1), + titleStyle: TextStyle(color: Color(0xFFF76808)), + ), + ], +) +``` + + + +### Smart Replies + + + +```dart +ThemeData( + extensions: [ + CometChatAISmartRepliesStyle( + backgroundColor: Color(0xFFFEEDE1), + titleStyle: TextStyle(color: Color(0xFFF76808)), + itemBackgroundColor: Color(0xFFFFF9F5), + itemBorder: Border.all(color: Color(0xFFFBBB90)), + ), + ], +) +``` + + + +### Message Information + + + +```dart +ThemeData( + fontFamily: "Times New Roman", + extensions: [ + CometChatOutgoingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + CometChatMessageInformationStyle( + backgroundHighLightColor: Color(0xFFFEEDE1), + messageReceiptStyle: CometChatMessageReceiptStyle( + readIconColor: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### Message Option Sheet + + + +```dart +ThemeData( + extensions: [ + CometChatMessageOptionSheetStyle( + backgroundColor: Color(0xFFFEEDE1), + iconColor: Color(0xFFF76808), + ), + ], +) +``` + + + +### Attachment Option Sheet + + + +```dart +ThemeData( + extensions: [ + CometChatAttachmentOptionSheetStyle( + backgroundColor: Color(0xFFFEEDE1), + iconColor: Color(0xFFF76808), + ), + ], +) +``` + + + +### AI Option Sheet + + + +```dart +ThemeData( + extensions: [ + CometChatAiOptionSheetStyle( + backgroundColor: Color(0xFFFFF9F5), + iconColor: Color(0xFFF76808), + ), + ], +) +``` + + + +### Mentions + + + +```dart +ThemeData( + extensions: [ + CometChatMentionsStyle( + mentionSelfTextBackgroundColor: Color(0xFFF76808), + mentionTextBackgroundColor: Colors.white, + mentionTextColor: Colors.black, + mentionSelfTextColor: Colors.white, + ), + ], +) +``` + + + +--- + +## Related + +- [Message Bubble Styling](/ui-kit/flutter/v6/message-bubble-styling) — Per-bubble-type style examples. +- [Color Resources](/ui-kit/flutter/v6/color-resources) — Color palette customization. +- [Theme Introduction](/ui-kit/flutter/v6/theme-introduction) — Theme system overview (ColorPalette, Typography, Spacing). +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — All customization categories. \ No newline at end of file diff --git a/ui-kit/flutter/v6/components-overview.mdx b/ui-kit/flutter/v6/components-overview.mdx new file mode 100644 index 000000000..a643de7ee --- /dev/null +++ b/ui-kit/flutter/v6/components-overview.mdx @@ -0,0 +1,55 @@ +--- +title: "Overview" +--- + +CometChat's **UI Kit V6** is a set of pre-built UI Widgets that allows you to easily craft an in-app chat with all the essential messaging features, built on clean architecture with BLoC state management. + +## Type of Widget + +UI Widgets based on behaviour and functionality can be categorized into two types: Base Widget and Widget. + +### Base Widget + +Base Widgets form the building blocks of your app's user interface (UI). They focus solely on presenting visual elements based on input data, without handling any business logic. These Widgets provide the foundational appearance and behavior for your UI. + +### Widget + +Widgets build upon Base Widgets by incorporating business logic via BLoC pattern. They not only render UI elements but also manage data loading through use cases and repositories, execute specific actions, and respond to events. This combination of visual presentation and functional capabilities makes Widgets essential for creating dynamic and interactive UIs. + +> **V6 Note:** V6 does not have Composite Widgets like `CometChatMessages` or `CometChatConversationsWithMessages`. Instead, you compose the UI yourself using individual Widgets (`CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`). This gives you full control over layout and behavior. + +## Architecture + +Each Widget in V6 follows clean architecture internally: + +| Layer | Purpose | Example | +|---|---|---| +| `bloc/` | State management (events, states, BLoC) | `ConversationsBloc`, `ConversationsEvent`, `ConversationsState` | +| `data/` | Data sources and repository implementations | `ConversationsRemoteDatasource`, `ConversationsRepositoryImpl` | +| `domain/` | Use cases and repository interfaces | `GetConversationsUseCase`, `ConversationsRepository` | +| `di/` | Dependency injection | `ConversationsServiceLocator` | +| `widgets/` | Decomposed sub-widgets | `ConversationsList`, `ConversationsEmptyView` | + +## Actions + +Actions direct the operational behavior of a component. They are split into two categories: Predefined Actions and User-Defined Actions. + +### Predefined Actions + +These are actions inherently programmed into a UI component. They execute automatically in response to user interaction, without needing any additional user input. + +### User-Defined Actions + +These are actions that must be explicitly specified by the user. They provide adaptability and allow for the creation of custom behaviors that align with the individual needs of the application. + +To customize the behavior of a component, actions must be overridden by the user. This provides the user with control over how the component responds to specific events or interactions. + +## Events + +Events allow for a decoupled, flexible architecture where different parts of the application can interact without having to directly reference each other. This makes it easier to create complex, interactive experiences, as well as to extend and customize the functionality provided by the CometChat UI Kit. + +Widgets have the ability to emit events. These events are dispatched in response to certain changes or user interactions within the component. By emitting events, these Widgets allow other parts of the application to react to changes or interactions, thus enabling dynamic and interactive behavior within the application. + +## Configurations + +Configurations offer the ability to customize the properties of each individual component. Each Widget has its own set of properties that can be configured, allowing for fine-tuned customization to tailor behavior and appearance to match specific requirements in a granular manner. diff --git a/ui-kit/flutter/v6/conversations.mdx b/ui-kit/flutter/v6/conversations.mdx new file mode 100644 index 000000000..edad71b1b --- /dev/null +++ b/ui-kit/flutter/v6/conversations.mdx @@ -0,0 +1,622 @@ +--- +title: "Conversations" +description: "Scrollable list of recent one-on-one and group conversations for the logged-in user." +--- + +`CometChatConversations` renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence. + +--- + +## Where It Fits + +`CometChatConversations` is a list component. It renders recent conversations and emits the selected `Conversation` via `onItemTap`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a standard chat layout. + + + +```dart +CometChatConversations( + onItemTap: (conversation) { + final entity = conversation.conversationWith; + if (entity is User) { + navigateToUserChat(entity); + } else if (entity is Group) { + navigateToGroupChat(entity); + } + }, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatConversations())); +``` + + + +Embedding as a widget: + + + +```dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatConversations(), + ), + ); +} +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +--- + +## Filtering Conversations + +Pass a `ConversationsRequestBuilder` to control what loads: + + + +```dart +CometChatConversations( + conversationsRequestBuilder: ConversationsRequestBuilder() + ..conversationType = "user" + ..limit = 10, +) +``` + + + +### Filter Recipes + +| Recipe | Builder property | +| --- | --- | +| Only user conversations | `..conversationType = "user"` | +| Only group conversations | `..conversationType = "group"` | +| Limit per page | `..limit = 10` | +| With tags | `..tags = ["vip"]` and `..withTags = true` | +| With user and group tags | `..withUserAndGroupTags = true` | + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemTap` + +Fires when a conversation row is tapped. Primary navigation hook. + + + +```dart +CometChatConversations( + onItemTap: (conversation) { + // Navigate to chat screen + }, +) +``` + + + +#### `onItemLongPress` + +Fires when a conversation row is long-pressed. By default shows a delete overlay (when `deleteConversationOptionVisibility` is true). + + + +```dart +CometChatConversations( + onItemLongPress: (conversation) { + // Custom long press behavior + }, +) +``` + + + +#### `onBack` + +Fires when the user presses the back button in the app bar. + + + +```dart +CometChatConversations( + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onSelection` + +Fires when conversations are selected/deselected in multi-select mode. + + + +```dart +CometChatConversations( + selectionMode: SelectionMode.multiple, + onSelection: (selectedConversations) { + // Handle selected conversations + }, +) +``` + + + +#### `onError` + +Fires on internal errors (network failure, auth issue, SDK exception). + + + +```dart +CometChatConversations( + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + +```dart +CometChatConversations( + onLoad: (conversations) { + debugPrint("Loaded ${conversations.length}"); + }, +) +``` + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + +```dart +CometChatConversations( + onEmpty: () { + debugPrint("No conversations"); + }, +) +``` + + + +### Global Events + +The component emits events via `CometChatConversationEvents` that can be subscribed to from anywhere: + + + +```dart +class _YourScreenState extends State with CometChatConversationEventListener { + + @override + void initState() { + super.initState(); + CometChatConversationEvents.addConversationListListener("listenerId", this); + } + + @override + void dispose() { + CometChatConversationEvents.removeConversationListListener("listenerId"); + super.dispose(); + } + + @override + void ccConversationDeleted(Conversation conversation) { + // Handle conversation deleted + } +} +``` + + + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +| --- | --- | +| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived` | Moves conversation to top, updates last message and unread count | +| `onTypingStarted` / `onTypingEnded` | Shows/hides typing indicator in subtitle | +| `onMessagesDelivered` / `onMessagesRead` | Updates receipt indicators | +| `onUserOnline` / `onUserOffline` | Updates presence status dot | +| `onGroupMemberJoined` / `onGroupMemberLeft` / `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group conversation metadata | +| Connection reconnected | Triggers silent refresh to sync missed messages | + +--- + +## Functionality + +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | `String?` | `null` | Custom app bar title | +| `showBackButton` | `bool` | `false` | Toggle back button | +| `hideAppbar` | `bool?` | `false` | Toggle app bar visibility | +| `hideSearch` | `bool?` | `null` | Toggle search bar | +| `searchReadOnly` | `bool` | `false` | Make search bar read-only (tap opens custom search) | +| `deleteConversationOptionVisibility` | `bool?` | `true` | Show delete option on long press | +| `groupTypeVisibility` | `bool?` | `true` | Show group type icon on avatar | +| `usersStatusVisibility` | `bool?` | `true` | Show online/offline status indicator | +| `receiptsVisibility` | `bool?` | `true` | Show message receipts | +| `disableSoundForMessages` | `bool` | `false` | Disable message sounds | +| `customSoundForMessages` | `String?` | `null` | Custom notification sound asset path | +| `selectionMode` | `SelectionMode?` | `null` | Enable selection mode (`single` or `multiple`) | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + +```dart +CometChatConversations( + leadingView: (context, conversation) { + return CircleAvatar( + child: Text(conversation.conversationWith?.name?[0] ?? ""), + ); + }, +) +``` + + + +### Title View + +Replace the name / title text. + + + +```dart +CometChatConversations( + titleView: (context, conversation) { + return Text( + conversation.conversationWith?.name ?? "", + style: TextStyle(fontWeight: FontWeight.bold), + ); + }, +) +``` + + + +### Subtitle View + +Replace the last message preview. + + + +```dart +CometChatConversations( + subtitleView: (context, conversation) { + final msg = conversation.lastMessage; + if (msg is TextMessage) { + return Text(msg.text, maxLines: 1, overflow: TextOverflow.ellipsis); + } + return Text("New conversation"); + }, +) +``` + + + +### Trailing View + +Replace the timestamp / badge / right section. + + + +```dart +CometChatConversations( + trailingView: (conversation) { + if (conversation.unreadMessageCount > 0) { + return Badge(label: Text("${conversation.unreadMessageCount}")); + } + return null; + }, +) +``` + + + +### List Item View + +Replace the entire list item row. + + + +```dart +CometChatConversations( + listItemView: (conversation) { + return ListTile( + leading: CircleAvatar(child: Text(conversation.conversationWith?.name?[0] ?? "")), + title: Text(conversation.conversationWith?.name ?? ""), + subtitle: Text("Custom item"), + ); + }, +) +``` + + + +### State Views + + + +```dart +CometChatConversations( + emptyStateView: (context) => Center(child: Text("No conversations yet")), + errorStateView: (context) => Center(child: Text("Something went wrong")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), +) +``` + + + +--- + +## Menu Options + + + +```dart +// Replace all options +CometChatConversations( + setOptions: (conversation, bloc, context) { + return [ + CometChatOption( + id: "delete", + icon: AssetConstants.delete, + title: "Delete", + onClick: () { + bloc.add(DeleteConversation(conversation.conversationId!)); + }, + ), + ]; + }, +) + +// Append to defaults +CometChatConversations( + addOptions: (conversation, bloc, context) { + return [ + CometChatOption( + id: "archive", + iconWidget: Icon(Icons.archive_outlined), + title: "Archive", + onClick: () { + // Archive conversation + }, + ), + ]; + }, +) +``` + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + +```dart +CometChatConversations( + hideAppbar: true, + hideSearch: true, +) +``` + + + +### Users-only conversations + + + +```dart +CometChatConversations( + conversationsRequestBuilder: ConversationsRequestBuilder() + ..conversationType = "user", +) +``` + + + +### Custom date formatting + + + +```dart +CometChatConversations( + datePattern: (conversation) { + final timestamp = conversation.updatedAt; + return DateFormat('MMM d').format(DateTime.fromMillisecondsSinceEpoch(timestamp! * 1000)); + }, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +Provide a custom `ConversationsBloc` to override behavior: + + + +```dart +CometChatConversations( + conversationsBloc: CustomConversationsBloc(), +) +``` + + + +### Extending ConversationsBloc + +`ConversationsBloc` uses the `ListBase` mixin with override hooks for custom list behavior: + + + +```dart +class CustomConversationsBloc extends ConversationsBloc { + @override + void onItemAdded(Conversation item, List updatedList) { + // Custom sorting — pinned conversations first + final sorted = _sortWithPinnedFirst(updatedList); + super.onItemAdded(item, sorted); + } + + @override + void onListReplaced(List previousList, List newList) { + // Filter out blocked users on every list refresh + final filtered = newList.where((c) => !isBlocked(c)).toList(); + super.onListReplaced(previousList, filtered); + } +} +``` + + + +For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/ui-kit/flutter/v6/customization-bloc-data#listbase-hooks). + +### Public BLoC Events + +| Event | Description | +| --- | --- | +| `LoadConversations({silent})` | Load initial conversations. `silent: true` keeps existing list visible during refresh. | +| `LoadMoreConversations()` | Load next page (pagination) | +| `RefreshConversations()` | Refresh the list | +| `DeleteConversation(conversationId)` | Delete via SDK and remove from list | +| `RemoveConversation(conversationId)` | Remove from list without SDK call | +| `SetActiveConversation(conversationId)` | Mark as active (suppresses unread count) | +| `UpdateConversation(conversationId, updatedConversation)` | Update with modified data | +| `ResetUnreadCount(conversationId)` | Reset unread count to 0 | + +### Public BLoC Methods + +| Method | Returns | Description | +| --- | --- | --- | +| `getTypingNotifier(conversationId)` | `ValueNotifier>` | Per-conversation typing notifier for isolated rebuilds | +| `getTypingIndicators(conversationId)` | `List` | Current typing indicators for a conversation | + +### Route Observer + +Pass a `RouteObserver` to freeze rebuilds when another screen is pushed on top (prevents expensive rebuilds during keyboard animation): + + + +```dart +// In your app +final RouteObserver> routeObserver = RouteObserver>(); + +MaterialApp( + navigatorObservers: [routeObserver], +) + +// Pass to conversations +CometChatConversations( + routeObserver: routeObserver, +) +``` + + + +--- + +## Style + + + +```dart +CometChatConversations( + conversationsStyle: CometChatConversationsStyle( + backgroundColor: Colors.white, + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + badgeStyle: CometChatBadgeStyle( + backgroundColor: Color(0xFFF76808), + ), + receiptStyle: CometChatMessageReceiptStyle(), + typingIndicatorStyle: CometChatTypingIndicatorStyle(), + dateStyle: CometChatDateStyle(), + mentionsStyle: CometChatMentionsStyle(), + deleteConversationDialogStyle: CometChatConfirmDialogStyle(), + ), +) +``` + + + +### Style Properties + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background color | +| `avatarStyle` | Avatar appearance | +| `badgeStyle` | Unread badge appearance | +| `receiptStyle` | Read receipt icons | +| `typingIndicatorStyle` | Typing indicator text | +| `dateStyle` | Timestamp appearance | +| `mentionsStyle` | Mention highlight style | +| `deleteConversationDialogStyle` | Delete confirmation dialog | + +See [Component Styling](/ui-kit/flutter/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + Browse and search available users + + + Display messages for a conversation + + + Detailed styling reference + + + Customize message bubble structure + + \ No newline at end of file diff --git a/ui-kit/flutter/v6/core-features.mdx b/ui-kit/flutter/v6/core-features.mdx new file mode 100644 index 000000000..a6adbd4ee --- /dev/null +++ b/ui-kit/flutter/v6/core-features.mdx @@ -0,0 +1,131 @@ +--- +title: "Core Features" +--- + +## Overview + +The UI Kit comprises a variety of widgets, each designed to work seamlessly with one another to deliver a comprehensive and intuitive chat experience. Here's how different UI Kit widgets work together to achieve CometChat's Core features: + +## Instant Messaging + +At the heart of CometChat's functionality is the ability to support real-time text messaging. Users can send and receive instant messages, fostering quick and efficient communication. + +| Widgets | Functionality | +|---|---| +| MessageComposer | Enables users to write and send a variety of messages. In V6, powered by `MessageComposerBloc` with rich text formatting support. | +| MessageList | Renders a list of messages sent and received using TextBubble. In V6, powered by `MessageListBloc` with `diffutil_dart` for efficient updates. | + +## Media Sharing + +Beyond text, CometChat allows users to share various media types within their conversations — images, videos, audio files, and documents. + +| Widgets | Functionality | +|---|---| +| MessageComposer | Has ActionSheet for sharing media files. V6 adds inline audio recorder and multi-attachment support (in progress). | +| MessageList | Renders different Media Message bubbles like Image Bubble, File Bubble, Audio Bubble, Video Bubble. | + +## Read Receipts + +CometChat's Read Receipts feature provides visibility into the message status, letting users know when a message has been delivered and read. + +| Widgets | Functionality | +|---|---| +| Conversations | Displays the delivery status of the last message. | +| MessageList | Read receipt status is an integral part of all message bubbles. | +| MessageInformation | Provides transparency into the status of each sent message. | + +## Mark As Unread + +Mark as Unread feature allows users to manually mark messages as unread, helping them keep track of important conversations they want to revisit later. + +| Widgets | Functionality | +|---|---| +| Message List | Provides the "Mark as unread" option in message actions and supports starting from the first unread message. | +| Conversations | Reflects the updated unread count in real-time. | + +## Typing Indicator + +The Typing Indicator feature shows when a user is typing a response in real-time. + +| Widgets | Functionality | +|---|---| +| Conversations | Shows real-time typing status indicators in conversation items. | +| Message Header | Dynamically updates to display a 'typing…' status in real-time. | + +## User Presence + +CometChat's User Presence feature allows users to see whether their contacts are online or offline. + +| Widgets | Functionality | +|---|---| +| Conversations | Shows user presence information in conversation items. | +| Message Header | Handles user Presence information in the toolbar. | +| Users | Renders users Presence information in the user list. | +| Group Members | Handles user Presence information in the member list. | + +## Reactions + +CometChat's Reactions feature allows users to react to messages with emojis. + +| Widgets | Functionality | +|---|---| +| MessageList | Reactions are an integral part of all message bubbles. Width-aware display shows visible reactions + "+N" overflow indicator. | + +## Mentions + +Mentions enhances interactivity by allowing users to directly address specific individuals in a conversation. Supports `@all` for group mentions. + +| Widgets | Functionality | +|---|---| +| Conversations | Shows where users have been specifically mentioned. | +| MessageComposer | Allows users to use the Mentions feature for direct addressing. | +| MessageList | Supports the rendering of Mentions in messages. | + +## Quoted Reply + +Quoted Reply enables users to quickly reply to specific messages by selecting the "Reply" option from a message's action menu. + +| Widgets | Functionality | +|---|---| +| MessageList | Supports replying to messages via the "Reply" option. | +| MessageComposer | Shows the quoted reply above the input field using `CometChatMessagePreview` (renamed from `CometChatEditPreview` in V5). | + +## Threaded Conversations + +The Threaded Conversations feature enables users to respond directly to a specific message in a chat. + +| Widgets | Functionality | +|---|---| +| Threaded Messages | Displays all replies made to a particular message. In V6, powered by `ThreadedHeaderBloc`. | + +## Conversation and Advanced Search + +Enables users to quickly find conversations, messages, and media across chats in real time. + +| Widgets | Functionality | +|---|---| +| Search | Allows users to search across conversations and messages. In V6, powered by a single consolidated `SearchBloc`. | +| Message Header | Shows the search button in the chat header. | +| MessageList | Shows the selected message when clicked from search results. | + +## Moderation + +CometChat's Message Moderation feature helps maintain a safe and respectful chat environment by automatically filtering and managing inappropriate content. + +| Widgets | Functionality | +|---|---| +| Message List | Automatically handles moderated messages, displaying blocked content appropriately. | + +## Report Message + +The Report Message feature allows users to report inappropriate or harmful messages within the chat. + +| Widgets | Functionality | +|---|---| +| MessageList | Provides the "Report Message" option in the message actions menu. | + +## Group Chat + +CometChat facilitates Group Chats, allowing users to have conversations with multiple participants simultaneously. + +For a comprehensive guide on implementing Groups, refer to our detailed [Groups guide](/ui-kit/flutter/v6/guide-group-chat). diff --git a/ui-kit/flutter/v6/custom-text-formatter-guide.mdx b/ui-kit/flutter/v6/custom-text-formatter-guide.mdx new file mode 100644 index 000000000..24bfb42b2 --- /dev/null +++ b/ui-kit/flutter/v6/custom-text-formatter-guide.mdx @@ -0,0 +1,267 @@ +--- +title: "Custom Text Formatter Guide" +description: "Build a custom text formatter from scratch to process hashtags, links, or any text pattern." +--- + +This guide walks you through building a custom `CometChatTextFormatter` that detects `#hashtags` in messages, highlights them, and shows a suggestion dropdown in the composer. + +## Prerequisites + +- CometChat Flutter UI Kit V6 installed +- Familiarity with [Text Formatters](/ui-kit/flutter/v6/customization-text-formatters) + +## Step 1: Create the Formatter Class + +Extend `CometChatTextFormatter` and set the tracking character to `#`: + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; + +class HashtagFormatter extends CometChatTextFormatter { + final List _allHashtags = [ + 'flutter', 'dart', 'cometchat', 'uikit', 'mobile', + 'android', 'ios', 'web', 'chat', 'messaging', + ]; + + HashtagFormatter() : super(trackingCharacter: '#'); + + @override + void init() { + // Called when the formatter is initialized + } +} +``` + + + +## Step 2: Implement Search + +The `search` method is called whenever the user types after the tracking character. Filter your data and set the suggestion list: + + + +```dart +@override +void search(String query) { + if (query.isEmpty) { + setSuggestionItems(_allHashtags + .map((tag) => SuggestionItem( + id: tag, + name: '#$tag', + leadingIcon: Icon(Icons.tag, size: 20), + )) + .toList()); + return; + } + + final filtered = _allHashtags + .where((tag) => tag.toLowerCase().contains(query.toLowerCase())) + .map((tag) => SuggestionItem( + id: tag, + name: '#$tag', + leadingIcon: Icon(Icons.tag, size: 20), + )) + .toList(); + + setSuggestionItems(filtered); +} +``` + + + +## Step 3: Handle Suggestion Selection + +When the user taps a suggestion, insert the hashtag into the composer: + + + +```dart +@override +void onItemClick(SuggestionItem item, User? user, Group? group) { + // The base class handles inserting the text into the composer. + // You can add custom logic here, like tracking analytics. + super.onItemClick(item, user, group); +} +``` + + + +## Step 4: Style Hashtags in Message Bubbles + +Override `buildMessageBubbleSpan` to apply styling to hashtags when they appear in sent/received messages: + + + +```dart +@override +List getFormattedText( + String text, + BuildContext context, + BubbleAlignment alignment, +) { + final results = []; + final regex = RegExp(r'#\w+'); + + for (final match in regex.allMatches(text)) { + results.add(CometChatTextFormatterResult( + start: match.start, + end: match.end, + style: TextStyle( + color: alignment == BubbleAlignment.right + ? Colors.white.withOpacity(0.8) + : Color(0xFF6851D6), + fontWeight: FontWeight.w600, + ), + onTap: () { + // Handle hashtag tap — navigate to hashtag feed, etc. + debugPrint('Tapped hashtag: ${match.group(0)}'); + }, + )); + } + + return results; +} +``` + + + +## Step 5: Pre-Send Hook (Optional) + +Modify the message before it's sent — for example, attach hashtag metadata: + + + +```dart +@override +BaseMessage handlePreMessageSend(BaseMessage message) { + if (message is TextMessage) { + final regex = RegExp(r'#\w+'); + final hashtags = regex + .allMatches(message.text) + .map((m) => m.group(0)!.substring(1)) + .toList(); + + if (hashtags.isNotEmpty) { + message.metadata ??= {}; + message.metadata!['hashtags'] = hashtags; + } + } + return message; +} +``` + + + +## Step 6: Register the Formatter + +Pass your formatter to the components that should use it: + + + +```dart +final hashtagFormatter = HashtagFormatter(); + +// On the message list (for rendering) +CometChatMessageList( + user: user, + textFormatters: [ + CometChatMentionsFormatter(), // Keep default mentions + hashtagFormatter, + ], +) + +// On the composer (for input suggestions) +CometChatMessageComposer( + user: user, + textFormatters: [ + CometChatMentionsFormatter(), + hashtagFormatter, + ], +) +``` + + + +## Complete Example + + + +```dart +class HashtagFormatter extends CometChatTextFormatter { + final List _allHashtags = [ + 'flutter', 'dart', 'cometchat', 'uikit', 'mobile', + ]; + + HashtagFormatter() : super(trackingCharacter: '#'); + + @override + void init() {} + + @override + void search(String query) { + final filtered = query.isEmpty + ? _allHashtags + : _allHashtags.where( + (tag) => tag.toLowerCase().contains(query.toLowerCase()), + ).toList(); + + setSuggestionItems(filtered + .map((tag) => SuggestionItem( + id: tag, + name: '#$tag', + leadingIcon: Icon(Icons.tag, size: 20), + )) + .toList()); + } + + @override + List getFormattedText( + String text, + BuildContext context, + BubbleAlignment alignment, + ) { + final results = []; + final regex = RegExp(r'#\w+'); + + for (final match in regex.allMatches(text)) { + results.add(CometChatTextFormatterResult( + start: match.start, + end: match.end, + style: TextStyle( + color: alignment == BubbleAlignment.right + ? Colors.white.withOpacity(0.8) + : Color(0xFF6851D6), + fontWeight: FontWeight.w600, + ), + )); + } + return results; + } + + @override + BaseMessage handlePreMessageSend(BaseMessage message) { + if (message is TextMessage) { + final hashtags = RegExp(r'#\w+') + .allMatches(message.text) + .map((m) => m.group(0)!.substring(1)) + .toList(); + if (hashtags.isNotEmpty) { + message.metadata ??= {}; + message.metadata!['hashtags'] = hashtags; + } + } + return message; + } +} +``` + + + +## Related + +- [Text Formatters](/ui-kit/flutter/v6/customization-text-formatters) — Text formatter API reference. +- [Mentions Formatter Guide](/ui-kit/flutter/v6/mentions-formatter-guide) — Built-in mentions formatter. +- [Shortcut Formatter Guide](/ui-kit/flutter/v6/shortcut-formatter-guide) — Shortcut text replacement. diff --git a/ui-kit/flutter/v6/customization-bloc-data.mdx b/ui-kit/flutter/v6/customization-bloc-data.mdx new file mode 100644 index 000000000..f23d84375 --- /dev/null +++ b/ui-kit/flutter/v6/customization-bloc-data.mdx @@ -0,0 +1,324 @@ +--- +title: "BLoC & Data" +description: "Configure data fetching with RequestBuilders, provide custom BLoC instances, and listen to state changes." +--- + +Each component's BLoC manages data fetching, state transitions, and business logic. You can configure it via RequestBuilders, provide a custom BLoC instance, or extend the default one. + +## Configuring Data Fetching with RequestBuilders + +Use request builders to control what data the component fetches. Pass the builder instance — not the result of `.build()`. + + + +```dart +CometChatMessageList( + user: user, + messagesRequestBuilder: MessagesRequestBuilder() + ..uid = user.uid + ..searchKeyword = 'hello' + ..limit = 30, +) +``` + + + + +The following parameters in `MessagesRequestBuilder` will always be altered inside the message list: UID, GUID, types, categories. + + +### Request Builder by Component + +| Component | Builder Property | Builder Type | +|---|---|---| +| `CometChatConversations` | `conversationsRequestBuilder` | `ConversationsRequestBuilder` | +| `CometChatUsers` | `usersRequestBuilder` | `UsersRequestBuilder` | +| `CometChatGroups` | `groupsRequestBuilder` | `GroupsRequestBuilder` | +| `CometChatGroupMembers` | `groupMembersRequestBuilder` | `GroupMembersRequestBuilder` | +| `CometChatMessageList` | `messagesRequestBuilder` | `MessagesRequestBuilder` | + +## Providing a Custom BLoC + +Each component accepts an optional BLoC parameter. Provide your own instance to override default behavior: + + + +```dart +final myBloc = MessageListBloc( + user: user, + parentMessageId: null, + types: MessageTemplateUtils.getAllMessageTypes(), + categories: MessageTemplateUtils.getAllMessageCategories(), +); + +CometChatMessageList( + user: user, + messageListBloc: myBloc, +) +``` + + + +### BLoC Parameters by Component + +| Component | BLoC Property | BLoC Type | +|---|---|---| +| `CometChatConversations` | `conversationsBloc` | `ConversationsBloc` | +| `CometChatMessageList` | `messageListBloc` | `MessageListBloc` | +| `CometChatMessageComposer` | `messageComposerBloc` | `MessageComposerBloc` | + +## Extending the Default BLoC + +Extend the default BLoC class and override hooks to add custom behavior: + + + +```dart +class CustomMessageListBloc extends MessageListBloc { + CustomMessageListBloc({required User user}) + : super(user: user); + + @override + void onItemAdded(BaseMessage item, List updatedList) { + // Custom logic when a message is added + debugPrint('Message added: ${item.id}'); + super.onItemAdded(item, updatedList); + } + + @override + void onItemRemoved(BaseMessage item, List updatedList) { + // Custom logic when a message is removed + super.onItemRemoved(item, updatedList); + } + + @override + void onItemUpdated(BaseMessage oldItem, BaseMessage newItem, List updatedList) { + // Custom logic when a message is updated + super.onItemUpdated(oldItem, newItem, updatedList); + } +} +``` + + + +### ListBase Hooks + +All list-based BLoCs use the `ListBase` mixin with these override hooks: + +| Hook | Called When | +|---|---| +| `onItemAdded(item, updatedList)` | An item is added to the list | +| `onItemRemoved(item, updatedList)` | An item is removed from the list | +| `onItemUpdated(oldItem, newItem, updatedList)` | An item is updated in the list | +| `onListCleared(previousList)` | The list is cleared | +| `onListReplaced(previousList, newList)` | The entire list is replaced | + +## Component-Specific BLoC Events + +Each component's BLoC has its own events and methods. See the individual component docs for details: + +- [Message List — BLoC Events & Methods](/ui-kit/flutter/v6/message-list#advanced) +- [Conversations — BLoC Events](/ui-kit/flutter/v6/conversations#advanced) +- [Users — BLoC Events](/ui-kit/flutter/v6/users#advanced) +- [Groups — BLoC Events](/ui-kit/flutter/v6/groups#advanced) +- [Group Members — BLoC Events](/ui-kit/flutter/v6/group-members#advanced) + +## Lifecycle Callbacks + + + +```dart +CometChatMessageList( + user: user, + onLoad: (messages) { + debugPrint('Loaded ${messages.length} messages'); + }, + onEmpty: () { + debugPrint('No messages found'); + }, + onError: (e) { + debugPrint('Error: ${e.message}'); + }, +) +``` + + + +## Related + +- [Message List](/ui-kit/flutter/v6/message-list) — Full message list component reference. +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — See all customization categories. + +--- + +## Repository & Datasource Overrides + +Both `CometChatConversations` and `CometChatMessageList` follow the same clean architecture stack. There are two override points: + +``` +Widget → BLoC → UseCase → Repository → DataSource (Remote + Local) + ↑ ↑ + override here or here +``` + +### 1. Datasource Override + +Implement the abstract datasource interfaces to swap the data layer entirely — e.g. a REST API instead of the CometChat SDK, or a persistent cache instead of in-memory. + +#### Conversations + + + +```dart +abstract class ConversationsRemoteDataSource { + Future> getConversations({int limit, String? fromId}); + Future getConversation(String conversationId); + Future deleteConversation(String conversationWith, String conversationType); + Future markMessageAsRead(BaseMessage message); + Future updateConversation(Conversation conversation); +} + +abstract class ConversationsLocalDataSource { + Future cacheConversations(List conversations); + Future> getCachedConversations(); + Future cacheConversation(Conversation conversation); + Future getCachedConversation(String conversationId); + Future removeCachedConversation(String conversationId); + Future clearCache(); + Future hasCachedData(); +} +``` + + + +#### Message List + + + +```dart +abstract class MessageListRemoteDataSource { + Future getMessages({...}); + Future> fetchPreviousMessages({required MessagesRequest request}); + Future> fetchNextMessages({required MessagesRequest request}); + Future markAsRead(BaseMessage message); + Future markAsDelivered(BaseMessage message); + Future getLoggedInUser(); + Future getConversation({...}); + Future markMessageAsUnread(BaseMessage message); +} + +abstract class MessageListLocalDataSource { + Future cacheMessages(String conversationId, List messages); + Future> getCachedMessages(String conversationId); + // ... cache CRUD methods +} +``` + + + +--- + +### 2. Repository Override + +The repository interfaces sit above the datasources. Override here to change business logic — caching strategy, error handling, retry logic — without touching the datasource layer. + +#### Conversations + + + +```dart +abstract class ConversationsRepository { + Future>> getConversations({int limit, String? fromId}); + Future> getConversationById(String conversationId); + Future> deleteConversation(String conversationId); + Future> updateConversation(Conversation conversation); + Future> getLoggedInUser(); + Future> markAsDelivered(BaseMessage message); + Future> getConversation({...}); +} +``` + + + +#### Message List + + + +```dart +abstract class MessageListRepository { + Future>> getMessages({...}); + Future>> fetchPreviousMessages({...}); + Future>> fetchNextMessages({...}); + Future> markAsRead(BaseMessage message); + Future> markAsDelivered(BaseMessage message); + Future> getLoggedInUser(); + Future> getConversation({...}); + Future> markMessageAsUnread(BaseMessage message); +} +``` + + + +--- + +### 3. Wiring via the Service Locator + +The service locators are the injection point. Both are singletons with a `setup()` method. Call `reset()` first, then `setup()` with your custom implementations before the widget mounts. + +#### Datasource-level override (Conversations) + + + +```dart +class MyConversationsRemoteDataSource implements ConversationsRemoteDataSource { + @override + Future> getConversations({int limit = 30, String? fromId}) async { + // Your REST API call, mock data, etc. + } + // ... implement remaining methods +} + +// Before mounting CometChatConversations: +await ConversationsServiceLocator.instance.reset(); + +final remote = MyConversationsRemoteDataSource(); +final local = ConversationsLocalDataSourceImpl(); // keep default cache +final repo = ConversationsRepositoryImpl( + remoteDataSource: remote, + localDataSource: local, +); +``` + + + +#### Repository-level override (Message List) + + + +```dart +class MyMessageListRepository implements MessageListRepository { + @override + Future>> getMessages({...}) async { + // Custom logic + } + // ... +} + +// Before mounting CometChatMessageList: +await MessageListServiceLocator.instance.reset(); +// Wire your repo into use cases and pass to the BLoC +``` + + + +--- + +### Key Points + +| Point | Detail | +|---|---| +| `reset()` | Sets `_isInitialized = false` — always call before re-wiring | +| `setup()` | Guarded by `_isInitialized` — safe to call multiple times normally | +| `localDataSource` in `MessageListRepositoryImpl` | Optional — pass `null` to disable caching entirely | +| Fallback caching | `ConversationsRepositoryImpl` falls back to local cache when remote fails — your custom remote inherits this if you use `ConversationsRepositoryImpl` with a custom datasource | +| `Result` | All repository methods return `Result` (`Success`/`Failure`) — your implementations must do the same | \ No newline at end of file diff --git a/ui-kit/flutter/v6/customization-datasource.mdx b/ui-kit/flutter/v6/customization-datasource.mdx new file mode 100644 index 000000000..972038527 --- /dev/null +++ b/ui-kit/flutter/v6/customization-datasource.mdx @@ -0,0 +1,209 @@ +--- +title: "MessageTemplateUtils & Data Source" +description: "Customize how messages are rendered, what options appear on bubbles, and what formatters are used — all through the central MessageTemplateUtils registry." +--- + +`MessageTemplateUtils` is the central registry that defines how each message type is rendered, what options appear on message bubbles, and what text formatters are applied. It replaces the `DataSource` / `ChatConfigurator` pattern used in the Android UI Kit. + +## How It Works + +In V6, `MessageTemplateUtils` is a static utility class that provides: + +- Message templates (how each message type is rendered as a bubble) +- Message options (long-press actions per message type) +- Text formatters (text processing for mentions, links, etc.) +- Message type/category lists (for request builder filtering) + +Components call `MessageTemplateUtils` internally to get defaults. You override behavior by passing custom templates, options, or formatters directly to the component. + +## Getting Default Templates + + + +```dart +// Get all default templates +final templates = MessageTemplateUtils.getAllMessageTemplates(); + +// Get a specific template +final textTemplate = MessageTemplateUtils.getTextMessageTemplate(); +final imageTemplate = MessageTemplateUtils.getImageMessageTemplate(); + +// Get template by type and category +final template = MessageTemplateUtils.getMessageTemplate( + messageType: MessageTypeConstants.text, + messageCategory: MessageCategoryConstants.message, +); +``` + + + +## Available Template Methods + +| Method | Returns | +|---|---| +| `getTextMessageTemplate()` | Template for text messages | +| `getImageMessageTemplate()` | Template for image messages | +| `getVideoMessageTemplate()` | Template for video messages | +| `getAudioMessageTemplate()` | Template for audio messages | +| `getFileMessageTemplate()` | Template for file messages | +| `getGroupActionTemplate()` | Template for group action messages | +| `getFormMessageTemplate()` | Template for form messages | +| `getCardMessageTemplate()` | Template for card messages | +| `getSchedulerMessageTemplate()` | Template for scheduler messages | +| `getPollMessageTemplate()` | Template for poll messages | +| `getStickerMessageTemplate()` | Template for sticker messages | +| `getCollaborativeDocumentTemplate()` | Template for collaborative document messages | +| `getCollaborativeWhiteboardTemplate()` | Template for collaborative whiteboard messages | +| `getAllMessageTemplates()` | All templates combined | +| `getMessageTemplate(messageType, messageCategory)` | Template for a specific type/category | + +## Overriding Templates + +### Replace All Templates + +Pass a complete list of templates to `CometChatMessageList`: + + + +```dart +CometChatMessageList( + user: user, + templates: [ + // Your custom text template + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + contentView: (message, context, alignment, {additionalConfigurations}) { + return MyCustomTextBubble(message: message as TextMessage); + }, + options: MessageTemplateUtils.getMessageOptions, + ), + // Keep defaults for other types + MessageTemplateUtils.getImageMessageTemplate(), + MessageTemplateUtils.getVideoMessageTemplate(), + MessageTemplateUtils.getAudioMessageTemplate(), + MessageTemplateUtils.getFileMessageTemplate(), + MessageTemplateUtils.getGroupActionTemplate(), + ], +) +``` + + + +### Add or Override Specific Templates + +Use `addTemplate` to merge custom templates with defaults. Templates are keyed by `category_type` — if your template matches an existing key, it overrides the default: + + + +```dart +CometChatMessageList( + user: user, + addTemplate: [ + // Override text message rendering + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + contentView: (message, context, alignment, {additionalConfigurations}) { + return MyCustomTextBubble(message: message as TextMessage); + }, + options: MessageTemplateUtils.getMessageOptions, + ), + // Add a new custom message type + CometChatMessageTemplate( + type: 'contact', + category: MessageCategoryConstants.custom, + contentView: (message, context, alignment, {additionalConfigurations}) { + return ContactCardBubble(message: message); + }, + ), + ], +) +``` + + + +## Message Options + +### Getting Default Options + + + +```dart +// Get options for a specific message type +final textOptions = MessageTemplateUtils.getTextMessageOptions( + loggedInUser, messageObject, context, group, additionalConfigurations, +); + +// Get options for any message (dispatches by type) +final options = MessageTemplateUtils.getMessageOptions( + loggedInUser, messageObject, context, group, additionalConfigurations, +); + +// Get common options (shared across all types) +final commonOptions = MessageTemplateUtils.getCommonOptions( + loggedInUser, messageObject, context, group, additionalConfigurations, +); +``` + + + +### Option Methods by Message Type + +| Method | Message Type | +|---|---| +| `getTextMessageOptions(...)` | Text | +| `getImageMessageOptions(...)` | Image | +| `getVideoMessageOptions(...)` | Video | +| `getAudioMessageOptions(...)` | Audio | +| `getFileMessageOptions(...)` | File | +| `getCommonOptions(...)` | Shared across all types | +| `getMessageOptions(...)` | Dispatches to the correct type-specific method | + +## Text Formatters + + + +```dart +// Get default formatters +final formatters = MessageTemplateUtils.getDefaultTextFormatters(); +// Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter] +``` + + + +## Type and Category Lists + +Used when building custom `MessagesRequestBuilder` instances: + + + +```dart +// All registered message types +final types = MessageTemplateUtils.getAllMessageTypes(); + +// All registered message categories +final categories = MessageTemplateUtils.getAllMessageCategories(); +``` + + + +## Comparison with Android's DataSource + +| Android | Flutter V6 | Notes | +|---|---|---| +| `ChatConfigurator.getDataSource()` | `MessageTemplateUtils` (static) | Flutter uses static methods instead of a decorator chain | +| `DataSourceDecorator` pattern | Template overrides via `templates` / `addTemplate` props | Flutter overrides at the component level, not globally | +| `CometChatUIKit.getDataSource()` | `MessageTemplateUtils` | Same functionality, different access pattern | +| Global decorator chain | Per-component template lists | Flutter's approach is more explicit but less global | + + +Unlike Android's `DataSourceDecorator` which applies globally, Flutter's template overrides are scoped to the component instance. To apply the same customization everywhere, pass the same template list to each `CometChatMessageList` instance. + + +## Related + +- [Message Template](/ui-kit/flutter/v6/message-template) — Full template structure and examples. +- [Menu & Options](/ui-kit/flutter/v6/customization-menu-options) — Component-level option customization. +- [Text Formatters](/ui-kit/flutter/v6/customization-text-formatters) — Custom text processing. +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/flutter/v6/customization-menu-options.mdx b/ui-kit/flutter/v6/customization-menu-options.mdx new file mode 100644 index 000000000..9a9917751 --- /dev/null +++ b/ui-kit/flutter/v6/customization-menu-options.mdx @@ -0,0 +1,161 @@ +--- +title: "Menu & Options" +description: "Add, replace, or extend long-press actions and composer attachment options on components." +--- + +Components provide long-press context menus (e.g., on conversations or messages) and the message composer provides attachment options. You can customize all of these at the component level or via message templates. + +## Message Bubble Options + +### Via Message Templates + +Each `CometChatMessageTemplate` has an `options` callback that controls what appears when a message is long-pressed: + + + +```dart +CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + options: (loggedInUser, messageObject, context, group, additionalConfigurations) { + // Get the default options + final defaults = MessageTemplateUtils.getTextMessageOptions( + loggedInUser, messageObject, context, group, additionalConfigurations, + ); + // Add a custom option at the beginning + return [ + CometChatMessageOption( + id: 'translate', + title: 'Translate', + icon: Icon(Icons.translate, size: 24), + onClick: () => translateMessage(messageObject), + ), + ...defaults, + ]; + }, +) +``` + + + +### Replacing All Options + +Return only your custom options to completely replace the defaults: + + + +```dart +CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + options: (loggedInUser, messageObject, context, group, additionalConfigurations) { + return [ + CometChatMessageOption( + id: 'bookmark', + title: 'Bookmark', + icon: Icon(Icons.bookmark_border, size: 24), + onClick: () => bookmarkMessage(messageObject), + ), + CometChatMessageOption( + id: 'share', + title: 'Share', + icon: Icon(Icons.share, size: 24), + onClick: () => shareMessage(messageObject), + ), + ]; + }, +) +``` + + + +## Message Option Visibility + +The `CometChatMessageList` provides boolean properties to hide specific default options without needing to override templates: + + + +```dart +CometChatMessageList( + user: user, + hideCopyMessageOption: true, + hideDeleteMessageOption: false, + hideEditMessageOption: false, + hideReactionOption: false, + hideReplyInThreadOption: true, + hideTranslateMessageOption: true, + hideShareMessageOption: true, + hideMessageInfoOption: false, + hideMessagePrivatelyOption: true, +) +``` + + + +## Composer Attachment Options + +The `CometChatMessageComposer` provides boolean properties to control which attachment options appear: + + + +```dart +CometChatMessageComposer( + user: user, + hideImageAttachmentOption: false, + hideVideoAttachmentOption: false, + hideAudioAttachmentOption: true, + hideFileAttachmentOption: false, + hidePollsOption: true, + hideCollaborativeDocumentOption: true, + hideCollaborativeWhiteboardOption: true, + hideTakePhotoOption: false, + hideStickersButton: false, + hideAttachmentButton: false, +) +``` + + + +## Conversation Options + +For conversations, use `setOptions` and `addOptions` on the `CometChatConversations` component: + + + +```dart +// Add custom options to existing defaults +CometChatConversations( + addOptions: (context, conversation) { + return [ + CometChatPopupMenu.MenuItem( + id: 'pin', + title: 'Pin Conversation', + icon: Icon(Icons.push_pin), + onTap: () => pinConversation(conversation), + ), + ]; + }, +) + +// Replace all options +CometChatConversations( + setOptions: (context, conversation) { + return [ + CometChatPopupMenu.MenuItem( + id: 'archive', + title: 'Archive', + icon: Icon(Icons.archive), + onTap: () => archiveConversation(conversation), + ), + ]; + }, +) +``` + + + +## Related + +- [Message Template](/ui-kit/flutter/v6/message-template) — Full template structure including options. +- [Message List](/ui-kit/flutter/v6/message-list) — Option visibility properties. +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/flutter/v6/customization-overview.mdx b/ui-kit/flutter/v6/customization-overview.mdx new file mode 100644 index 000000000..724c7e4b6 --- /dev/null +++ b/ui-kit/flutter/v6/customization-overview.mdx @@ -0,0 +1,88 @@ +--- +title: "Customization Overview" +description: "Understand the Widget + BLoC + Template architecture and discover all customization entry points in the CometChat Flutter UI Kit." +--- + +Every component in the Flutter UI Kit follows a layered architecture built on BLoC for state management and declarative widget composition. Understanding these layers is the key to unlocking deep customization without rebuilding components from scratch. + +## Architecture + +Each component is composed of collaborating layers: + +| Layer | Role | Example Class | +|---|---|---| +| Widget | Renders the UI, accepts configuration props, and exposes builder callbacks for customization. | `CometChatConversations` | +| BLoC | Manages data fetching, state transitions, and business logic via streams and events. | `ConversationsBloc` | +| Templates | Define how each message type is rendered as a bubble (message list only). | `CometChatMessageTemplate` | + +``` +┌─────────────────────────────────┐ +│ CometChatConversations │ +│ (Widget Layer) │ +│ │ +│ ┌───────────────────────┐ │ +│ │ ConversationsBloc │ │ +│ │ (State Management) │ │ +│ └───────────────────────┘ │ +│ │ +│ ┌───────────────────────┐ │ +│ │ Builder Callbacks │ │ +│ │ (View Customization) │ │ +│ └───────────────────────┘ │ +└─────────────────────────────────┘ +``` + +## Accessing Internal Layers + +Components expose their BLoC via constructor parameters: + + + +```dart +// Provide a custom BLoC instance +CometChatConversations( + conversationsBloc: myCustomConversationsBloc, +) + +// Or use the stateCallBack to access the controller +CometChatMessageList( + user: user, + stateCallBack: (controller) { + // Access the controller for programmatic operations + }, +) +``` + + + +## Customization Categories + +The UI Kit provides seven categories of customization entry points. Each category has a dedicated guide: + + + + Replace specific regions of a component's UI (leading view, title, subtitle, trailing view) using builder callbacks. + + + Customize visual appearance using ThemeData extensions or component-level style objects. + + + Configure data fetching with RequestBuilders, provide custom BLoC instances, override repositories and datasources. + + + Replace the default empty, error, and loading state views with custom widgets. + + + Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API. + + + Add, replace, or extend long-press actions and composer attachment options on components. + + + Customize how messages are rendered using MessageTemplateUtils — the central registry for message templates, options, and formatters. + + + +## What's Next + +If you're new to customization, start with [View Slots](/ui-kit/flutter/v6/customization-view-slots) for quick UI changes, or [Styles](/ui-kit/flutter/v6/component-styling) to match your brand. For advanced use cases like custom message types or global behavior changes, head to [Message Templates](/ui-kit/flutter/v6/customization-datasource). diff --git a/ui-kit/flutter/v6/customization-state-views.mdx b/ui-kit/flutter/v6/customization-state-views.mdx new file mode 100644 index 000000000..f81b85102 --- /dev/null +++ b/ui-kit/flutter/v6/customization-state-views.mdx @@ -0,0 +1,156 @@ +--- +title: "State Views" +description: "Replace the default empty, error, and loading state views with custom widgets." +--- + +Components display state views when the list is empty, an error occurs, or data is loading. You can replace these with custom widgets. + +## Replacing State Views + +Each state view property accepts a `WidgetBuilder` — a function that takes `BuildContext` and returns a `Widget`. + +| Property | State | +|---|---| +| `emptyStateView` | No data to display | +| `errorStateView` | An error occurred during data fetching | +| `loadingStateView` | Data is being fetched | +| `emptyChatGreetingView` | Empty chat with a greeting (message list only) | + +## Example: Custom Empty State + + + +```dart +CometChatConversations( + emptyStateView: (context) { + return Center( + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.chat_bubble_outline, size: 64, color: Colors.grey), + SizedBox(height: 16), + Text( + 'No conversations yet', + style: TextStyle(fontSize: 18, color: Colors.grey[700]), + ), + SizedBox(height: 8), + Text( + 'Start a new chat to get going', + style: TextStyle(fontSize: 14, color: Colors.grey), + ), + ], + ), + ); + }, +) +``` + + + +## Example: Custom Error State + + + +```dart +CometChatMessageList( + user: user, + errorStateView: (context) { + return Center( + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.error_outline, size: 48, color: Colors.red), + SizedBox(height: 12), + Text('Something went wrong'), + SizedBox(height: 16), + ElevatedButton( + onPressed: () { + // Trigger reload + }, + child: Text('Try Again'), + ), + ], + ), + ); + }, +) +``` + + + +## Example: Custom Loading State + + + +```dart +CometChatMessageList( + user: user, + loadingStateView: (context) { + return Center( + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + CircularProgressIndicator(color: Color(0xFF6851D6)), + SizedBox(height: 16), + Text('Loading messages...'), + ], + ), + ); + }, +) +``` + + + +## Example: Empty Chat Greeting + +The message list supports a special `emptyChatGreetingView` for new conversations: + + + +```dart +CometChatMessageList( + user: user, + emptyChatGreetingView: (context) { + return Center( + child: Column( + mainAxisSize: MainAxisSize.min, + children: [ + Icon(Icons.waving_hand, size: 48, color: Color(0xFF6851D6)), + SizedBox(height: 16), + Text('Say hello! 👋', style: TextStyle(fontSize: 18)), + ], + ), + ); + }, +) +``` + + + +## Lifecycle Callbacks + +Use lifecycle callbacks to run custom logic when states change: + + + +```dart +CometChatMessageList( + user: user, + onLoad: (messages) { + debugPrint('Loaded ${messages.length} messages'); + }, + onEmpty: () { + debugPrint('No messages found'); + }, + onError: (e) { + debugPrint('Error: ${e.message}'); + }, +) +``` + + + +## Related + +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/flutter/v6/customization-text-formatters.mdx b/ui-kit/flutter/v6/customization-text-formatters.mdx new file mode 100644 index 000000000..6651b54a4 --- /dev/null +++ b/ui-kit/flutter/v6/customization-text-formatters.mdx @@ -0,0 +1,154 @@ +--- +title: "Text Formatters" +description: "Create custom text processors for hashtags, mentions, links, or any pattern using the CometChatTextFormatter API." +--- + +Text formatters let you process message text with tracking characters, suggestion lists, and rich text transformations. Use them to add hashtag detection, custom mentions, link previews, or any text pattern processing. + +## CometChatTextFormatter + +The `CometChatTextFormatter` abstract class is the base for all formatters. Its constructor takes a `String trackingCharacter` that triggers the formatter when typed in the composer (e.g., `@` for mentions, `#` for hashtags). + +### Key Override Methods + +| Method | Purpose | +|---|---| +| `search(String query)` | Called when the user types after the tracking character. Use this to fetch and display suggestions. | +| `onScrollToBottom()` | Called when the user scrolls to the bottom of the suggestion list. Use for pagination. | +| `buildInputSpan(BuildContext, BaseMessage)` | Apply rich text formatting in the message composer. | +| `buildMessageBubbleSpan(BuildContext, BaseMessage, BubbleAlignment)` | Apply rich text formatting in message bubbles. | +| `buildConversationSpan(BuildContext, BaseMessage)` | Apply formatting in the conversations list last message preview. | +| `handlePreMessageSend(BaseMessage)` | Modify a message before it's sent (attach metadata, transform text). | + +## Suggestion System + +The formatter provides a built-in suggestion dropdown: + +| Property/Method | Description | +|---|---| +| `setSuggestionItems(List)` | Set the list of suggestions to display | +| `setShowLoadingIndicator(bool)` | Show/hide a loading spinner in the suggestion dropdown | +| `onItemClick(SuggestionItem, User?, Group?)` | Called when the user selects a suggestion item | + +## Example: Custom Hashtag Formatter + + + +```dart +class HashtagFormatter extends CometChatTextFormatter { + HashtagFormatter() : super(trackingCharacter: '#'); + + @override + void search(String query) { + // Fetch hashtag suggestions based on query + final suggestions = fetchHashtags(query); + setSuggestionItems(suggestions); + } + + @override + void onScrollToBottom() { + // Load more suggestions + } + + @override + InlineSpan? buildMessageBubbleSpan( + BuildContext context, + BaseMessage message, + BubbleAlignment alignment, + ) { + // Apply blue color to #hashtags in message bubbles + return _applyHashtagSpans(message.text); + } + + @override + InlineSpan? buildConversationSpan( + BuildContext context, + BaseMessage message, + ) { + return _applyHashtagSpans(message.text); + } +} +``` + + + +## Registering Formatters + +Register formatters on a component using `textFormatters`: + + + +```dart +CometChatMessageList( + user: user, + textFormatters: [ + CometChatMentionsFormatter(), + HashtagFormatter(), + ], +) +``` + + + +Or on the message composer: + + + +```dart +CometChatMessageComposer( + user: user, + textFormatters: [ + CometChatMentionsFormatter(), + HashtagFormatter(), + ], +) +``` + + + +## Built-in Formatters + +The UI Kit includes several built-in formatters: + +| Formatter | Tracking Character | Description | +|---|---|---| +| `CometChatMentionsFormatter` | `@` | Handles @mention detection, user suggestion lists, and styled highlighting | +| `CometChatEmailFormatter` | — | Detects and links email addresses | +| `CometChatPhoneNumberFormatter` | — | Detects and links phone numbers | +| `MarkdownTextFormatter` | — | Renders markdown formatting (bold, italic, code, etc.) | + +### Default Formatters + +`MessageTemplateUtils.getDefaultTextFormatters()` returns the default set of formatters used by all components: + + + +```dart +final defaults = MessageTemplateUtils.getDefaultTextFormatters(); +// Returns: [CometChatMentionsFormatter, CometChatEmailFormatter, CometChatPhoneNumberFormatter] +``` + + + +## Customizing the Mentions Formatter + + + +```dart +final mentionsFormatter = CometChatMentionsFormatter(); + +CometChatMessageList( + user: user, + textFormatters: [mentionsFormatter], +) +``` + + + +See the [Mentions Formatter Guide](/ui-kit/flutter/v6/mentions-formatter-guide) for detailed styling and behavior customization. + +## Related + +- [Mentions Formatter Guide](/ui-kit/flutter/v6/mentions-formatter-guide) — Built-in mentions formatter reference. +- [Shortcut Formatter Guide](/ui-kit/flutter/v6/shortcut-formatter-guide) — Shortcut text replacement formatter. +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/flutter/v6/customization-view-slots.mdx b/ui-kit/flutter/v6/customization-view-slots.mdx new file mode 100644 index 000000000..49066f259 --- /dev/null +++ b/ui-kit/flutter/v6/customization-view-slots.mdx @@ -0,0 +1,135 @@ +--- +title: "View Slots" +description: "Replace specific regions of a component's UI using builder callbacks without rebuilding the entire component." +--- + +View Slots let you swap out specific parts of a component — the avatar area, title, subtitle, trailing section, or the entire row — while keeping the rest of the component's behavior intact. + +## The Builder Callback Pattern + +Flutter UI Kit components accept nullable builder callbacks for each customizable region. Each callback receives the relevant data model and returns a `Widget?`. Return `null` to fall back to the default view. + +```dart +Widget? Function(BuildContext context, DataModel model)? +``` + +## Available View Slots + +### List Components (Conversations, Users, Groups, Group Members) + +| Property | Region | Signature | +|---|---|---| +| `leadingView` | Left section (avatar) | `Widget? Function(BuildContext, Model)` | +| `titleView` | Title text | `Widget? Function(BuildContext, Model)` | +| `subtitleView` | Subtitle text | `Widget? Function(BuildContext, Model)` | +| `trailingView` | Right section (timestamp, badge) | `Widget? Function(BuildContext, Model)` | + +### Message List + +| Property | Region | Signature | +|---|---|---| +| `headerView` | Above the message list | `Widget? Function(BuildContext, {User?, Group?, int?})` | +| `footerView` | Below the message list | `Widget? Function(BuildContext, {User?, Group?, int?})` | +| `templates` | All message bubble templates | `List` | +| `addTemplate` | Additional templates merged with defaults | `List` | + +### Message Template Slots + +Each `CometChatMessageTemplate` has its own view slots for the bubble structure: + +| Property | Region | Signature | +|---|---|---| +| `headerView` | Above the bubble content | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | +| `contentView` | Main bubble content | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment, {AdditionalConfigurations?})` | +| `footerView` | Below the bubble | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | +| `bottomView` | Below the content, inside the bubble | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | +| `statusInfoView` | Timestamp and receipts | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | +| `replyView` | Quoted reply preview | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | +| `threadView` | Thread reply indicator | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | +| `bubbleView` | Entire bubble (replaces all other slots) | `Widget? Function(BaseMessage, BuildContext, BubbleAlignment)` | + +## Example: Custom Leading View on Conversations + + + +```dart +CometChatConversations( + leadingView: (context, conversation) { + final name = conversation.conversationWith?.name ?? ''; + return CircleAvatar( + backgroundColor: Color(0xFF6851D6), + child: Text( + name.isNotEmpty ? name[0].toUpperCase() : '?', + style: TextStyle(color: Colors.white, fontSize: 18), + ), + ); + }, +) +``` + + + +## Example: Custom Subtitle View on Conversations + + + +```dart +CometChatConversations( + subtitleView: (context, conversation) { + final lastMessage = conversation.lastMessage; + String subtitle; + if (lastMessage is TextMessage) { + subtitle = lastMessage.text; + } else if (lastMessage is MediaMessage) { + subtitle = '📎 ${lastMessage.attachment?.fileExtension ?? "Media"}'; + } else { + subtitle = 'New conversation'; + } + return Text( + subtitle, + maxLines: 1, + overflow: TextOverflow.ellipsis, + ); + }, +) +``` + + + +## Example: Custom Header View on Message List + + + +```dart +CometChatMessageList( + user: user, + headerView: (context, {user, group, parentMessageId}) { + return Container( + padding: EdgeInsets.symmetric(horizontal: 16, vertical: 8), + color: Color(0xFFEDEAFA), + child: Row( + children: [ + Chip(label: Text('📌 Pinned Messages')), + SizedBox(width: 8), + Chip(label: Text('🔗 Saved Links')), + ], + ), + ); + }, +) +``` + + + +## Slot-Level vs Full Replacement + +Use individual slot properties (`leadingView`, `titleView`, `subtitleView`, `trailingView`) when you want to customize one region while keeping the default layout for everything else. Use `bubbleView` on a `CometChatMessageTemplate` when you need complete control over the entire message bubble. + + +When you set `bubbleView` on a template, all other template slots (`headerView`, `contentView`, `footerView`, etc.) are ignored since the entire bubble is replaced. + + +## Related + +- [Message Template](/ui-kit/flutter/v6/message-template) — Full template structure for message bubbles. +- [Customization Overview](/ui-kit/flutter/v6/customization-overview) — See all customization categories. diff --git a/ui-kit/flutter/v6/events.mdx b/ui-kit/flutter/v6/events.mdx new file mode 100644 index 000000000..c780e9feb --- /dev/null +++ b/ui-kit/flutter/v6/events.mdx @@ -0,0 +1,195 @@ +--- +title: "Events" +--- + +## Overview + +Events allow for a decoupled, flexible architecture where different parts of the application can interact without having to directly reference each other. This makes it easier to create complex, interactive experiences, as well as to extend and customize the functionality provided by the CometChat UI Kit. + +> The event system is identical between V5 and V6. All event classes, listeners, and APIs work the same way. + +### User Events + +`CometChatUserEvents` emit events when the logged-in user executes actions on another user. + +1. `ccUserBlocked`: Triggered when the logged-in user blocks another user. +2. `ccUserUnblocked`: Triggered when the logged-in user unblocks another user. + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class _YourScreenState extends State with CometChatUserEventListener { + @override + void initState() { + super.initState(); + CometChatUserEvents.addUsersListener("listenerId", this); + } + + @override + void dispose() { + super.dispose(); + CometChatUserEvents.removeUsersListener("listenerId"); + } + + @override + void ccUserBlocked(User user) { + // Handle user blocked + } + + @override + void ccUserUnblocked(User user) { + // Handle user unblocked + } + + @override + Widget build(BuildContext context) { + return const Placeholder(); + } +} +``` + + + +*** + +### Group Events + +`CometChatGroupEvents` emits events when the logged-in user performs actions related to groups. + +1. `ccGroupCreated`: Triggered when the logged-in user creates a group. +2. `ccGroupDeleted`: Triggered when the logged-in user deletes a group. +3. `ccGroupLeft`: Triggered when the logged-in user leaves a group. +4. `ccGroupMemberScopeChanged`: Triggered when the logged-in user changes the scope of another group member. +5. `ccGroupMemberBanned`: Triggered when the logged-in user bans a group member. +6. `ccGroupMemberKicked`: Triggered when the logged-in user kicks a group member. +7. `ccGroupMemberUnbanned`: Triggered when the logged-in user unbans a user. +8. `ccGroupMemberJoined`: Triggered when the logged-in user joins a group. +9. `ccGroupMemberAdded`: Triggered when the logged-in user adds new members. +10. `ccOwnershipChanged`: Triggered when the logged-in user transfers ownership. + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class _YourScreenState extends State with CometChatGroupEventListener { + @override + void initState() { + super.initState(); + CometChatGroupEvents.addGroupsListener("listenerId", this); + } + + @override + void dispose() { + super.dispose(); + CometChatGroupEvents.removeGroupsListener("listenerId"); + } + + @override + void ccGroupCreated(Group group) { + // Handle group created + } + + @override + void ccGroupDeleted(Group group) { + // Handle group deleted + } + + @override + Widget build(BuildContext context) { + return const Placeholder(); + } +} +``` + + + +*** + +### Message Events + +`CometChatMessageEvents` emits events related to messages. + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class _YourScreenState extends State with CometChatMessageEventListener { + @override + void initState() { + super.initState(); + CometChatMessageEvents.addMessagesListener("listenerId", this); + } + + @override + void dispose() { + super.dispose(); + CometChatMessageEvents.removeMessagesListener("listenerId"); + } + + @override + Widget build(BuildContext context) { + return const Placeholder(); + } +} +``` + + + +*** + +### Conversation Events + +`CometChatConversationEvents` emits events related to conversations. + +1. `ccConversationDeleted`: Triggered when a conversation is deleted. + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class _YourScreenState extends State with CometChatConversationEventListener { + @override + void initState() { + super.initState(); + CometChatConversationEvents.addConversationListListener("listenerId", this); + } + + @override + void dispose() { + super.dispose(); + CometChatConversationEvents.removeConversationListListener("listenerId"); + } + + @override + void ccConversationDeleted(Conversation conversation) { + // Handle conversation deleted + } + + @override + Widget build(BuildContext context) { + return const Placeholder(); + } +} +``` + + + +*** + +### UI Events + +`CometChatUIEvents` emits events related to UI interactions. + + + +```dart +// UI events are used internally by the UI Kit widgets +// to communicate state changes across components +``` + + diff --git a/ui-kit/flutter/v6/extensions.mdx b/ui-kit/flutter/v6/extensions.mdx new file mode 100644 index 000000000..bf6b7b7db --- /dev/null +++ b/ui-kit/flutter/v6/extensions.mdx @@ -0,0 +1,85 @@ +--- +title: "Extensions" +--- + +## Overview + +CometChat's UI Kit comes with built-in support for a wide variety of extensions that provide additional functionality. These extensions enhance the chatting experience, making it more interactive, secure, and efficient. + +Activating any of the extensions in CometChat is a simple process done through your application's dashboard. Refer to our guide for detailed information on [Extensions](/fundamentals/extensions-overview). + +> **V6 Architecture Change:** In V5, extensions used a decorator/chain-of-responsibility pattern with `*Extension` and `*ExtensionDecorator` classes that wrapped the `DataSource` interface. V6 removes this entire pattern. Extension behavior is now handled directly by `MessageTemplateUtils` static methods. No registration is needed — just enable extensions in your CometChat Dashboard and they work automatically. + +## Built-in Extensions + +### Stickers + +The Stickers extension allows users to express their emotions more creatively with pre-designed stickers. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the [Message Composer](/ui-kit/flutter/v6/message-composer) widget. + +### Polls + +The Polls extension enhances group discussions by allowing users to create polls with predefined answers. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/ui-kit/flutter/v6/message-composer) widget. + +### Collaborative Whiteboard + +The Collaborative Whiteboard extension facilitates real-time collaboration on a shared digital whiteboard. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/ui-kit/flutter/v6/message-composer) widget. + +### Collaborative Document + +Users can work together on a shared document with the Collaborative Document extension. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of the [Message Composer](/ui-kit/flutter/v6/message-composer) widget. + +### Message Translation + +The Message Translation extension translates any message into your local locale, eliminating language barriers. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Action Sheet of [MessageList Widget](/ui-kit/flutter/v6/message-list). + +### Link Preview + +The Link Preview extension provides a summary of URLs shared in the chat, including title, description, and thumbnail. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Widget](/ui-kit/flutter/v6/message-list). + +### Thumbnail Generation + +The Thumbnail Generation extension automatically creates smaller preview images for shared images, reducing bandwidth usage. + +Once activated from your CometChat Dashboard, the feature will automatically be incorporated into the Message Bubble of [MessageList Widget](/ui-kit/flutter/v6/message-list). + +## V6 Extension Architecture + +### What Changed + +| Aspect | V5 | V6 | +|---|---|---| +| Registration | `UIKitSettings.extensions = CometChatUIKitChatExtensions.getDefaultExtensions()` | Not needed — built-in | +| Architecture | Decorator chain (up to 10 layers) | `MessageTemplateUtils` static methods (1 hop) | +| Startup cost | 9 `isExtensionEnabled()` network calls | None | +| Files removed | — | 27 files (~7000+ lines) | +| UI widgets | Preserved | Preserved (bubbles, configs, styles) | + +### What Was Removed + +- All `*Extension` classes (e.g., `StickersExtension`, `PollsExtension`) +- All `*ExtensionDecorator` classes (e.g., `StickersExtensionDecorator`) +- `ChatConfigurator`, `DataSource` interface, `ExtensionsDataSource` +- `CometChatUIKitChatExtensions`, `CometChatUIKitChatAIFeatures` +- `CometChatUIKit.getDataSource()` method + +### What Was Preserved + +All extension UI widgets remain: +- `CometChatStickerBubble`, `CometChatStickerKeyboard` +- `CometChatPollsBubble`, `CometChatCreatePoll` +- `CometChatLinkPreviewBubble` +- `CometChatCollaborativeBubble`, `CometChatCollaborativeWebView` +- `MessageTranslationBubble` +- All configuration and style classes diff --git a/ui-kit/flutter/v6/flutter-conversation.mdx b/ui-kit/flutter/v6/flutter-conversation.mdx new file mode 100644 index 000000000..b58d05343 --- /dev/null +++ b/ui-kit/flutter/v6/flutter-conversation.mdx @@ -0,0 +1,158 @@ +--- +title: "Conversation List + Message View" +sidebarTitle: "Conversation List + Message View" +--- + +The Conversation List + Message View layout provides a seamless two-panel chat interface. This layout allows users to switch between conversations while keeping the active chat open. + +## Integration + +### Step 1: Create the Conversations Screen + + + +```dart +import 'package:flutter/material.dart'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class ConversationsScreen extends StatelessWidget { + const ConversationsScreen({super.key}); + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: const Text('Conversations')), + body: CometChatConversations( + onItemTap: (conversation) { + _openChat(context, conversation); + }, + ), + ); + } + + void _openChat(BuildContext context, Conversation conversation) { + User? user; + Group? group; + + if (conversation.conversationType == 'user') { + user = conversation.conversationWith as User; + } else { + group = conversation.conversationWith as Group; + } + + Navigator.push( + context, + MaterialPageRoute( + builder: (_) => ChatScreen(user: user, group: group), + ), + ); + } +} +``` + + + +### Step 2: Create the Chat Screen + +Use the same `MessagesScreen` pattern from [One-to-One Chat](/ui-kit/flutter/v6/flutter-one-to-one-chat#step-2-render-the-messages-component): + + + +```dart +class ChatScreen extends StatelessWidget { + final User? user; + final Group? group; + + const ChatScreen({super.key, this.user, this.group}); + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: CometChatMessageHeader(user: user, group: group), + body: SafeArea( + child: Column( + children: [ + Expanded(child: CometChatMessageList(user: user, group: group)), + CometChatMessageComposer(user: user, group: group), + ], + ), + ), + ); + } +} +``` + + + +### Step 3: Complete Example + + + +```dart +import 'package:flutter/material.dart'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +void main() { + runApp(const MyApp()); +} + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'CometChat V6', + theme: ThemeData(useMaterial3: true), + home: const InitPage(), + ); + } +} + +class InitPage extends StatefulWidget { + const InitPage({super.key}); + + @override + State createState() => _InitPageState(); +} + +class _InitPageState extends State { + bool _ready = false; + + @override + void initState() { + super.initState(); + _init(); + } + + Future _init() async { + UIKitSettings settings = (UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..region = "REGION" + ..appId = "APP_ID" + ..authKey = "AUTH_KEY") + .build(); + + CometChatUIKit.init( + uiKitSettings: settings, + onSuccess: (_) { + CometChatUIKit.login("cometchat-uid-1", onSuccess: (_) { + setState(() => _ready = true); + }, onError: (e) {}); + }, + onError: (e) {}, + ); + } + + @override + Widget build(BuildContext context) { + if (!_ready) { + return const Scaffold(body: Center(child: CircularProgressIndicator())); + } + return const ConversationsScreen(); + } +} +``` + + diff --git a/ui-kit/flutter/v6/flutter-one-to-one-chat.mdx b/ui-kit/flutter/v6/flutter-one-to-one-chat.mdx new file mode 100644 index 000000000..d3af82fd6 --- /dev/null +++ b/ui-kit/flutter/v6/flutter-one-to-one-chat.mdx @@ -0,0 +1,232 @@ +--- +title: "Building A One To One/Group Chat Experience" +sidebarTitle: "One To One/Group Chat" +--- + +The One-to-One Chat feature provides a streamlined direct messaging interface, ideal for support chats, dating apps, and private messaging platforms. + +*** + +### Step 1: Render the Message View + +Fetch the target user and display the messaging screen. V6 uses the same `CometChatUIKit` initialization but with BLoC-powered widgets. + +```dart main.dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: FutureBuilder( + future: fetchCometChatUser("cometchat-uid-2"), + builder: (context, snapshot) { + if (snapshot.connectionState == ConnectionState.waiting) { + return const Center(child: CircularProgressIndicator()); + } else if (snapshot.hasError) { + return Center(child: Text("Error: ${snapshot.error}")); + } else if (snapshot.hasData) { + return MessagesScreen(user: snapshot.data!); + } else { + return const Center(child: Text("User not found")); + } + }, + ), + ), + ); +} +``` + +#### Full Example: main.dart + + + +```dart +import 'package:flutter/material.dart'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'messages_screen.dart'; +import 'cometchat_config.dart'; +import 'dart:async'; + +void main() => runApp(const MyApp()); + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'CometChat V6 UI Kit', + theme: ThemeData( + colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple), + useMaterial3: true, + ), + home: const Home(), + ); + } +} + +class Home extends StatelessWidget { + const Home({super.key}); + + Future _initializeAndLogin() async { + final settings = UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..appId = CometChatConfig.appId + ..region = CometChatConfig.region + ..authKey = CometChatConfig.authKey; + + await CometChatUIKit.init(uiKitSettings: settings.build()); + await CometChatUIKit.login( + 'cometchat-uid-1', + onSuccess: (_) => debugPrint('Login Successful'), + onError: (err) => throw Exception('Login Failed: $err'), + ); + } + + @override + Widget build(BuildContext context) { + return FutureBuilder( + future: _initializeAndLogin(), + builder: (ctx, snap) { + if (snap.connectionState != ConnectionState.done) { + return const Scaffold( + body: SafeArea(child: Center(child: CircularProgressIndicator())), + ); + } + if (snap.hasError) { + return Scaffold( + body: SafeArea( + child: Center(child: Text('Error:\n${snap.error}', textAlign: TextAlign.center)), + ), + ); + } + return const MessagesPage(); + }, + ); + } +} + +class MessagesPage extends StatelessWidget { + const MessagesPage({super.key}); + + Future fetchCometChatUser(String uid) async { + final completer = Completer(); + CometChat.getUser( + uid, + onSuccess: (user) => completer.complete(user), + onError: (error) => completer.completeError(error), + ); + return completer.future; + } + + @override + Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: FutureBuilder( + future: fetchCometChatUser("cometchat-uid-2"), + builder: (context, snapshot) { + if (snapshot.connectionState == ConnectionState.waiting) { + return const Center(child: CircularProgressIndicator()); + } else if (snapshot.hasError) { + return Center(child: Text("Error: ${snapshot.error}")); + } else if (snapshot.hasData) { + return MessagesScreen(user: snapshot.data!); + } else { + return const Center(child: Text("User not found")); + } + }, + ), + ), + ); + } +} +``` + + + +### Step 2: Render the Messages Component + +Compose the messaging view using: + +* [Message Header](/ui-kit/flutter/v6/message-header) +* [Message List](/ui-kit/flutter/v6/message-list) +* [Message Composer](/ui-kit/flutter/v6/message-composer) + + + +```dart +import 'package:flutter/material.dart'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class MessagesScreen extends StatefulWidget { + final User? user; + final Group? group; + + const MessagesScreen({Key? key, this.user, this.group}) : super(key: key); + + @override + State createState() => _MessagesScreenState(); +} + +class _MessagesScreenState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: CometChatMessageHeader( + user: widget.user, + group: widget.group, + ), + body: SafeArea( + child: Column( + children: [ + Expanded( + child: CometChatMessageList( + user: widget.user, + group: widget.group, + ), + ), + CometChatMessageComposer( + user: widget.user, + group: widget.group, + ), + ], + ), + ), + ); + } +} +``` + + + + + +*** + +### Step 3: Run the App + +``` +flutter run +``` + +This launches the app with the one-to-one chat interface featuring the message header, list, and composer. + +*** + +## Key V6 Differences + +| Aspect | V5 | V6 | +|---|---|---| +| Composite widget | `CometChatMessages` wraps header + list + composer | No composite — compose individually | +| State management | GetX controllers | BLoC pattern (`MessageListBloc`, `MessageComposerBloc`) | +| Extensions | `CometChatUIKitChatExtensions.getDefaultExtensions()` | Extensions handled via `MessageTemplateUtils` | +| Rich text | Not available | Built-in rich text formatting and code blocks | + +*** + +## Next Steps + +* [Advanced Customizations](/ui-kit/flutter/v6/theme-introduction) — Personalize the chat UI to align with your brand. +* [Message List](/ui-kit/flutter/v6/message-list) — Customize message display and behavior. +* [Message Composer](/ui-kit/flutter/v6/message-composer) — Configure rich text, attachments, and audio recording. diff --git a/ui-kit/flutter/v6/flutter-tab-based-chat.mdx b/ui-kit/flutter/v6/flutter-tab-based-chat.mdx new file mode 100644 index 000000000..8b9f5b40c --- /dev/null +++ b/ui-kit/flutter/v6/flutter-tab-based-chat.mdx @@ -0,0 +1,213 @@ +--- +title: "Building A Messaging UI With Tabs, Sidebar, And Message View" +sidebarTitle: "Tab Based Chat Experience" +--- + +This guide walks you through creating a tab-based messaging UI using Flutter and CometChat V6 UIKit. The UI includes sections for Chats, Users, and Groups, allowing seamless navigation. + +*** + +## User Interface Preview + +This layout consists of: + +1. Sidebar (Conversation List) — Displays recent conversations with active users and groups. +2. Message View — Shows the selected chat with real-time messages. +3. Message Input Box — Allows users to send messages seamlessly. + +*** + +### Step 1: Render the Tab Component + +Set up initialization and the tab-based layout. In V6, all list widgets (`CometChatConversations`, `CometChatUsers`, `CometChatGroups`) are powered by BLoC. + +#### Full Example: main.dart + + + +```dart +import 'package:flutter/material.dart'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'messages_screen.dart'; +import 'cometchat_config.dart'; + +void main() => runApp(const MyApp()); + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'CometChat V6 UI Kit', + theme: ThemeData( + colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple), + useMaterial3: true, + ), + home: const Home(), + ); + } +} + +class Home extends StatelessWidget { + const Home({super.key}); + + Future _initializeAndLogin() async { + final settings = UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..appId = CometChatConfig.appId + ..region = CometChatConfig.region + ..authKey = CometChatConfig.authKey; + + await CometChatUIKit.init(uiKitSettings: settings.build()); + await CometChatUIKit.login( + 'cometchat-uid-1', + onSuccess: (_) => debugPrint('Login Successful'), + onError: (err) => throw Exception('Login Failed: $err'), + ); + } + + @override + Widget build(BuildContext context) { + return FutureBuilder( + future: _initializeAndLogin(), + builder: (ctx, snap) { + if (snap.connectionState != ConnectionState.done) { + return const Scaffold( + body: SafeArea(child: Center(child: CircularProgressIndicator())), + ); + } + if (snap.hasError) { + return Scaffold( + body: SafeArea( + child: Center(child: Text('Error:\n${snap.error}', textAlign: TextAlign.center)), + ), + ); + } + return const TabsScreen(); + }, + ); + } +} + +class TabsScreen extends StatefulWidget { + const TabsScreen({super.key}); + + @override + State createState() => _TabsScreenState(); +} + +class _TabsScreenState extends State { + int _selectedIndex = 0; + final PageController _pageController = PageController(); + + void _onItemTapped(int index) { + setState(() { + _selectedIndex = index; + }); + _pageController.jumpToPage(index); + } + + @override + Widget build(BuildContext context) { + return Scaffold( + body: PageView( + controller: _pageController, + onPageChanged: (index) { + setState(() { + _selectedIndex = index; + }); + }, + children: [ + CometChatConversations( + showBackButton: false, + onItemTap: (conversation) { + Navigator.push( + context, + MaterialPageRoute( + builder: (context) => MessagesScreen( + user: conversation.conversationWith is User + ? conversation.conversationWith as User + : null, + group: conversation.conversationWith is Group + ? conversation.conversationWith as Group + : null, + ), + ), + ); + }, + ), + CometChatUsers(), + CometChatGroups(), + ], + ), + bottomNavigationBar: BottomNavigationBar( + currentIndex: _selectedIndex, + onTap: _onItemTapped, + items: const [ + BottomNavigationBarItem(icon: Icon(Icons.chat), label: "Chat"), + BottomNavigationBarItem(icon: Icon(Icons.person), label: "Users"), + BottomNavigationBarItem(icon: Icon(Icons.group), label: "Groups"), + ], + ), + ); + } +} +``` + + + +### Step 2: Render the Messages Component + +Use the same `MessagesScreen` pattern from [One-to-One Chat](/ui-kit/flutter/v6/flutter-one-to-one-chat#step-2-render-the-messages-component): + + + +```dart +import 'package:flutter/material.dart'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class MessagesScreen extends StatelessWidget { + final User? user; + final Group? group; + + const MessagesScreen({super.key, this.user, this.group}); + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: CometChatMessageHeader(user: user, group: group), + body: SafeArea( + child: Column( + children: [ + Expanded(child: CometChatMessageList(user: user, group: group)), + CometChatMessageComposer(user: user, group: group), + ], + ), + ), + ); + } +} +``` + + + + + +*** + +### Step 3: Run the App + +``` +flutter run +``` + +This launches the app with the tab-based chat experience. Navigate between Chats, Users, and Groups tabs and interact with the messaging features. + +*** + +## Next Steps + +* [Advanced Customizations](/ui-kit/flutter/v6/theme-introduction) — Personalize the chat UI to align with your brand. +* [Component Styling](/ui-kit/flutter/v6/component-styling) — Fine-tune individual component appearances. diff --git a/ui-kit/flutter/v6/getting-started.mdx b/ui-kit/flutter/v6/getting-started.mdx new file mode 100644 index 000000000..71857eab1 --- /dev/null +++ b/ui-kit/flutter/v6/getting-started.mdx @@ -0,0 +1,381 @@ +--- +title: "Getting Started With CometChat Flutter UI Kit V6" +sidebarTitle: "Getting Started" +--- + +CometChat UI Kit V6 for Flutter is a package of pre-assembled UI elements built on clean architecture with BLoC state management. It provides essential messaging functionalities with options for light and dark themes, diverse fonts, colors, and extensive customization capabilities. + +CometChat UI Kit V6 supports both one-to-one and group conversations. Follow the guide below to initiate conversations from scratch. + +## Prerequisites + +Before installing the **UI Kit**, you need to create a CometChat application on the CometChat Dashboard, which includes all the necessary data for a chat service, such as users, groups, calls, and messages. You will require the `App ID`, `AuthKey`, and `Region` of your CometChat application when initializing the SDK. + +**i. Register on CometChat** + +* You need to register on the **CometChat Dashboard** first. [Click here to sign up](https://app.cometchat.com/login). + +**ii. Get Your Application Keys** + +* Create a **new app** +* Head over to the **QuickStart** or **API & Auth Keys section** and note the **App ID**, **Auth Key**, and **Region**. + +> Each CometChat application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web. + +**iii. Platform & IDE Setup** + +* Flutter installed on your system. +* Android Studio or VS Code with configured Flutter/Dart plugins. +* Xcode & Pod (CocoaPods) for iOS. +* An iOS device or emulator with iOS 13.0 or above. +* Android device or emulator with Android version 7.0 (API 24) or above. + +## Getting Started + +### **Step 1: Create Flutter application project** + +To get started, create a new flutter application project. + +*** + +### **Step 2: Add Dependency** + +**1. Install via CLI** + +Since V6 is hosted on Cloudsmith (not pub.dev), run this command instead of the standard `flutter pub add`: + +```bash +dart pub add cometchat_chat_uikit:6.0.0-beta1 --hosted-url https://dart.cloudsmith.io/cometchat/cometchat/ +``` + +**2. Update Pubspec** + +Or add it manually to your `pubspec.yaml`: + +```yaml pubspec.yaml +dependencies: + cometchat_chat_uikit: + hosted: https://dart.cloudsmith.io/cometchat/cometchat/ + version: 6.0.0-beta1 +``` + +Final `pubspec.yaml` + +```yaml pubspec.yaml +name: my_chat_app +description: "A Flutter app with CometChat V6." + +publish_to: 'none' + +version: 1.0.0+1 + +environment: + sdk: ^3.8.0 + +dependencies: + flutter: + sdk: flutter + + cometchat_chat_uikit: + hosted: https://dart.cloudsmith.io/cometchat/cometchat/ + version: 6.0.0-beta1 + + cupertino_icons: ^1.0.8 + +dev_dependencies: + flutter_test: + sdk: flutter + + flutter_lints: ^4.0.0 + +flutter: + uses-material-design: true +``` + +*** + +**2. Android App Setup** + +Update the `minSdkVersion` in your Android project configuration, located at `android/app/build.gradle`: + +```gradle build.gradle +android { + defaultConfig { + minSdk = 24 + // Other configurations... + } +} +``` + +*** + +**3. Update iOS Podfile** + +In your Podfile (located at `ios/Podfile`), update the minimum iOS version: + +```ruby Podfile +platform :ios, '13.0' +``` + +*** + +**4. Import CometChat UIKit** + +In your Dart code, import the CometChat UIKit package: + +```dart main.dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +``` + +> V6 uses a single import. The `cometchat_uikit_shared` package is internalized — no separate import needed. + +*** + +### **Step 3: Initialize UI Kit** + +Before using any features from the CometChat UI Kit, initialize it with your app credentials. + +1. **Create a Configuration File:** + +```dart cometchat_config.dart +class CometChatConfig { + static const String appId = "APP_ID"; // Replace with your App ID + static const String region = "REGION"; // Replace with your App Region + static const String authKey = "AUTH_KEY"; // Replace with your Auth Key +} +``` + +2. **Initialize the UI Kit:** + +```dart main.dart +import 'cometchat_config.dart'; + +UIKitSettings uiKitSettings = (UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..region = CometChatConfig.region + ..appId = CometChatConfig.appId + ..authKey = CometChatConfig.authKey +).build(); + +CometChatUIKit.init( + uiKitSettings: uiKitSettings, + onSuccess: (successMessage) async { + debugPrint('CometChat Initialized'); + }, + onError: (error) { + debugPrint('CometChat Initialization error'); + }, +); +``` + +> **V6 difference from V5:** No `extensions` or `aiFeature` parameters needed. Extensions are built-in and handled automatically by `MessageTemplateUtils`. + +*** + +### **Step 4: Login to UI Kit** + +Once the UI Kit is initialized, authenticate your user using the `login()` method. + +```dart main.dart +CometChatUIKit.login( + "cometchat-uid-1", // Replace with a valid UID + onSuccess: (user) { + debugPrint('CometChat LoggedIn success'); + }, + onError: (error) { + debugPrint('CometChat LoggedIn error'); + }, +); +``` + +You can test using any of the following pre-generated users: + +* `cometchat-uid-1` +* `cometchat-uid-2` +* `cometchat-uid-3` +* `cometchat-uid-4` +* `cometchat-uid-5` + +> For more information, refer to the documentation on [Init](/ui-kit/flutter/v6/methods#init) and [Login](/ui-kit/flutter/v6/methods#login-using-auth-key). + +#### **Example: Initialization and Login Combined** + +```dart main.dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; +import 'cometchat_config.dart'; + +void main() { + runApp(const MyApp()); +} + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'CometChat V6', + theme: ThemeData(useMaterial3: true), + home: const InitPage(), + ); + } +} + +class InitPage extends StatefulWidget { + const InitPage({super.key}); + + @override + State createState() => _InitPageState(); +} + +class _InitPageState extends State { + bool _isInitializing = true; + String? _error; + + @override + void initState() { + super.initState(); + _initCometChat(); + } + + Future _initCometChat() async { + UIKitSettings uiKitSettings = (UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..region = CometChatConfig.region + ..appId = CometChatConfig.appId + ..authKey = CometChatConfig.authKey) + .build(); + + CometChatUIKit.init( + uiKitSettings: uiKitSettings, + onSuccess: (msg) { + CometChatUIKit.login( + "cometchat-uid-1", + onSuccess: (user) { + debugPrint('Logged in as: ${user.name}'); + setState(() => _isInitializing = false); + }, + onError: (error) { + setState(() { + _isInitializing = false; + _error = error.message; + }); + }, + ); + }, + onError: (error) { + setState(() { + _isInitializing = false; + _error = error.message; + }); + }, + ); + } + + @override + Widget build(BuildContext context) { + if (_isInitializing) { + return const Scaffold(body: Center(child: CircularProgressIndicator())); + } + if (_error != null) { + return Scaffold(body: Center(child: Text('Error: $_error'))); + } + return const Scaffold(body: Center(child: Text('Ready!'))); + } +} +``` + +*** + +### **Step 5: Choose a Chat Experience** + +Integrate a conversation view that suits your application's UX requirements. Below are the available options: + +*** + +### **1. Conversation List + Message View** + +**Best for:** Flutter apps that need a smooth, stack-based navigation between conversations and messages. + +**Highlights:** + +* **Compact Layout** – Uses `Navigator.push()` for mobile-first navigation. +* **One-to-One & Group Chats** – Built-in support for private and group conversations. +* **Real-Time Messaging** – Message list auto-refreshes with CometChat events. +* **BLoC-Powered** – Predictable state management with `ConversationsBloc` and `MessageListBloc`. + +**Use When:** + +* You want a clean navigation experience for multiple chat sessions. +* Your Flutter app supports both direct and group messaging. + +[Integrate Conversation List + Message View](./flutter-conversation) + +*** + +### **2. One-to-One / Group Chat** + +**Best for:** When a user lands directly into a chat screen, bypassing the conversation list. + +In V6, you compose the chat screen using individual widgets: + +```dart +Scaffold( + body: Column( + children: [ + CometChatMessageHeader(user: user), + Expanded(child: CometChatMessageList(user: user)), + CometChatMessageComposer(user: user), + ], + ), +) +``` + +> V6 does not have a combined `CometChatMessages` composite widget. You compose the UI yourself using `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer`. + +**Use When:** + +* Your chat starts from a specific user or group ID. +* You want a clean, focused chat interface. +* Use case involves support, onboarding, or one-time messages. + +[Integrate One-to-One / Group Chat](./flutter-one-to-one-chat) + +*** + +### **3. Tab-Based Messaging UI (All-in-One)** + +**Best for:** Flutter apps needing a multi-tab experience to access Chat, Users, Calls, and Settings. + +**Use When:** + +* You need a full-featured chat solution in one UI. +* Your users require structured navigation between modules. + +[Integrate Tab-Based Chat](./flutter-tab-based-chat) + +*** + +## **Build Your Own Chat Experience** + +**Best for:** Developers who need complete control over their chat interface. + +**Key Areas to Explore:** + +* **[Core Features](./core-features)** – Learn about messaging, real-time updates, and other essential capabilities. +* **[Components](./components-overview)** – Utilize prebuilt UI elements or customize them to fit your design. +* **[Themes](./theme-introduction)** – Adjust colors, fonts, and styles to match your branding. + +*** + +## **Next Steps** + +* **[Integrate Conversation List + Message](/ui-kit/flutter/v6/flutter-conversation)** +* **[Integrate One-to-One Chat](/ui-kit/flutter/v6/flutter-one-to-one-chat)** +* **[Integrate Tab-Based Chat](/ui-kit/flutter/v6/flutter-tab-based-chat)** +* **[Advanced Customizations](/ui-kit/flutter/v6/theme-introduction)** + +*** diff --git a/ui-kit/flutter/v6/group-members.mdx b/ui-kit/flutter/v6/group-members.mdx new file mode 100644 index 000000000..ecd43f52b --- /dev/null +++ b/ui-kit/flutter/v6/group-members.mdx @@ -0,0 +1,542 @@ +--- +title: "Group Members" +description: "Scrollable list of members in a group with scope indicators, search, and member management actions." +--- + +`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). + + + + + +--- + +## 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. + + + +```dart +CometChatGroupMembers( + group: group, + onItemTap: (groupMember) { + // Navigate to member profile or chat + }, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute( + builder: (context) => CometChatGroupMembers(group: group), +)); +``` + + + +Embedding as a widget: + + + +```dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatGroupMembers(group: group), + ), + ); +} +``` + + + +Prerequisites: CometChat SDK initialized, a user logged in, and a valid `Group` object. + +--- + +## Filtering Members + +Pass a `GroupMembersRequestBuilder` to control what loads: + + + +```dart +CometChatGroupMembers( + group: group, + groupMembersRequestBuilder: GroupMembersRequestBuilder(group.guid) + ..limit = 20 + ..searchKeyword = "john", +) +``` + + + +### 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. + + + +```dart +CometChatGroupMembers( + group: group, + onItemTap: (groupMember) { + // Navigate to member profile + }, +) +``` + + + +#### `onItemLongPress` + +Fires when a member row is long-pressed. By default shows the member action menu (kick/ban/scope change). + + + +```dart +CometChatGroupMembers( + group: group, + onItemLongPress: (groupMember) { + // Custom long press behavior + }, +) +``` + + + +#### `onBack` + +Fires when the user presses the back button. + + + +```dart +CometChatGroupMembers( + group: group, + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onSelection` + +Fires when members are selected/deselected in multi-select mode. + + + +```dart +CometChatGroupMembers( + group: group, + selectionMode: SelectionMode.multiple, + onSelection: (selectedMembers, context) { + // Handle selected members + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatGroupMembers( + group: group, + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +#### `onLoad` + +Fires when the list is successfully fetched. + + + +```dart +CometChatGroupMembers( + group: group, + onLoad: (memberList) { + debugPrint("Loaded ${memberList.length} members"); + }, +) +``` + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + +```dart +CometChatGroupMembers( + group: group, + onEmpty: () { + debugPrint("No members found"); + }, +) +``` + + + +### Global Events + +The component emits events via `CometChatGroupEvents`: + + + +```dart +class _YourScreenState extends State 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 + } +} +``` + + + +### 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 | +|---|---|---|---| +| `group` | `Group` | **required** | The group whose members to display | +| `title` | `String?` | `null` | Custom app bar title | +| `showBackButton` | `bool` | `true` | Toggle back button | +| `hideAppbar` | `bool?` | `false` | Toggle app bar visibility | +| `hideSearch` | `bool` | `false` | Toggle search bar | +| `usersStatusVisibility` | `bool?` | `true` | Show online/offline status | +| `selectionMode` | `SelectionMode?` | `null` | Enable selection mode | +| `hideKickMemberOption` | `bool?` | `false` | Hide kick option in action menu | +| `hideBanMemberOption` | `bool?` | `false` | Hide ban option in action menu | +| `hideScopeChangeOption` | `bool?` | `false` | Hide scope change option | + +--- + +## Custom View Slots + +### Leading View + + + +```dart +CometChatGroupMembers( + group: group, + leadingView: (context, groupMember) { + return CircleAvatar( + child: Text(groupMember.name?[0] ?? ""), + ); + }, +) +``` + + + +### Title View + + + +```dart +CometChatGroupMembers( + group: group, + titleView: (context, groupMember) { + return Text( + groupMember.name ?? "", + style: TextStyle(fontWeight: FontWeight.bold), + ); + }, +) +``` + + + +### Subtitle View + + + +```dart +CometChatGroupMembers( + group: group, + subtitleView: (context, groupMember) { + return Text( + groupMember.scope ?? "participant", + style: TextStyle(color: Color(0xFF727272), fontSize: 14), + ); + }, +) +``` + + + +### Trailing View + + + +```dart +CometChatGroupMembers( + group: group, + trailingView: (context, groupMember) { + return Chip(label: Text(groupMember.scope ?? "")); + }, +) +``` + + + +### List Item View + + + +```dart +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 ?? "")), + ); + }, +) +``` + + + +### State Views + + + +```dart +CometChatGroupMembers( + group: group, + emptyStateView: (context) => Center(child: Text("No members")), + errorStateView: (context) => Center(child: Text("Something went wrong")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), +) +``` + + + +--- + +## Menu Options + + + +```dart +// 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 + }, + ), + ]; + }, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +Provide a custom `GroupMembersBloc`: + + + +```dart +CometChatGroupMembers( + group: group, + groupMembersBloc: CustomGroupMembersBloc(), +) +``` + + + +### 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/v6/customization-bloc-data#listbase-hooks). + +### Public BLoC Methods + +| Method | Returns | Description | +|---|---|---| +| `getStatusNotifier(uid)` | `ValueNotifier` | 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 + + + +```dart +CometChatGroupMembers( + group: group, + groupMembersStyle: CometChatGroupMembersStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + statusIndicatorStyle: CometChatStatusIndicatorStyle(), + changeScopeStyle: CometChatChangeScopeStyle(), + confirmDialogStyle: CometChatConfirmDialogStyle(), + ), +) +``` + + + + + + + +### Style Properties + +| Property | Description | +|---|---| +| `avatarStyle` | Avatar appearance | +| `statusIndicatorStyle` | Online/offline indicator | +| `changeScopeStyle` | Scope change dialog style | +| `confirmDialogStyle` | Kick/ban confirmation dialog style | + +--- + +## Next Steps + + + + Browse available groups + + + Complete group chat implementation + + + Detailed styling reference + + + Browse recent conversations + + diff --git a/ui-kit/flutter/v6/groups.mdx b/ui-kit/flutter/v6/groups.mdx new file mode 100644 index 000000000..ba5edb50f --- /dev/null +++ b/ui-kit/flutter/v6/groups.mdx @@ -0,0 +1,484 @@ +--- +title: "Groups" +description: "Scrollable list of all available groups with search, avatars, group type indicators, and member counts." +--- + +`CometChatGroups` renders a scrollable list of all available groups with real-time updates for group events, search, avatars, group type indicators (public/private/password), and member counts. + + + + + +--- + +## Where It Fits + +`CometChatGroups` is a list component. It renders all available groups and emits the selected `Group` via `onItemTap`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a group chat layout. + + + +```dart +CometChatGroups( + onItemTap: (context, group) { + // Navigate to group chat + }, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatGroups())); +``` + + + +Embedding as a widget: + + + +```dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatGroups(), + ), + ); +} +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +--- + +## Filtering Groups + +Pass a `GroupsRequestBuilder` to control what loads: + + + +```dart +CometChatGroups( + groupsRequestBuilder: GroupsRequestBuilder() + ..limit = 10 + ..searchKeyword = "team", +) +``` + + + +### Filter Recipes + +| Recipe | Builder property | +|---|---| +| Limit per page | `..limit = 10` | +| Search by keyword | `..searchKeyword = "team"` | +| Joined groups only | `..joinedOnly = true` | +| Filter by tags | `..tags = ["project"]` | +| With tags | `..withTags = true` | + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemTap` + +Fires when a group row is tapped. Primary navigation hook. + + + +```dart +CometChatGroups( + onItemTap: (context, group) { + // Navigate to group chat screen + }, +) +``` + + + +#### `onItemLongPress` + +Fires when a group row is long-pressed. + + + +```dart +CometChatGroups( + onItemLongPress: (context, group) { + // Show context menu + }, +) +``` + + + +#### `onBack` + +Fires when the user presses the back button in the app bar. + + + +```dart +CometChatGroups( + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onSelection` + +Fires when groups are selected/deselected in multi-select mode. + + + +```dart +CometChatGroups( + selectionMode: SelectionMode.multiple, + onSelection: (selectedGroups, context) { + // Handle selected groups + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatGroups( + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + +```dart +CometChatGroups( + onLoad: (groupList) { + debugPrint("Loaded ${groupList.length} groups"); + }, +) +``` + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + +```dart +CometChatGroups( + onEmpty: () { + debugPrint("No groups found"); + }, +) +``` + + + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +|---|---| +| `onGroupMemberJoined` | Updates group member count | +| `onGroupMemberLeft` | Updates group member count | +| `onGroupMemberKicked` | Updates group member count, removes group if logged-in user was kicked | +| `onGroupMemberBanned` | Updates group member count, removes group if logged-in user was banned | +| `onMemberAddedToGroup` | Updates group member count | +| `ccGroupCreated` | Adds new group to list | +| `ccGroupDeleted` | Removes group from list | +| Connection reconnected | Triggers silent refresh | + +--- + +## Functionality + +| Property | Type | Default | Description | +|---|---|---|---| +| `title` | `String?` | `null` | Custom app bar title | +| `showBackButton` | `bool` | `true` | Toggle back button | +| `hideAppbar` | `bool?` | `false` | Toggle app bar visibility | +| `hideSearch` | `bool` | `false` | Toggle search bar | +| `selectionMode` | `SelectionMode?` | `null` | Enable selection mode (`single` or `multiple`) | +| `searchPlaceholder` | `String?` | `null` | Search placeholder text | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + +```dart +CometChatGroups( + leadingView: (context, group) { + return CircleAvatar( + child: Text(group.name?[0] ?? "G"), + ); + }, +) +``` + + + +### Title View + +Replace the group name / title text. + + + +```dart +CometChatGroups( + titleView: (context, group) { + return Text( + group.name ?? "", + style: TextStyle(fontWeight: FontWeight.bold), + ); + }, +) +``` + + + +### Subtitle View + +Replace the subtitle text below the group name. + + + +```dart +CometChatGroups( + subtitleView: (context, group) { + return Text( + "${group.membersCount} members", + style: TextStyle(color: Color(0xFF727272), fontSize: 14), + ); + }, +) +``` + + + +### Trailing View + +Replace the right section of each group item. + + + +```dart +CometChatGroups( + trailingView: (context, group) { + return Text(group.type ?? ""); + }, +) +``` + + + +### List Item View + +Replace the entire list item row. + + + +```dart +CometChatGroups( + listItemView: (group) { + return ListTile( + leading: CircleAvatar(child: Text(group.name?[0] ?? "G")), + title: Text(group.name ?? ""), + subtitle: Text("${group.membersCount} members"), + ); + }, +) +``` + + + +### State Views + + + +```dart +CometChatGroups( + emptyStateView: (context) => Center(child: Text("No groups found")), + errorStateView: (context) => Center(child: Text("Something went wrong")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), +) +``` + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + +```dart +CometChatGroups( + hideAppbar: true, + hideSearch: true, +) +``` + + + +### Joined groups only + + + +```dart +CometChatGroups( + groupsRequestBuilder: GroupsRequestBuilder() + ..joinedOnly = true, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +Provide a custom `GroupsBloc` to override behavior: + + + +```dart +CometChatGroups( + groupsBloc: CustomGroupsBloc(), +) +``` + + + +### Extending GroupsBloc + +`GroupsBloc` uses the `ListBase` mixin with override hooks: + + + +```dart +class CustomGroupsBloc extends GroupsBloc { + @override + void onItemAdded(Group item, List updatedList) { + // Custom sorting logic + super.onItemAdded(item, updatedList); + } + + @override + void onListReplaced(List previousList, List newList) { + // Filter out specific groups + final filtered = newList.where((g) => g.membersCount > 0).toList(); + super.onListReplaced(previousList, filtered); + } +} +``` + + + +For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/ui-kit/flutter/v6/customization-bloc-data#listbase-hooks). + +### Public BLoC Events + +| Event | Description | +|---|---| +| `LoadGroups({searchKeyword, silent})` | Load initial groups. `silent: true` keeps existing list visible. | +| `LoadMoreGroups()` | Load next page (pagination) | +| `RefreshGroups()` | Refresh the list | +| `SearchGroups(keyword)` | Search groups with debouncing | + +--- + +## Style + + + +```dart +CometChatGroups( + groupsStyle: CometChatGroupsStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + statusIndicatorStyle: CometChatStatusIndicatorStyle(), + ), +) +``` + + + + + + + +### Style Properties + +| Property | Description | +|---|---| +| `backgroundColor` | List background color | +| `avatarStyle` | Avatar appearance | +| `statusIndicatorStyle` | Group type indicator | +| `searchBoxStyle` | Search box appearance | + +See [Component Styling](/ui-kit/flutter/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + View and manage group members + + + Browse recent conversations + + + Detailed styling reference + + + Complete group chat implementation + + diff --git a/ui-kit/flutter/v6/guide-block-unblock-user.mdx b/ui-kit/flutter/v6/guide-block-unblock-user.mdx new file mode 100644 index 000000000..98f0bcf6c --- /dev/null +++ b/ui-kit/flutter/v6/guide-block-unblock-user.mdx @@ -0,0 +1,86 @@ +--- +title: "Implementing Block/Unblock User in Flutter with CometChat UIKit" +sidebarTitle: "Block/Unblock User" +--- + +Enable users to block and unblock other users in your Flutter chat app using CometChat's `blockUsers` and `unblockUsers` methods. + +## Overview + +The Block User feature lets one user prevent another from sending messages or interacting with them. Essential for user privacy, spam control, and moderation. + +## Prerequisites + +- A Flutter project with CometChat UIKit Flutter V6 installed +- Initialized CometChat credentials (`appID`, `region`, `authKey`) + +## Components + +| Component | Role | +|:---|:---| +| `CometChatUIKit.blockUsers([...])` | SDK method to block specified user(s) | +| `CometChatUIKit.unblockUsers([...])` | SDK method to unblock specified user(s) | +| `ElevatedButton` | Flutter widget for block/unblock actions | + +## Integration Steps + +### Add "Block User" Button + + + +```dart +ElevatedButton( + onPressed: () async { + try { + await CometChatUIKit.blockUsers([user.uid]); + ScaffoldMessenger.of(context).showSnackBar( + SnackBar(content: Text('${user.name} has been blocked')), + ); + } catch (e) { + ScaffoldMessenger.of(context).showSnackBar( + SnackBar(content: Text('Error blocking user: $e')), + ); + } + }, + child: Text('Block User'), +) +``` + + + +### Add "Unblock User" Button + + + +```dart +ElevatedButton( + onPressed: () async { + try { + await CometChatUIKit.unblockUsers([user.uid]); + ScaffoldMessenger.of(context).showSnackBar( + SnackBar(content: Text('${user.name} has been unblocked')), + ); + } catch (e) { + ScaffoldMessenger.of(context).showSnackBar( + SnackBar(content: Text('Error unblocking user: $e')), + ); + } + }, + child: Text('Unblock User'), +) +``` + + + +## Customization Options + +- Conditional Rendering: Display "Block" or "Unblock" based on `user.blockedByMe` state +- Modal Confirmation: Wrap actions in `showDialog` for confirmation prompts +- Self-Block Prevention: Disable the button if `user.uid == loggedInUser.uid` + +## Summary + +| Feature | Method | +|:---|:---| +| Block User | `CometChatUIKit.blockUsers([...])` | +| Unblock User | `CometChatUIKit.unblockUsers([...])` | diff --git a/ui-kit/flutter/v6/guide-call-log-details.mdx b/ui-kit/flutter/v6/guide-call-log-details.mdx new file mode 100644 index 000000000..9332d44f0 --- /dev/null +++ b/ui-kit/flutter/v6/guide-call-log-details.mdx @@ -0,0 +1,91 @@ +--- +title: "Call Log Details" +sidebarTitle: "Call Log Details" +--- + +Provide a post-call details screen with metadata, participants, history, and recordings using CometChat V6 UIKit. + +## Overview + +The Call Log Details feature displays detailed information about a specific call, including participants, duration, timestamps, and recordings (if available). + +## Components + +| Component | Role | +|:---|:---| +| `CometChatCallLogs` | Lists call logs; tap to view details | +| `CallLogRequestBuilder` | Filters call logs by criteria | + +## Integration + +### Navigate to Call Details + + + +```dart +CometChatCallLogs( + onItemClick: (callLog) { + Navigator.push( + context, + MaterialPageRoute( + builder: (_) => CallLogDetailScreen(callLog: callLog), + ), + ); + }, +) +``` + + + +### Build a Call Detail Screen + + + +```dart +class CallLogDetailScreen extends StatelessWidget { + final CallLog callLog; + + const CallLogDetailScreen({required this.callLog, super.key}); + + @override + Widget build(BuildContext context) { + final initiatedAt = DateTime.fromMillisecondsSinceEpoch( + (callLog.initiatedAt ?? 0) * 1000, + ); + + return Scaffold( + appBar: AppBar(title: const Text("Call Details")), + body: Padding( + padding: const EdgeInsets.all(16), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text("Status: ${callLog.status ?? 'Unknown'}"), + Text("Type: ${callLog.type ?? 'Unknown'}"), + Text("Duration: ${callLog.totalDurationInMinutes ?? 0} min"), + Text("Time: $initiatedAt"), + if (callLog.hasRecording == true) + const Text("Recording available"), + ], + ), + ), + ); + } +} +``` + + + +## Filtering Call Logs + + + +```dart +CometChatCallLogs( + callLogsRequestBuilder: CallLogRequestBuilder() + ..limit = 20 + ..hasRecording = true, +) +``` + + diff --git a/ui-kit/flutter/v6/guide-group-chat.mdx b/ui-kit/flutter/v6/guide-group-chat.mdx new file mode 100644 index 000000000..c157201e3 --- /dev/null +++ b/ui-kit/flutter/v6/guide-group-chat.mdx @@ -0,0 +1,91 @@ +--- +title: "Group Chat" +sidebarTitle: "Group Chat" +--- + +Build group chat functionality in your Flutter app using CometChat V6 UIKit. Create/join groups, view members, manage roles, and moderate participation. + +## Overview + +V6 provides `CometChatGroups` and `CometChatGroupMembers` widgets powered by BLoC for group management. + +## Components + +| Component | Role | +|:---|:---| +| `CometChatGroups` | Lists available groups | +| `CometChatGroupMembers` | Displays and manages group members | +| `CometChatMessageHeader` | Shows group info in chat header | +| `CometChatMessageList` | Displays group messages | +| `CometChatMessageComposer` | Sends messages to group | + +## Integration + +### Display Groups List + + + +```dart +CometChatGroups( + onItemTap: (group) { + Navigator.push( + context, + MaterialPageRoute( + builder: (_) => Scaffold( + appBar: CometChatMessageHeader(group: group), + body: SafeArea( + child: Column( + children: [ + Expanded(child: CometChatMessageList(group: group)), + CometChatMessageComposer(group: group), + ], + ), + ), + ), + ), + ); + }, +) +``` + + + +### Display Group Members + + + +```dart +CometChatGroupMembers( + group: group, + onItemTap: (groupMember) { + // Handle member tap + }, +) +``` + + + +### Manage Members + +V6 provides built-in options for member management: + + + +```dart +CometChatGroupMembers( + group: group, + hideKickMemberOption: false, + hideBanMemberOption: false, + hideScopeChangeOption: false, +) +``` + + + +## Key V6 Differences + +| Aspect | V5 | V6 | +|---|---|---| +| Composite widget | `CometChatGroupsWithMessages` | Not available — compose manually | +| State management | GetX | BLoC (`GroupsBloc`) | +| Member management | Via configuration objects | Direct widget properties | diff --git a/ui-kit/flutter/v6/guide-message-agentic-flow.mdx b/ui-kit/flutter/v6/guide-message-agentic-flow.mdx new file mode 100644 index 000000000..6f0f76bd5 --- /dev/null +++ b/ui-kit/flutter/v6/guide-message-agentic-flow.mdx @@ -0,0 +1,87 @@ +--- +title: "Message Agentic Flow" +sidebarTitle: "Message Agentic Flow" +--- + +Implement agentic message flows in your Flutter app using CometChat V6 UIKit. This guide covers how to integrate AI-powered message handling with the chat interface. + +## Overview + +The Message Agentic Flow feature enables AI-driven interactions within your chat application. In V6, AI features are handled through `MessageTemplateUtils` rather than explicit extension registration. + +## Integration + +### Enable AI Features + +Ensure AI features are enabled on your CometChat Dashboard. V6 handles AI integration internally. + +### Custom AI Message Handling + + + +```dart +CometChatMessageList( + user: user, + templates: [ + CometChatMessageTemplate( + type: "ai_response", + category: MessageCategoryConstants.custom, + contentView: (baseMessage, context, alignment, {additionalConfigurations}) { + // Custom rendering for AI agent messages + return Container( + padding: const EdgeInsets.all(12), + decoration: BoxDecoration( + color: Color(0xFFEDEAFA), + borderRadius: BorderRadius.circular(12), + ), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Row( + children: [ + Icon(Icons.smart_toy, color: Color(0xFF6852D6), size: 16), + SizedBox(width: 4), + Text("AI Assistant", style: TextStyle( + color: Color(0xFF6852D6), + fontWeight: FontWeight.bold, + fontSize: 12, + )), + ], + ), + SizedBox(height: 8), + Text((baseMessage as TextMessage).text), + ], + ), + ); + }, + ), + ], +) +``` + + + +### AI Assistant Chat History + +Use the `CometChatAIAssistantChatHistory` widget to display past AI interactions: + + + +```dart +CometChatAIAssistantChatHistory( + user: user, + style: CometChatAIAssistantChatHistoryStyle( + backgroundColor: const Color(0xFFFFFAF6), + ), +) +``` + + + +## Key V6 Differences + +| Aspect | V5 | V6 | +|---|---|---| +| AI extension registration | Explicit via `UIKitSettings.aiFeature` | Handled internally via `MessageTemplateUtils` | +| Custom AI templates | Via `CometChatUIKit.getDataSource()` | Via `MessageTemplateUtils` and direct template injection | +| AI Assistant widget | `CometChatAIAssistantChatHistory` | Same widget, same API | diff --git a/ui-kit/flutter/v6/guide-message-privately.mdx b/ui-kit/flutter/v6/guide-message-privately.mdx new file mode 100644 index 000000000..a764f1c40 --- /dev/null +++ b/ui-kit/flutter/v6/guide-message-privately.mdx @@ -0,0 +1,62 @@ +--- +title: "Message Privately" +sidebarTitle: "Message Privately" +--- + +Start a direct 1:1 chat from a profile or list in your Flutter app using CometChat V6 UIKit. + +## Overview + +The "Message Privately" feature allows users to initiate a direct conversation with another user from any context — a group member list, user profile, or search results. + +## Integration + +### Navigate to Private Chat + + + +```dart +void openPrivateChat(BuildContext context, User user) { + Navigator.push( + context, + MaterialPageRoute( + builder: (_) => Scaffold( + appBar: CometChatMessageHeader(user: user), + body: SafeArea( + child: Column( + children: [ + Expanded(child: CometChatMessageList(user: user)), + CometChatMessageComposer(user: user), + ], + ), + ), + ), + ), + ); +} +``` + + + +### From Group Members List + + + +```dart +CometChatGroupMembers( + group: group, + onItemTap: (groupMember) { + // Convert GroupMember to User for private messaging + User user = User( + uid: groupMember.uid, + name: groupMember.name, + avatar: groupMember.avatar, + ); + openPrivateChat(context, user); + }, +) +``` + + + + diff --git a/ui-kit/flutter/v6/guide-new-chat.mdx b/ui-kit/flutter/v6/guide-new-chat.mdx new file mode 100644 index 000000000..fa962d94a --- /dev/null +++ b/ui-kit/flutter/v6/guide-new-chat.mdx @@ -0,0 +1,94 @@ +--- +title: "New Chat" +sidebarTitle: "New Chat" +--- + +Offer a unified discovery screen for users and groups and launch new chats quickly using CometChat V6 UIKit. + +## Overview + +The "New Chat" feature provides a screen where users can browse available users and groups to start a new conversation. + +## Integration + +### Create a New Chat Screen + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; + +class NewChatScreen extends StatelessWidget { + const NewChatScreen({super.key}); + + void _openChat(BuildContext context, {User? user, Group? group}) { + Navigator.push( + context, + MaterialPageRoute( + builder: (_) => Scaffold( + appBar: CometChatMessageHeader(user: user, group: group), + body: SafeArea( + child: Column( + children: [ + Expanded(child: CometChatMessageList(user: user, group: group)), + CometChatMessageComposer(user: user, group: group), + ], + ), + ), + ), + ), + ); + } + + @override + Widget build(BuildContext context) { + return DefaultTabController( + length: 2, + child: Scaffold( + appBar: AppBar( + title: const Text('New Chat'), + bottom: const TabBar( + tabs: [ + Tab(text: 'Users'), + Tab(text: 'Groups'), + ], + ), + ), + body: TabBarView( + children: [ + CometChatUsers( + hideAppbar: true, + onItemTap: (user) => _openChat(context, user: user), + ), + CometChatGroups( + hideAppbar: true, + onItemTap: (group) => _openChat(context, group: group), + ), + ], + ), + ), + ); + } +} +``` + + + +### Launch from a FAB + + + +```dart +FloatingActionButton( + onPressed: () { + Navigator.push( + context, + MaterialPageRoute(builder: (_) => const NewChatScreen()), + ); + }, + child: const Icon(Icons.chat), +) +``` + + diff --git a/ui-kit/flutter/v6/guide-overview.mdx b/ui-kit/flutter/v6/guide-overview.mdx new file mode 100644 index 000000000..86311f450 --- /dev/null +++ b/ui-kit/flutter/v6/guide-overview.mdx @@ -0,0 +1,22 @@ +--- +title: "Overview" +sidebarTitle: "Overview" +--- + +> This page indexes focused, task-oriented feature guides for the Flutter V6 UI Kit. Each guide shows how to implement a specific capability end-to-end using V6 UI kit components. + +## When to Use These Guides + +Use these after finishing [Getting Started](/ui-kit/flutter/v6/getting-started) and wiring a basic conversations/messages experience. Add them incrementally to deepen functionality without rebuilding fundamentals. + +## Guide Directory + +| Guide | Description | +|:------|:------------| +| [Block / Unblock User](/ui-kit/flutter/v6/guide-block-unblock-user) | Let users block or unblock others; enforce privacy by hiding interaction options and preventing message flow. | +| [Group Chat](/ui-kit/flutter/v6/guide-group-chat) | Create/join groups, view members, add/remove users, manage roles, and moderate participation. | +| [Message Privately](/ui-kit/flutter/v6/guide-message-privately) | Start a direct 1:1 chat from a profile or list. | +| [New Chat](/ui-kit/flutter/v6/guide-new-chat) | Offer a unified discovery screen for users and groups and launch new chats quickly. | +| [Threaded Messages](/ui-kit/flutter/v6/guide-threaded-messages) | Enable threaded replies: open parent message context, browse replies, and compose within a focused thread. | + + diff --git a/ui-kit/flutter/v6/guide-threaded-messages.mdx b/ui-kit/flutter/v6/guide-threaded-messages.mdx new file mode 100644 index 000000000..0e0ea924e --- /dev/null +++ b/ui-kit/flutter/v6/guide-threaded-messages.mdx @@ -0,0 +1,118 @@ +--- +title: "Threaded Messages" +sidebarTitle: "Threaded Messages" +--- + +Enhance your Flutter chat app with threaded messaging using CometChat V6's `CometChatMessageList` and `CometChatThreadedHeader` components. + +## Overview + +- Reply to specific messages to start focused sub-conversations +- View all replies grouped under the parent message +- Seamlessly switch back to the main conversation + +## Prerequisites + +- A Flutter project with CometChat UIKit Flutter V6 installed +- Initialized CometChat credentials + +## Components + +| Component | Role | +|:---|:---| +| `CometChatMessageList` | Displays main chat; provides `onThreadRepliesClick` callback | +| `CometChatThreadedHeader` | Shows the parent message and thread context | +| `CometChatMessageComposer` | Sends new messages; pass `parentMessageId` for replies | + +## Integration Steps + +### Show the "Reply in Thread" Option + + + +```dart +CometChatMessageList( + user: user, + onThreadRepliesClick: (BaseMessage message) { + Navigator.push( + context, + MaterialPageRoute( + builder: (_) => ThreadScreen(parentMessage: message, user: user), + ), + ); + }, +) +``` + + + +### Navigate to the Thread Screen + +In V6, compose the thread screen using individual widgets: + + + +```dart +class ThreadScreen extends StatelessWidget { + final BaseMessage parentMessage; + final User? user; + final Group? group; + + const ThreadScreen({required this.parentMessage, this.user, this.group, super.key}); + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: AppBar(title: Text("Thread")), + body: Column( + children: [ + CometChatThreadedHeader(message: parentMessage), + Expanded( + child: CometChatMessageList( + user: user, + group: group, + parentMessageId: parentMessage.id, + ), + ), + CometChatMessageComposer( + user: user, + group: group, + parentMessageId: parentMessage.id, + ), + ], + ), + ); + } +} +``` + + + +### Send a Threaded Message + + + +```dart +CometChatMessageComposer( + user: user, + parentMessageId: parentMessage.id, +) +``` + + + +## Customization Options + +- Header Styling: Customize `CometChatThreadedHeader` appearance +- Composer Placeholder: Change placeholder text based on thread context +- Empty State: Display "No replies yet" when thread is empty + +## Summary + +| Feature | Component / Method | +|:---|:---| +| Show thread option | `CometChatMessageList.onThreadRepliesClick` | +| Thread view screen | Custom `ThreadScreen` widget | +| Display threaded messages | `CometChatMessageList(parentMessageId: ...)` | +| Send threaded message | `CometChatMessageComposer(parentMessageId: ...)` | +| Thread header | `CometChatThreadedHeader(message: ...)` | diff --git a/ui-kit/flutter/v6/incoming-call.mdx b/ui-kit/flutter/v6/incoming-call.mdx new file mode 100644 index 000000000..3890ebb27 --- /dev/null +++ b/ui-kit/flutter/v6/incoming-call.mdx @@ -0,0 +1,238 @@ +--- +title: "Incoming Call" +description: "Full-screen overlay for incoming audio and video calls with accept/reject options." +--- + +`CometChatIncomingCall` displays a full-screen overlay when an incoming call is received, showing caller info with accept and reject buttons. + +--- + +## Where It Fits + +Typically triggered automatically when `CallNavigationContext.navigatorKey` is set in your `MaterialApp`. + + + +```dart +MaterialApp(navigatorKey: CallNavigationContext.navigatorKey, home: YourHomeScreen()) +``` + + + +--- + +## Quick Start + +### Automatic (Recommended) + + + +```dart +MaterialApp(navigatorKey: CallNavigationContext.navigatorKey, home: YourHomeScreen()) +``` + + + +### Manual Launch + + + +```dart +Navigator.push(context, MaterialPageRoute( + builder: (context) => CometChatIncomingCall(user: user, call: callObject), +)); +``` + + + +Prerequisites: CometChat SDK initialized, Calls UIKit added, `callingExtension` set. See [Call Features](/ui-kit/flutter/call-features). + +--- + +## Actions + +#### `onAccept` + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + onAccept: (BuildContext context, Call call) { /* Custom accept */ }, +) +``` + + + +#### `onDecline` + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + onDecline: (BuildContext context, Call call) { /* Custom decline */ }, +) +``` + + + +#### `onError` + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + onError: (e) { debugPrint("Error: ${e.message}"); }, +) +``` + + + + + +--- + +## Functionality + +| Property | Type | Description | +|---|---|---| +| `user` | `User?` | Caller user object | +| `call` | `Call` | Call object (required) | +| `callSettingsBuilder` | `CallSettingsBuilder?` | Configure call settings | +| `height` / `width` | `double?` | Widget dimensions | +| `callIcon` | `Widget?` | Custom call type icon | +| `acceptButtonText` | `String?` | Custom accept button text | +| `declineButtonText` | `String?` | Custom decline button text | +| `disableSoundForCalls` | `bool?` | Disable incoming call sound | +| `customSoundForCalls` | `String?` | Custom sound asset path | + +--- + +## Custom View Slots + +### Item View + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + itemView: (context, call) { return Container(); }, +) +``` + + + +### Leading View + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + leadingView: (context, call) { + return CircleAvatar(radius: 40, backgroundImage: NetworkImage(call.sender?.avatar ?? "")); + }, +) +``` + + + +### Title View + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + titleView: (context, call) { + return Text(call.sender?.name ?? "Unknown", + style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold, color: Colors.white)); + }, +) +``` + + + +### Subtitle View + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + subTitleView: (context, call) { + final type = call.type == CometChatConstants.CALL_TYPE_VIDEO ? "Video" : "Audio"; + return Text("Incoming $type Call", style: TextStyle(fontSize: 14, color: Colors.white70)); + }, +) +``` + + + +### Trailing View + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + trailingView: (context, call) { + return Row(mainAxisAlignment: MainAxisAlignment.spaceEvenly, children: [ + ElevatedButton(onPressed: () {}, child: Text("Reject"), + style: ElevatedButton.styleFrom(backgroundColor: Colors.red)), + ElevatedButton(onPressed: () {}, child: Text("Accept"), + style: ElevatedButton.styleFrom(backgroundColor: Colors.green)), + ]); + }, +) +``` + + + +--- + +## Style + + + +```dart +CometChatIncomingCall(user: user, call: callObject, + incomingCallStyle: CometChatIncomingCallStyle( + backgroundColor: Color(0xFFEDEAFA), + avatarStyle: CometChatAvatarStyle(backgroundColor: Color(0xFFAA9EE8), borderRadius: BorderRadius.circular(7.5)), + acceptButtonColor: Color(0xFF6852D6), + declineButtonColor: Colors.white, + declineTextColor: Color(0xFFF44649), + callIconColor: Color(0xFF6852D6), + ), +) +``` + + + +| Property | Description | +|---|---| +| `backgroundColor` | Background color | +| `avatarStyle` | Caller avatar appearance | +| `acceptButtonColor` | Accept button background | +| `declineButtonColor` | Decline button background | +| `declineTextColor` | Decline button text color | +| `callIconColor` | Call type icon color | + +--- + +## Key V6 Differences + +| Aspect | V5 | V6 | +|---|---|---| +| Subtitle | Static `String?` | Dynamic `Widget? Function(BuildContext, Call)?` | +| Decline icon | URL-based `String?` | Widget-based | +| Custom views | Limited | Full `titleView`, `subTitleView`, `leadingView`, `trailingView`, `itemView` | +| State management | GetX controller | BLoC (`IncomingCallBloc`) | +| Removed | `theme`, `avatarStyle`, `cardStyle`, `ongoingCallConfiguration` | Integrated into main style | + +--- + +## Next Steps + + + Manage outgoing calls + Add call buttons + Complete calling setup + Styling reference + diff --git a/ui-kit/flutter/v6/localize.mdx b/ui-kit/flutter/v6/localize.mdx new file mode 100644 index 000000000..ede87425f --- /dev/null +++ b/ui-kit/flutter/v6/localize.mdx @@ -0,0 +1,166 @@ +--- +title: "Localize" +--- + +## Overview + +CometChat V6 UI Kit provides language localization to adapt to the language of a specific country or region. The `CometChatLocalize` class allows you to detect the language of your users based on their device settings and set the language accordingly. + +The UI Kit supports 19 languages: + +* Arabic (ar), German (de), English (en, en-GB), Spanish (es), French (fr), Hindi (hi), Hungarian (hu), Japanese (ja), Korean (ko), Lithuanian (lt), Malay (ms), Dutch (nl), Portuguese (pt), Russian (ru), Swedish (sv), Turkish (tr), Chinese (zh, zh-TW) + +## Usage + +### Integration + +Add the following dependency in `pubspec.yaml`: + + + +```yaml +flutter_localizations: + sdk: flutter +``` + + + +*** + +Update MaterialApp Localizations Delegates: + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:cometchat_uikit_shared/l10n/translations.dart' as cc; +import 'package:flutter/material.dart'; +import 'package:flutter_localizations/flutter_localizations.dart'; + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp( + supportedLocales: const [ + Locale('en'), Locale('en', 'GB'), Locale('ar'), Locale('de'), + Locale('es'), Locale('fr'), Locale('hi'), Locale('hu'), + Locale('ja'), Locale('ko'), Locale('lt'), Locale('ms'), + Locale('nl'), Locale('pt'), Locale('ru'), Locale('sv'), + Locale('tr'), Locale('zh'), Locale('zh', 'TW'), + ], + localizationsDelegates: const [ + cc.Translations.delegate, + GlobalMaterialLocalizations.delegate, + GlobalWidgetsLocalizations.delegate, + GlobalCupertinoLocalizations.delegate, + ], + theme: ThemeData( + appBarTheme: AppBarTheme(scrolledUnderElevation: 0.0), + ), + title: 'CometChat Flutter App', + home: YourHomeScreen(), + debugShowCheckedModeBanner: false, + ); + } +} +``` + + + +*** + +You can also translate specific strings: + + + +```dart +String translatedString = Translations.of(context).users; +Text(translatedString); +``` + + + +### Customizing UI Kit Translations for a Specific Language + +Override a specific language's default translations by creating a custom localization class: + + + +```dart +import 'dart:async'; +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart' as cc; +import 'package:flutter/foundation.dart'; +import 'package:flutter/material.dart'; + +class CustomEN extends TranslationsEn { + static const delegate = _CustomCometChatLocalizationsDelegate(); + + @override + String get chats => "Overridden Chat"; + + @override + String get calls => "Overridden Call"; +} + +class _CustomCometChatLocalizationsDelegate + extends LocalizationsDelegate { + const _CustomCometChatLocalizationsDelegate(); + + @override + bool isSupported(Locale locale) => locale.languageCode == 'en'; + + @override + Future load(Locale locale) => + SynchronousFuture(CustomEN()); + + @override + bool shouldReload(_CustomCometChatLocalizationsDelegate old) => false; +} +``` + + + +Then add `CustomEN.delegate` to your `localizationsDelegates` list before `cc.Translations.delegate`. + +### Adding New Language Support + +Extend the UI Kit with a new language by creating a custom translation class: + + + +```dart +class TeluguLocalization extends cc.Translations { + TeluguLocalization([super.locale = "te"]); + static const delegate = _TeluguLocalizationsDelegate(); + + @override + String get chats => "సందేశాలు"; + + @override + String get calls => "ఫోన్ కాల్స్"; + // Override all relevant strings for full localization +} + +class _TeluguLocalizationsDelegate + extends LocalizationsDelegate { + const _TeluguLocalizationsDelegate(); + + @override + bool isSupported(Locale locale) => locale.languageCode == 'te'; + + @override + Future load(Locale locale) => + SynchronousFuture(TeluguLocalization()); + + @override + bool shouldReload(_TeluguLocalizationsDelegate old) => false; +} +``` + + + +### DateTimeFormatter + +By providing a custom `DateTimeFormatterCallback`, you can globally configure how time and date values are displayed across all UI components. For details, refer to the [CometChatUIKit class](/ui-kit/flutter/v6/methods#dateformatter). diff --git a/ui-kit/flutter/v6/mentions-formatter-guide.mdx b/ui-kit/flutter/v6/mentions-formatter-guide.mdx new file mode 100644 index 000000000..dfef364a7 --- /dev/null +++ b/ui-kit/flutter/v6/mentions-formatter-guide.mdx @@ -0,0 +1,147 @@ +--- +title: "Mentions Formatter" +--- + +## Overview + +The `CometChatMentionsFormatter` class formats mentions within text messages displayed in the chat interface. For the base `CometChatTextFormatter` API, see [Text Formatters](/ui-kit/flutter/v6/customization-text-formatters). + +## Usage + +Pass `CometChatMentionsFormatter` to the `textFormatters` property of widgets like [CometChatConversations](/ui-kit/flutter/v6/conversations), [CometChatMessageList](/ui-kit/flutter/v6/message-list), or [CometChatMessageComposer](/ui-kit/flutter/v6/message-composer). + + + +```dart +textFormatters: [ + CometChatMentionsFormatter( + messageBubbleTextStyle: (theme, alignment, {forConversation = false}) => + TextStyle( + color: alignment == BubbleAlignment.left ? Colors.orange : Colors.pink, + fontSize: 14, + fontWeight: FontWeight.bold, + ), + ), +] +``` + + + +*** + +## Actions + +##### onMentionTap + +Setting a listener for mention-click events in Message Bubbles. This listener is activated when a mention is clicked, returning the corresponding user object. + + + +```dart +CometChatMessageList( + user: user, + textFormatters: [ + CometChatMentionsFormatter( + onMentionTap: (mention, mentionedUser, {message}) { + ScaffoldMessenger.of(context).showSnackBar( + SnackBar(content: Text('Tapped on ${mentionedUser.name}')), + ); + }, + messageBubbleTextStyle: (theme, alignment, {forConversation = false}) => + TextStyle( + color: alignment == BubbleAlignment.left ? Colors.orange : Colors.greenAccent, + fontSize: 14, + fontWeight: FontWeight.bold, + ), + ), + ], +) +``` + + + +*** + +## Customization + +| Property | Description | Code | +|---|---|---| +| trackingCharacter | Character that triggers mention search | `String? trackingCharacter` | +| pattern | Regex pattern to identify mentions | `RegExp? pattern` | +| messageBubbleTextStyle | Text style for message bubble | `TextStyle? messageBubbleTextStyle` | +| messageInputTextStyle | Text style for message input | `TextStyle? messageInputTextStyle` | +| onMentionTap | Callback for mention tap actions | `void Function(User)? onMentionTap` | +| groupMembersRequestBuilder | Request builder for group members | `GroupMembersRequestBuilder?` | +| usersRequestBuilder | Request builder for users | `UsersRequestBuilder?` | + +*** + +## Advanced + +### Composer Mention Text Style + + + +```dart +CometChatMessageComposer( + user: user, + textFormatters: [ + CometChatMentionsFormatter( + messageInputTextStyle: (theme) { + return const TextStyle( + color: Colors.lightBlueAccent, + fontSize: 14, + fontWeight: FontWeight.bold, + ); + }, + ), + ], +) +``` + + + +### Message Bubble Mention Text Style + + + +```dart +CometChatMessageList( + user: user, + textFormatters: [ + CometChatMentionsFormatter( + messageBubbleTextStyle: (theme, alignment, {forConversation = false}) => + TextStyle( + color: alignment == BubbleAlignment.left ? Colors.orange : Colors.greenAccent, + fontSize: 14, + fontWeight: FontWeight.bold, + ), + ), + ], +) +``` + + + +### Conversations Mention Text Style + + + +```dart +CometChatConversations( + textFormatters: [ + CometChatMentionsFormatter( + messageBubbleTextStyle: (theme, alignment, {forConversation = false}) => + const TextStyle( + color: Colors.lightBlueAccent, + fontSize: 14, + fontWeight: FontWeight.bold, + ), + ), + ], +) +``` + + + + diff --git a/ui-kit/flutter/v6/message-bubble-styling.mdx b/ui-kit/flutter/v6/message-bubble-styling.mdx new file mode 100644 index 000000000..a49c48079 --- /dev/null +++ b/ui-kit/flutter/v6/message-bubble-styling.mdx @@ -0,0 +1,411 @@ +--- +title: "Customizing Message Bubbles" +sidebarTitle: "Message Bubble Styling" +--- + +The CometChat V6 UI Kit provides `CometChatOutgoingMessageBubbleStyle` and `CometChatIncomingMessageBubbleStyle` for fine-grained control over message bubble appearance. These classes extend `ThemeExtension`, allowing customizations through global theming or explicit style objects. + +## How These Classes Help + +### 1. Targeted Customization + +Customize specific attributes of message bubbles: + +* Background color, border radius, text style +* Specialized bubbles: Audio, File, Collaborative, Poll, Deleted, Link Preview, Sticker, Call bubbles +* Reactions, timestamps, avatars, and borders + +### 2. Unified Global Theming + +Apply styles via Flutter's global theming or pass them to `CometChatMessageListStyle`: + + + +```dart +MaterialApp( + title: 'Your app', + theme: ThemeData( + extensions: [ + CometChatIncomingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + CometChatOutgoingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ], + ), + home: ..., +); +``` + + + +### 3. Ease of Integration + +Pass styles directly to `CometChatMessageList`: + + + +```dart +CometChatMessageList( + user: user, + group: group, + style: CometChatMessageListStyle( + incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle(), + outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle(), + ), +) +``` + + + +## Customizable Message Bubbles + +### Text Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + textBubbleStyle: CometChatTextBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + textBubbleStyle: CometChatTextBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + ), + ), + ], +) +``` + + + +### Image Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + imageBubbleStyle: CometChatImageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + imageBubbleStyle: CometChatImageBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + ), + ), + ], +) +``` + + + +### Video Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + videoBubbleStyle: CometChatVideoBubbleStyle( + backgroundColor: Color(0xFFF76808), + playIconColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + videoBubbleStyle: CometChatVideoBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + playIconColor: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### Audio Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + audioBubbleStyle: CometChatAudioBubbleStyle( + backgroundColor: Color(0xFFF76808), + playIconColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + audioBubbleStyle: CometChatAudioBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + downloadIconColor: Color(0xFFF76808), + audioBarColor: Color(0xFFF76808), + playIconColor: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### File Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + fileBubbleStyle: CometChatFileBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + fileBubbleStyle: CometChatFileBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + downloadIconTint: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### Sticker Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + stickerBubbleStyle: CometChatStickerBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + stickerBubbleStyle: CometChatStickerBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + ), + ), + ], +) +``` + + + +### Call Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + videoCallBubbleStyle: CometChatCallBubbleStyle( + backgroundColor: Color(0xFFF76808), + iconColor: Color(0xFFF76808), + buttonTextStyle: TextStyle(color: Colors.white), + dividerColor: Color(0xFFFBAA75), + ), + ), + CometChatIncomingMessageBubbleStyle( + videoCallBubbleStyle: CometChatCallBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + iconColor: Color(0xFFF76808), + buttonTextStyle: TextStyle(color: Color(0xFFF76808)), + ), + ), + ], +) +``` + + + +### Collaborative Whiteboard Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + collaborativeWhiteboardBubbleStyle: CometChatCollaborativeBubbleStyle( + backgroundColor: Color(0xFFF76808), + iconTint: Color(0xFFFFFFFF), + titleStyle: TextStyle(fontWeight: FontWeight.bold, color: Color(0xFFFFFFFF)), + buttonTextStyle: TextStyle(color: Color(0xFFFFFFFF)), + dividerColor: Color(0xFFFBAA75), + ), + ), + CometChatIncomingMessageBubbleStyle( + collaborativeWhiteboardBubbleStyle: CometChatCollaborativeBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + iconTint: Color(0xFFF76808), + titleStyle: TextStyle(fontWeight: FontWeight.bold), + buttonTextStyle: TextStyle(color: Color(0xFFF76808)), + ), + ), + ], +) +``` + + + +### Collaborative Document Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + collaborativeDocumentBubbleStyle: CometChatCollaborativeBubbleStyle( + backgroundColor: Color(0xFFF76808), + iconTint: Color(0xFFFFFFFF), + titleStyle: TextStyle(fontWeight: FontWeight.bold, color: Color(0xFFFFFFFF)), + buttonTextStyle: TextStyle(color: Color(0xFFFFFFFF)), + dividerColor: Color(0xFFFBAA75), + ), + ), + CometChatIncomingMessageBubbleStyle( + collaborativeDocumentBubbleStyle: CometChatCollaborativeBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + iconTint: Color(0xFFF76808), + titleStyle: TextStyle(fontWeight: FontWeight.bold), + buttonTextStyle: TextStyle(color: Color(0xFFF76808)), + ), + ), + ], +) +``` + + + +### Poll Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + pollsBubbleStyle: CometChatPollsBubbleStyle( + backgroundColor: Color(0xFFF76808), + progressBackgroundColor: Color(0xFFFBAA75), + iconColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + pollsBubbleStyle: CometChatPollsBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + progressBackgroundColor: Color(0xFFDCDCDC), + progressColor: Color(0xFFF76808), + iconColor: Colors.white, + selectedOptionColor: Color(0xFFF76808), + ), + ), + ], +) +``` + + + +### Link Preview Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + linkPreviewBubbleStyle: CometChatLinkPreviewBubbleStyle( + backgroundColor: Color(0xFFFBAA75), + ), + textBubbleStyle: CometChatTextBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + linkPreviewBubbleStyle: CometChatLinkPreviewBubbleStyle( + backgroundColor: Color(0xFFFBAA75), + ), + textBubbleStyle: CometChatTextBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + ), + ), + ], +) +``` + + + +### Action Message Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatActionBubbleStyle( + textStyle: TextStyle(color: Color(0xFFF76808)), + border: Border.all(color: Color(0xFFF76808)), + backgroundColor: Color(0xFFFEEDE1), + ), + ], +) +``` + + + +### Deleted Message Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatOutgoingMessageBubbleStyle( + deletedBubbleStyle: CometChatDeletedBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + ), + CometChatIncomingMessageBubbleStyle( + deletedBubbleStyle: CometChatDeletedBubbleStyle( + backgroundColor: Color(0xFFFEEDE1), + ), + ), + ], +) +``` + + + +### AI Assistant Bubble + + + +```dart +ThemeData( + extensions: [ + CometChatAiAssistantBubbleStyle( + backgroundColor: Colors.transparent, + textColor: const Color(0xFF141414), + ), + ], +) +``` + + diff --git a/ui-kit/flutter/v6/message-composer.mdx b/ui-kit/flutter/v6/message-composer.mdx new file mode 100644 index 000000000..ba4b9b12d --- /dev/null +++ b/ui-kit/flutter/v6/message-composer.mdx @@ -0,0 +1,445 @@ +--- +title: "Message Composer" +--- + +## Overview + +`CometChatMessageComposer` is a [Widget](/ui-kit/flutter/v6/components-overview#widget) that enables users to write and send a variety of messages, including text, image, video, and custom messages. + +Features such as **Live Reaction**, **Attachments**, **Message Editing**, **Rich Text Formatting**, **Code Blocks**, and **Inline Audio Recording** are supported. + +`CometChatMessageComposer` is comprised of the following Base Widgets: + +| Base Widgets | Description | +|---|---| +| MessageInput | Provides a basic layout for the contents, such as the TextField and buttons | +| ActionSheet | Presents a list of options in either a list or grid mode | + +In V6, the composer is powered by `MessageComposerBloc` and decomposed into focused sub-widgets. + +## Usage + +### Integration + +##### 1. Using Navigator to Launch `CometChatMessageComposer` + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatMessageComposer(user: user))); +``` + + + +##### 2. Embedding `CometChatMessageComposer` as a Widget in the build Method + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; + +class MessageComposerScreen extends StatefulWidget { + const MessageComposerScreen({super.key}); + + @override + State createState() => _MessageComposerScreenState(); +} + +class _MessageComposerScreenState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + resizeToAvoidBottomInset: false, // REQUIRED — composer handles keyboard internally + body: Column( + children: [ + Expanded(child: CometChatMessageList(user: user)), + CometChatMessageComposer(user: user), + ], + ), + ); + } +} +``` + + + +*** + +### Actions + +##### 1. OnSendButtonClick + +The `OnSendButtonClick` event gets activated when the send message button is clicked. + + + +```dart +CometChatMessageComposer( + user: user, + onSendButtonTap: (BuildContext context, BaseMessage baseMessage, PreviewMessageMode? previewMessageMode) { + // Handle send + }, +) +``` + + + +*** + +##### 2. onChange + +Handles changes in the value of text in the input field. + + + +```dart +CometChatMessageComposer( + user: user, + onChange: (String? text) { + // Handle text change + }, +) +``` + + + +*** + +##### 3. onError + +Listens for any errors that occur. + + + +```dart +CometChatMessageComposer( + user: user, + onError: (e) { + // Handle error + }, +) +``` + + + +*** + +### Filters + +`CometChatMessageComposer` widget does not have any available filters. + +*** + +### Events + +The `CometChatMessageComposer` Widget does not emit any events of its own. + +*** + +## Customization + +### Style + +##### 1. CometChatMessageComposerStyle + + + +```dart +CometChatMessageComposer( + user: user, + messageComposerStyle: CometChatMessageComposerStyle( + sendButtonIconBackgroundColor: Color(0xFFF76808), + secondaryButtonIconColor: Color(0xFFF76808), + auxiliaryButtonIconColor: Color(0xFFF76808), + ), +) +``` + + + +##### 2. MediaRecorder Style + + + +```dart +CometChatMessageComposer( + user: user, + messageComposerStyle: CometChatMessageComposerStyle( + mediaRecorderStyle: CometChatMediaRecorderStyle( + recordIndicatorBackgroundColor: Color(0xFFF44649), + recordIndicatorBorderRadius: BorderRadius.circular(20), + ), + ), +) +``` + + + +*** + +### Functionality + + + +```dart +CometChatMessageComposer( + user: user, + placeholderText: "Type a message...", + disableMentions: true, +) +``` + + + +## Message Composer Properties + +| Property | Data Type | Description | +|---|---|---| +| `user` | `User?` | Sets user for the message composer. | +| `group` | `Group?` | Sets group for the message composer. | +| `messageComposerStyle` | `CometChatMessageComposerStyle?` | Sets style for the message composer. | +| `placeholderText` | `String?` | Hint text for the input field. | +| `text` | `String?` | Initial text for the input field. | +| `onChange` | `Function(String text)?` | Callback triggered when text changes. | +| `textEditingController` | `TextEditingController?` | Controls the state of the text field. | +| `maxLine` | `int?` | Maximum number of lines allowed. | +| `disableMentions` | `bool?` | Disables mentions in the composer. | +| `disableTypingEvents` | `bool` | Disables typing events. | +| `disableSoundForMessages` | `bool` | Disables sound for sent messages. | +| `parentMessageId` | `int` | ID of the parent message (default is 0). | +| `sendButtonView` | `Widget?` | Custom send button widget. | +| `attachmentIcon` | `Widget?` | Custom attachment icon. | +| `voiceRecordingIcon` | `Widget?` | Custom voice recording icon. | +| `auxiliaryButtonView` | `ComposerWidgetBuilder?` | UI component as auxiliary button. | +| `secondaryButtonView` | `ComposerWidgetBuilder?` | UI component as secondary button. | +| `hideVoiceRecordingButton` | `bool?` | Hide the voice recording button. | +| `attachmentOptions` | `ComposerActionsBuilder?` | Provides options for file attachments. | +| `hideAttachmentButton` | `bool?` | Hide/display attachment button. | +| `hideImageAttachmentOption` | `bool?` | Hide/display image attachment option. | +| `hideVideoAttachmentOption` | `bool?` | Hide/display video attachment option. | +| `hideAudioAttachmentOption` | `bool?` | Hide/display audio attachment option. | +| `hideFileAttachmentOption` | `bool?` | Hide/display file attachment option. | +| `hidePollsOption` | `bool?` | Hide/display polls option. | +| `onSendButtonTap` | `Function(BuildContext, BaseMessage, PreviewMessageMode?)?` | Callback when send button is tapped. | +| `onError` | `OnError?` | Callback to handle errors. | +| `hideSendButton` | `bool?` | Hide/display the send button. | +| `hideStickersButton` | `bool?` | Hide/display the sticker button. | +| `sendButtonIcon` | `Widget?` | Custom send button icon. | +| `richTextConfiguration` | `RichTextConfiguration?` | Configuration for rich text formatting toolbar. See Rich Text section below. | +| `richTextToolbarView` | `Widget Function(BuildContext, TextEditingController, RichTextFormatterManager)?` | Custom rich text toolbar widget. | +| `onRichTextFormatApplied` | `void Function(RichTextFormatType)?` | Callback when a rich text format is applied. | +| `hideBottomSafeArea` | `bool` | Hide bottom safe area padding (default: `false`). | + +*** + +### Advanced + +#### TextFormatters + + + +```dart +CometChatMessageComposer( + user: user, + textFormatters: [ + CometChatMentionsFormatter( + style: CometChatMentionsStyle( + mentionSelfTextBackgroundColor: Color(0xFFF76808), + mentionTextBackgroundColor: Colors.white, + mentionTextColor: Colors.black, + mentionSelfTextColor: Colors.white, + ), + ), + ], +) +``` + + + +*** + +#### AttachmentOptions + + + +```dart +CometChatMessageComposer( + user: user, + attachmentOptions: (context, user, group, id) { + return [ + CometChatMessageComposerAction( + id: "Custom Option", + title: "Custom Option", + icon: Icon(Icons.add_box, color: Colors.black), + ), + ]; + }, +) +``` + + + +*** + +#### AuxiliaryButton Widget + +You can customize the auxiliary button area (mic, sticker, etc.) using the `auxiliaryButtonView` parameter: + + + +```dart +CometChatMessageComposer( + user: user, + auxiliaryButtonView: (context, user, group, id) { + return Row( + children: [ + IconButton( + icon: Icon(Icons.location_pin, color: Color(0xFF6852D6)), + onPressed: () { + // Handle location sharing + }, + ), + ], + ); + }, +) +``` + + + +*** + +## Rich Text Formatting + +The composer includes a WYSIWYG rich text toolbar. Configure it via `richTextConfiguration`: + +### Enable with defaults + + + +```dart +CometChatMessageComposer( + user: user, + richTextConfiguration: RichTextConfiguration(), +) +``` + + + +### Toolbar modes + +| Mode | Description | +| --- | --- | +| `RichTextToolbarMode.alwaysVisible` | Toolbar always shown (default) | +| `RichTextToolbarMode.onSelection` | Toolbar shown when text is selected | +| `RichTextToolbarMode.disabled` | Rich text formatting disabled | + + + +```dart +CometChatMessageComposer( + user: user, + richTextConfiguration: RichTextConfiguration( + toolbarMode: RichTextToolbarMode.onSelection, + ), +) +``` + + + +### Disable specific formats + + + +```dart +CometChatMessageComposer( + user: user, + richTextConfiguration: RichTextConfiguration( + enableCodeBlock: false, + enableBlockquote: false, + enableOrderedList: false, + ), +) +``` + + + +### RichTextConfiguration properties + +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `toolbarMode` | `RichTextToolbarMode` | `alwaysVisible` | How the toolbar is displayed | +| `previewMode` | `RichTextPreviewMode` | `onFormatting` | How the preview is displayed | +| `enableAutoFormatting` | `bool` | `true` | Auto-detect and format Markdown as user types | +| `enableBold` | `bool` | `true` | Bold (`**text**`) | +| `enableItalic` | `bool` | `true` | Italic (`_text_`) | +| `enableUnderline` | `bool` | `true` | Underline (`text`) | +| `enableStrikethrough` | `bool` | `true` | Strikethrough (`~~text~~`) | +| `enableInlineCode` | `bool` | `true` | Inline code (`` `code` ``) | +| `enableCodeBlock` | `bool` | `true` | Code block (` ```code``` `) | +| `enableLinks` | `bool` | `true` | Links (`[text](url)`) | +| `enableBulletList` | `bool` | `true` | Bullet list (`- item`) | +| `enableOrderedList` | `bool` | `true` | Ordered list (`1. item`) | +| `enableBlockquote` | `bool` | `true` | Blockquote (`> text`) | + +### Custom toolbar view + + + +```dart +CometChatMessageComposer( + user: user, + richTextConfiguration: RichTextConfiguration(), + richTextToolbarView: (context, controller, manager) { + return Row( + children: [ + IconButton( + icon: Icon(Icons.format_bold), + onPressed: () => manager.applyFormat(RichTextFormatType.bold), + ), + IconButton( + icon: Icon(Icons.format_italic), + onPressed: () => manager.applyFormat(RichTextFormatType.italic), + ), + ], + ); + }, +) +``` + + + +*** + +## V6 Architecture + +### Sub-Widget Decomposition + +| Widget | Purpose | +|---|---| +| `AttachmentOptionsOverlay` | Attachment picker overlay | +| `MessageComposerAuxiliaryButtons` | Auxiliary button area | +| `MessageComposerSecondaryButtons` | Secondary button area | +| `MessageComposerSendButton` | Send button | +| `MessageComposerSuggestionList` | Suggestion/mention list | +| `ComposerAttachmentUtils` | Attachment utilities | + +### BLoC Architecture + +| Component | Description | +|---|---| +| `MessageComposerBloc` | Manages composer state | +| `MessageComposerEvent` | Events: `SendTextMessage`, `SendMediaMessage`, `EditTextMessage`, `StartTyping`, `EndTyping`, etc. | +| `MessageComposerState` | Composer state | + +### Use Cases + +| Use Case | Description | +|---|---| +| `SendTextMessageUseCase` | Sends text messages | +| `SendMediaMessageUseCase` | Sends media messages | +| `SendCustomMessageUseCase` | Sends custom messages | +| `EditMessageUseCase` | Edits messages | +| `TypingUseCases` | Start/end typing indicators | +| `GetLoggedInUserUseCase` | Gets the logged-in user | diff --git a/ui-kit/flutter/v6/message-header.mdx b/ui-kit/flutter/v6/message-header.mdx new file mode 100644 index 000000000..347c14732 --- /dev/null +++ b/ui-kit/flutter/v6/message-header.mdx @@ -0,0 +1,364 @@ +--- +title: "Message Header" +description: "Toolbar displaying user/group info, typing indicators, online status, and navigation controls." +--- + +`CometChatMessageHeader` renders the header of a chat conversation showing user/group avatar, name, online/offline status, typing indicators, back navigation, and action buttons (call buttons, menu). + + + + + +--- + +## Where It Fits + +`CometChatMessageHeader` is a toolbar component. It sits at the top of a chat screen above `CometChatMessageList` and `CometChatMessageComposer`. It automatically shows typing indicators and user presence in real-time. + + + +```dart +Scaffold( + body: Column( + children: [ + CometChatMessageHeader(user: user), + Expanded(child: CometChatMessageList(user: user)), + CometChatMessageComposer(user: user), + ], + ), +) +``` + + + +--- + +## Quick Start + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; + +class ChatScreen extends StatelessWidget { + final User user; + const ChatScreen({super.key, required this.user}); + + @override + Widget build(BuildContext context) { + return Scaffold( + appBar: PreferredSize( + preferredSize: const Size.fromHeight(60), + child: CometChatMessageHeader(user: user), + ), + body: Column( + children: [ + Expanded(child: CometChatMessageList(user: user)), + CometChatMessageComposer(user: user), + ], + ), + ); + } +} +``` + + + +For group chats, pass a `Group` object instead: + + + +```dart +CometChatMessageHeader(group: group) +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and a valid `User` or `Group` object. + +--- + +## Actions and Events + +### Callback Methods + +#### `onBack` + +Fires when the user presses the back button. + + + +```dart +CometChatMessageHeader( + user: user, + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatMessageHeader( + user: user, + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +|---|---| +| `onUserOnline` / `onUserOffline` | Updates online/offline status and last seen | +| `onTypingStarted` / `onTypingEnded` | Shows/hides typing indicator in subtitle | +| `onGroupMemberJoined` / `onGroupMemberLeft` | Updates group member count | +| `onGroupMemberKicked` / `onGroupMemberBanned` | Updates group member count | +| `onMemberAddedToGroup` | Updates group member count | +| `ccOwnershipChanged` | Updates group owner info | +| `onUserBlocked` / `onUserUnblocked` | Updates user blocked state | +| Connection reconnected | Refreshes user/group data | + +--- + +## Functionality + +| Property | Type | Default | Description | +|---|---|---|---| +| `user` | `User?` | `null` | User object for 1:1 chat header | +| `group` | `Group?` | `null` | Group object for group chat header | +| `showBackButton` | `bool?` | `true` | Toggle back button visibility | +| `backButton` | `Widget?` | `null` | Custom back button widget | +| `appBarOptions` | `List?` | `null` | Additional widgets in the app bar (e.g., call buttons, menu) | +| `hideUserStatus` | `bool?` | `false` | Hide online/offline status for users | +| `disableTypingIndicator` | `bool?` | `false` | Disable typing indicator display | + +--- + +## Custom View Slots + +### Subtitle View + +Replace the default subtitle (online status / typing indicator / member count). + + + +```dart +CometChatMessageHeader( + user: user, + subtitleView: (user, group) { + if (user != null) { + return Text( + user.status == "online" ? "Active now" : "Last seen recently", + style: TextStyle(color: Color(0xFF727272), fontSize: 12), + ); + } + if (group != null) { + return Text( + "${group.membersCount} members", + style: TextStyle(color: Color(0xFF727272), fontSize: 12), + ); + } + return null; + }, +) +``` + + + +### Leading View + +Replace the avatar / left section. + + + +```dart +CometChatMessageHeader( + user: user, + leadingView: (user, group) { + return CircleAvatar( + backgroundImage: NetworkImage(user?.avatar ?? ""), + child: user?.avatar == null ? Text(user?.name?[0] ?? "") : null, + ); + }, +) +``` + + + +### Title View + +Replace the name / title text. + + + +```dart +CometChatMessageHeader( + user: user, + titleView: (user, group) { + return Text( + user?.name ?? group?.name ?? "", + style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16), + ); + }, +) +``` + + + +### Trailing View + +Replace the right section (call buttons, menu, etc.). + + + +```dart +CometChatMessageHeader( + user: user, + trailingView: (user, group) { + return Row( + mainAxisSize: MainAxisSize.min, + children: [ + IconButton(icon: Icon(Icons.call), onPressed: () {}), + IconButton(icon: Icon(Icons.videocam), onPressed: () {}), + IconButton(icon: Icon(Icons.info_outline), onPressed: () {}), + ], + ); + }, +) +``` + + + +--- + +## Common Patterns + +### Header with info button for groups + + + +```dart +CometChatMessageHeader( + group: group, + trailingView: (user, group) { + return IconButton( + icon: Icon(Icons.info_outline), + onPressed: () { + Navigator.push(context, MaterialPageRoute( + builder: (context) => GroupInfoScreen(group: group!), + )); + }, + ); + }, +) +``` + + + +### Hide back button (embedded in tab layout) + + + +```dart +CometChatMessageHeader( + user: user, + showBackButton: false, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +Provide a custom `MessageHeaderBloc`: + + + +```dart +CometChatMessageHeader( + user: user, + messageHeaderBloc: CustomMessageHeaderBloc(), +) +``` + + + +### Public BLoC Methods + +| Method | Returns | Description | +|---|---|---| +| `getTypingNotifier()` | `ValueNotifier` | Typing indicator notifier for isolated rebuilds | + +--- + +## Style + + + +```dart +CometChatMessageHeader( + user: user, + messageHeaderStyle: CometChatMessageHeaderStyle( + backgroundColor: Colors.white, + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + ), + statusIndicatorStyle: CometChatStatusIndicatorStyle(), + typingIndicatorStyle: CometChatTypingIndicatorStyle(), + ), +) +``` + + + + + + + +### Style Properties + +| Property | Description | +|---|---| +| `backgroundColor` | Header background color | +| `avatarStyle` | Avatar appearance | +| `statusIndicatorStyle` | Online/offline indicator | +| `typingIndicatorStyle` | Typing indicator text style | + +See [Component Styling](/ui-kit/flutter/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + Display messages in a conversation + + + Compose and send messages + + + Add voice and video call buttons + + + Detailed styling reference + + diff --git a/ui-kit/flutter/v6/message-list.mdx b/ui-kit/flutter/v6/message-list.mdx new file mode 100644 index 000000000..1c587b677 --- /dev/null +++ b/ui-kit/flutter/v6/message-list.mdx @@ -0,0 +1,546 @@ +--- +title: "Message List" +description: "Scrollable list of messages for a conversation with real-time updates, reactions, threaded replies, and message actions." +--- + +`CometChatMessageList` renders a scrollable list of messages for a conversation with real-time updates for new messages, edits, deletions, reactions, and threaded replies. + +--- + +## Where It Fits + +`CometChatMessageList` is a message display component. It requires either a `User` or `Group` object to fetch and render messages. Wire it with `CometChatMessageHeader` and `CometChatMessageComposer` to build a complete messaging layout. + + + +```dart +CometChatMessageList( + user: user, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatMessageList(user: user))); +``` + + + +Embedding as a widget: + + + +```dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatMessageList( + user: user, // or group: group + ), + ), + ); +} +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + + +Simply adding the `MessageList` component to the layout will only display the loading indicator. You must supply a `User` or `Group` object to fetch messages. + + +--- + +## Filtering + +Pass a `MessagesRequestBuilder` to control what loads: + + + +```dart +CometChatMessageList( + user: user, + messagesRequestBuilder: MessagesRequestBuilder() + ..uid = user.uid + ..searchKeyword = "hello" + ..limit = 30, +) +``` + + + + +The following parameters in `MessagesRequestBuilder` will always be altered inside the message list: UID, GUID, types, categories. + + +--- + +## Actions and Events + +### Callback Methods + +#### `onThreadRepliesClick` + +Fires when a user taps a threaded message bubble. + + + +```dart +CometChatMessageList( + user: user, + onThreadRepliesClick: (message, context, {template}) { + // Navigate to thread view + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatMessageList( + user: user, + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + +```dart +CometChatMessageList( + user: user, + onLoad: (messages) { + debugPrint("Loaded ${messages.length}"); + }, +) +``` + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + +```dart +CometChatMessageList( + user: user, + onEmpty: () { + debugPrint("No messages"); + }, +) +``` + + + +#### `onReactionClick` + +Fires when a reaction pill is tapped. + + + +```dart +CometChatMessageList( + user: user, + onReactionClick: (emoji, message) { + // Handle reaction click + }, +) +``` + + + +#### `onReactionLongPress` + +Fires when a reaction pill is long-pressed. + + + +```dart +CometChatMessageList( + user: user, + onReactionLongPress: (emoji, message) { + // Handle reaction long press + }, +) +``` + + + +### SDK Events (Real-Time, Automatic) + +The component listens to SDK message events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +| --- | --- | +| `onTextMessageReceived` / `onMediaMessageReceived` / `onCustomMessageReceived` | Inserts new message with animation | +| `onMessageEdited` | Updates message in-place | +| `onMessageDeleted` | Removes or marks message as deleted | +| `onMessagesDelivered` / `onMessagesRead` | Updates receipt status via ValueNotifier | +| `onTypingStarted` / `onTypingEnded` | Updates typing indicator | +| `onMessageReactionAdded` / `onMessageReactionRemoved` | Updates reaction counts | +| Connection reconnected | Triggers silent sync to fetch missed messages | + +--- + +## Functionality + +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `user` | `User?` | required* | User for 1-on-1 conversation | +| `group` | `Group?` | required* | Group for group conversation | +| `parentMessageId` | `int?` | `null` | Parent message ID for thread replies | +| `alignment` | `ChatAlignment` | `standard` | Chat alignment setting | +| `hideDeletedMessages` | `bool` | `false` | Hide deleted messages entirely | +| `disableReceipts` | `bool` | `false` | Disable read/delivery receipts | +| `disableSoundForMessages` | `bool` | `false` | Disable message sounds | +| `hideReplies` | `bool` | `true` | Hide thread replies in main conversation | +| `hideGroupActionMessages` | `bool?` | `false` | Hide group action messages | +| `hideTimestamp` | `bool?` | `null` | Toggle timestamp visibility | +| `hideDateSeparator` | `bool?` | `false` | Hide date separators | +| `hideStickyDate` | `bool?` | `false` | Hide floating sticky date header | +| `avatarVisibility` | `bool?` | `true` | Toggle avatar visibility | +| `receiptsVisibility` | `bool?` | `true` | Toggle read receipts | +| `disableReactions` | `bool?` | `false` | Toggle reactions | +| `enableSwipeToReply` | `bool` | `true` | Enable swipe-to-reply gesture | +| `startFromUnreadMessages` | `bool` | `false` | Scroll to first unread on open | +| `showMarkAsUnreadOption` | `bool` | `false` | Show "Mark as Unread" in long-press options | +| `goToMessageId` | `int?` | `null` | Scroll to a specific message after load | + +\* One of `user` or `group` is required. + +--- + +## Custom View Slots + +### Header View + +Custom view displayed at the top of the message list. + + + +```dart +CometChatMessageList( + user: user, + headerView: (context, {user, group, parentMessageId}) { + return Container( + padding: EdgeInsets.all(8), + child: Text("Pinned Messages"), + ); + }, +) +``` + + + +### Footer View + +Custom view displayed at the bottom of the message list. + + + +```dart +CometChatMessageList( + user: user, + footerView: (context, {user, group, parentMessageId}) { + return Container( + padding: EdgeInsets.all(8), + child: Text("End of messages"), + ); + }, +) +``` + + + +### State Views + + + +```dart +CometChatMessageList( + user: user, + emptyStateView: (context) => Center(child: Text("No messages yet")), + errorStateView: (context) => Center(child: Text("Something went wrong")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), + emptyChatGreetingView: (context) => Center(child: Text("Say hello!")), +) +``` + + + +### Text Formatters (Mentions) + + + +```dart +CometChatMessageList( + user: user, + textFormatters: [ + CometChatMentionsFormatter(), + ], +) +``` + + + +### Message Templates + +Override or extend message bubble rendering: + + + +```dart +// Replace all templates +CometChatMessageList( + user: user, + templates: getCustomTemplates(), +) + +// Add/override specific templates (merged with defaults) +CometChatMessageList( + user: user, + addTemplate: [ + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + contentView: (message, context, alignment, {additionalConfigurations}) { + return Text((message as TextMessage).text, + style: TextStyle(color: Colors.red)); + }, + ), + ], +) +``` + + + +See [Message Template](/ui-kit/flutter/v6/message-template) for the full template structure. + +--- + +## Message Option Visibility + +| Property | Default | Description | +| --- | --- | --- | +| `hideCopyMessageOption` | `false` | Hide "Copy Message" | +| `hideDeleteMessageOption` | `false` | Hide "Delete Message" | +| `hideEditMessageOption` | `false` | Hide "Edit Message" | +| `hideMessageInfoOption` | `false` | Hide "Message Info" | +| `hideMessagePrivatelyOption` | `false` | Hide "Message Privately" | +| `hideReactionOption` | `false` | Hide "Reaction" | +| `hideReplyInThreadOption` | `false` | Hide "Reply in Thread" | +| `hideTranslateMessageOption` | `false` | Hide "Translate Message" | +| `hideShareMessageOption` | `false` | Hide "Share Message" | +| `hideModerationView` | `null` | Hide moderation view | + +--- + +## Common Patterns + +### Thread replies view + + + +```dart +CometChatMessageList( + user: user, + parentMessageId: parentMessage.id, +) +``` + + + +### Jump to a specific message + + + +```dart +CometChatMessageList( + user: user, + goToMessageId: 12345, +) +``` + + + +### Start from unread messages + + + +```dart +CometChatMessageList( + user: user, + startFromUnreadMessages: true, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +Provide a custom `MessageListBloc` to override behavior: + + + +```dart +CometChatMessageList( + user: user, + messageListBloc: CustomMessageListBloc(user: user), +) +``` + + + +### Extending MessageListBloc + +`MessageListBloc` uses the `ListBase` mixin with override hooks: + + + +```dart +class CustomMessageListBloc extends MessageListBloc { + CustomMessageListBloc({required User user}) : super(user: user); + + @override + void onItemAdded(BaseMessage item, List updatedList) { + // Custom logic when a message is added + super.onItemAdded(item, updatedList); + } +} +``` + + + +For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/ui-kit/flutter/v6/customization-bloc-data#listbase-hooks). + +### Public BLoC Events + +| Event | Description | +| --- | --- | +| `LoadMessages(conversationWith, conversationType)` | Load initial messages | +| `LoadOlderMessages()` | Load older messages (scroll up) | +| `LoadNewerMessages()` | Load newer messages (scroll down) | +| `RefreshMessages()` | Refresh from the latest | +| `SyncMessages()` | Silently sync missed messages | +| `JumpToMessage(messageId)` | Jump to a specific message | +| `AddReaction(message, reaction)` | Add a reaction | +| `RemoveReaction(message, reaction)` | Remove a reaction | +| `MarkMessageAsRead(message)` | Mark a message as read | +| `MarkMessageAsUnread(...)` | Mark a message as unread | +| `LoadFromUnread(conversationWith, conversationType)` | Load from first unread message | + +### Public BLoC Methods + +#### O(1) Lookup Methods + +| Method | Returns | Description | +| --- | --- | --- | +| `findMessageIndex(messageId)` | `int?` | Find message index by ID | +| `findMessageIndexByMuid(muid)` | `int?` | Find message index by muid (pending messages) | +| `findMessage(messageId)` | `BaseMessage?` | Get message by ID | +| `findMessageByMuid(muid)` | `BaseMessage?` | Get message by muid | + +#### ValueNotifier Accessors (Isolated Rebuilds) + +| Method | Returns | Description | +| --- | --- | --- | +| `getReceiptNotifier(messageId)` | `ValueNotifier` | Per-message receipt status notifier | +| `getReceiptNotifierForMessage(message)` | `ValueNotifier` | Receipt notifier handling both ID and muid | +| `getTypingNotifier(conversationId)` | `ValueNotifier>` | Per-conversation typing notifier | +| `getThreadReplyCountNotifier(parentMessageId)` | `ValueNotifier` | Per-message thread reply count notifier | + +#### MessageReceiptStatus Enum + +| Value | Description | +| --- | --- | +| `sending` | Message is being sent (id = 0) | +| `sent` | Message has been sent to server | +| `delivered` | Message has been delivered to recipient | +| `read` | Message has been read by recipient | +| `error` | Message failed to send | + +### Operations Stream + +The BLoC exposes an `operationsStream` consumed by `CometChatAnimatedMessageList` for smooth animations: + +| Operation | Description | +| --- | --- | +| `MessageOperation.insert(message, index)` | Insert a single message | +| `MessageOperation.insertAll(messages, index)` | Insert a batch of messages | +| `MessageOperation.update(oldMessage, newMessage, index)` | Replace a message in-place | +| `MessageOperation.remove(message, index)` | Remove a message | +| `MessageOperation.set(messages)` | Replace the entire list | + +--- + +## Style + + + +```dart +CometChatMessageList( + user: user, + style: CometChatMessageListStyle( + backgroundColor: Color(0xFFFEEDE1), + outgoingMessageBubbleStyle: CometChatOutgoingMessageBubbleStyle( + backgroundColor: Color(0xFFF76808), + ), + incomingMessageBubbleStyle: CometChatIncomingMessageBubbleStyle( + backgroundColor: Colors.white, + ), + ), +) +``` + + + +See [Component Styling](/ui-kit/flutter/v6/component-styling) and [Message Bubble Styling](/ui-kit/flutter/v6/message-bubble-styling) for the full reference. + +--- + +## Next Steps + + + + Display user/group info in the app bar + + + Rich input for sending messages + + + Customize message bubble structure + + + Detailed styling reference + + \ No newline at end of file diff --git a/ui-kit/flutter/v6/message-template.mdx b/ui-kit/flutter/v6/message-template.mdx new file mode 100644 index 000000000..20b51e7af --- /dev/null +++ b/ui-kit/flutter/v6/message-template.mdx @@ -0,0 +1,251 @@ +--- +title: "Message Template" +--- + +## Overview + +A `CometChatMessageTemplate` provides the capability to define and customize both the structure and behavior of message bubbles. It acts as a blueprint for creating message bubble widgets, allowing you to manage appearance and interactions consistently. + +### Structure + +The MessageBubble structure can be broken down into: + +1. Leading widget — Sender's avatar +2. Header widget — Sender's name (useful in group chats) +3. Content widget — Message content (text, images, videos, etc.) +4. Bottom widget — Additional elements like link previews or "load more" buttons +5. Footer widget — Timestamp and delivery/read status + +### Properties + +| Property | Description | +|---|---| +| `type` | Maps the template to a CometChat message type | +| `category` | Sets the message category | +| `headerView` | Custom header widget for the bubble | +| `contentView` | Custom content widget for the bubble | +| `footerView` | Custom footer widget (timestamp, receipts) | +| `bottomView` | Custom bottom widget (link previews, etc.) | +| `bubbleView` | Complete custom bubble widget | +| `options` | List of actions on long press | + +## Customization + +### Header Widget + + + +```dart +CometChatMessageList( + group: group, + templates: [ + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + headerView: (BaseMessage baseMessage, BuildContext buildContext, BubbleAlignment alignment) { + return Text( + "${baseMessage.sender?.name} • 🗓️ In meeting", + style: TextStyle( + color: Color(0xFF6852D6), + fontSize: 14.4, + fontWeight: FontWeight.w500, + ), + ); + }, + ), + ], +) +``` + + + +*** + +### Content Widget + + + +```dart +CometChatMessageList( + group: group, + templates: [ + CometChatMessageTemplate( + type: "image", + category: "message", + contentView: (message, context, alignment, {AdditionalConfigurations? additionalConfigurations}) { + if (message is! MediaMessage) return const SizedBox(); + return Wrap( + direction: Axis.vertical, + crossAxisAlignment: WrapCrossAlignment.center, + children: [ + CometChatImageBubble( + imageUrl: message.attachment?.fileUrl, + metadata: message.metadata, + key: UniqueKey(), + ), + TextButton( + onPressed: () { + // Navigate to purchase screen + }, + child: Text("Buy Now"), + ), + ], + ); + }, + ), + ], +) +``` + + + +*** + +### Bottom Widget + + + +```dart +CometChatMessageList( + group: group, + templates: [ + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + bottomView: (BaseMessage baseMessage, BuildContext buildContext, BubbleAlignment alignment) { + return Container( + decoration: BoxDecoration( + color: Color(0xFFF44649).withOpacity(.2), + borderRadius: BorderRadius.circular(12), + ), + child: Row( + children: [ + Icon(Icons.warning, color: Color(0xFFF44649), size: 12), + Text( + "According to guidelines you cannot share contact", + style: TextStyle(color: Color(0xFFF44649), fontSize: 12), + ), + ], + ), + ); + }, + ), + ], +) +``` + + + +*** + +### Footer Widget + + + +```dart +CometChatMessageList( + group: group, + templates: [ + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + statusInfoView: (baseMessage, context, alignment) { + return const SizedBox(height: 11); + }, + footerView: (baseMessage, context, alignment, {additionalConfigurations}) { + // Custom footer with time and receipt + return Row( + mainAxisAlignment: MainAxisAlignment.end, + children: [ + CometChatDate(date: baseMessage.sentAt!, pattern: DateTimePattern.timeFormat), + ], + ); + }, + ), + ], +) +``` + + + +*** + +### Options List + + + +```dart +CometChatMessageList( + group: group, + templates: [ + CometChatMessageTemplate( + type: MessageTypeConstants.text, + category: MessageCategoryConstants.message, + options: (loggedInUser, messageObject, context, group, additionalConfigurations) { + final existingOptions = CometChatUIKit.getDataSource() + .getTextMessageOptions(loggedInUser, messageObject, context, group, additionalConfigurations); + return [ + CometChatMessageOption( + id: "refresh", + title: "Refresh", + icon: Icon(Icons.refresh, color: Color(0xFF6852D6), size: 24), + ), + ...existingOptions, + ]; + }, + ), + ], +) +``` + + + +*** + +## New Templates + +Create entirely new templates for custom message types: + + + +```dart +CometChatMessageList( + user: user, + messagesRequestBuilder: MessagesRequestBuilder() + ..limit = 30 + ..types = [...CometChatUIKit.getDataSource().getAllMessageTypes(), "contact"] + ..categories = CometChatUIKit.getDataSource().getAllMessageCategories(), + templates: [ + CometChatMessageTemplate( + type: "contact", + category: MessageCategoryConstants.custom, + contentView: (baseMessage, context, alignment, {additionalConfigurations}) { + return Padding( + padding: const EdgeInsets.fromLTRB(8, 8, 8, 0), + child: Row( + children: [ + CircleAvatar( + backgroundColor: Color(0xFFEDEAFA), + child: Icon(Icons.person, color: Colors.white), + ), + SizedBox(width: 8), + Text("Contact Name", + style: TextStyle( + color: alignment == BubbleAlignment.right ? Colors.white : Colors.black, + fontSize: 14, + ), + ), + ], + ), + ); + }, + ), + ], +) +``` + + + + +In V6, `CometChatUIKit.getDataSource()` is replaced by `MessageTemplateUtils` for accessing data source methods. Use the appropriate service locator to get message options and templates. + diff --git a/ui-kit/flutter/v6/methods.mdx b/ui-kit/flutter/v6/methods.mdx new file mode 100644 index 000000000..dd7cf0929 --- /dev/null +++ b/ui-kit/flutter/v6/methods.mdx @@ -0,0 +1,194 @@ +--- +title: "Methods" +--- + +## Overview + +The UI Kit's core function is to extend the Chat SDK, translating the raw data and functionality provided by the underlying methods into visually appealing and easy-to-use UI components. + +The CometChat UI Kit has encapsulated the critical Chat SDK methods within its wrapper to efficiently manage internal eventing. This layer of abstraction simplifies interaction with the underlying CometChat SDK. + +You can access the methods using the `CometChatUIKit` class. This class provides access to all the public methods exposed by the CometChat UI Kit. + +## Init + +As a developer, you need to invoke this method every time before you use any other methods provided by the UI Kit. + +The `UIKitSettings` is an important parameter of the `init()` function. It functions as a base settings object, housing properties such as `appId`, `region`, and `authKey`. + +| Method | Type | Description | +|---|---|---| +| appId | String | Sets the unique ID for the app, available on dashboard | +| region | String | Sets the region for the app ('us' or 'eu' or 'in') | +| authKey | String | Sets the auth key for the app, available on dashboard | +| subscriptionType | String | Sets subscription type for tracking the presence of all users | +| roles | String | Sets subscription type for tracking the presence of users with specified roles | +| autoEstablishSocketConnection | Boolean | Configures if web socket connections will be established automatically on app initialization or be done manually, set to true by default | + +> **V6 Note:** The `extensions` and `aiFeature` parameters from V5 have been removed. Extensions are built-in and handled automatically by `MessageTemplateUtils`. No registration is needed. + +```dart +UIKitSettings uiKitSettings = (UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..autoEstablishSocketConnection = true + ..region = "your_region" + ..appId = "your_appID" + ..authKey = "your_authKey" +).build(); + +CometChatUIKit.init( + uiKitSettings: uiKitSettings, + onSuccess: (successMessage) async { + // Ready to use + }, + onError: (error) { + // Handle error + }, +); +``` + +## Login using Auth Key + +Only the UID of a user is needed to log in. This simple authentication procedure is useful when you are creating a POC or if you are in the development phase. For production apps, we suggest you use AuthToken instead of Auth Key. + +```dart +CometChatUIKit.login(uid, onSuccess: (user) { + // Logged in successfully +}, onError: (e) { + // Handle error +}); +``` + +## Login using Auth Token + +This advanced authentication procedure does not use the Auth Key directly in your client code thus ensuring safety. + +1. Create a User via the CometChat API when the user signs up in your app. +2. Create an Auth Token via the CometChat API for the new user and save the token in your database. +3. Load the Auth Token in your client and pass it to the `loginWithAuthToken()` method. + +```dart +CometChatUIKit.loginWithAuthToken("authToken", onSuccess: (user) { + // Logged in successfully +}, onError: (e) { + // Handle error +}); +``` + +## Logout + +Before a new user logs in, it is crucial to clean session data to avoid potential conflicts. This can be achieved by invoking the `.logout()` function. + +```dart +CometChatUIKit.logout(onSuccess: (s) { + // Logged out successfully +}, onError: (e) { + // Handle error +}); +``` + +## Create User + +You can dynamically create users on CometChat using the `.createUser()` function. + +```dart +CometChat.createUser(userObject, 'authKey', onSuccess: (user) { + // User created +}, onError: (e) { + // Handle error +}); +``` + +## Base Message + +### Text Message + +Send a text message to a single user or a group using the `sendTextMessage()` function. + +```dart +CometChatUIKit.sendTextMessage(textMessageObject, onSuccess: (msg) { + // Message sent +}, onError: (e) { + // Handle error +}); +``` + +### Media Message + +Send a media message (image, video, audio, file) using the `sendMediaMessage()` function. + +```dart +CometChatUIKit.sendMediaMessage(mediaMessageObject, onSuccess: (msg) { + // Message sent +}, onError: (e) { + // Handle error +}); +``` + +### Custom Message + +Send a custom message using the `sendCustomMessage()` function. + +```dart +CometChatUIKit.sendCustomMessage(customMessageObject, onSuccess: (msg) { + // Message sent +}, onError: (e) { + // Handle error +}); +``` + +## Interactive Message + +### Form Message + +```dart +CometChatUIKit.sendFormMessage(formMessageObject, onSuccess: (msg) { + // Form message sent +}, onError: (e) { + // Handle error +}); +``` + +### Card Message + +```dart +CometChatUIKit.sendCardMessage(cardMessageObject, onSuccess: (msg) { + // Card message sent +}, onError: (e) { + // Handle error +}); +``` + +### Scheduler Message + +```dart +CometChatUIKit.sendSchedulerMessage(schedulerMessageObject, onSuccess: (msg) { + // Scheduler message sent +}, onError: (e) { + // Handle error +}); +``` + +### Custom Interactive Message + +```dart +CometChatUIKit.sendCustomInteractiveMessage(interactiveMessageObject, onSuccess: (msg) { + // Interactive message sent +}, onError: (e) { + // Handle error +}); +``` + +## DateFormatter + +By providing a custom implementation of the `DateTimeFormatterCallback`, you can globally configure how time and date values are displayed across all UI components. + +```dart +UIKitSettings uiKitSettings = (UIKitSettingsBuilder() + ..subscriptionType = CometChatSubscriptionType.allUsers + ..region = CometChatConfig.region + ..appId = CometChatConfig.appId + ..authKey = CometChatConfig.authKey + ..dateTimeFormatterCallback = DateFormatter() +).build(); +``` diff --git a/ui-kit/flutter/v6/multi-tab-chat-ui-guide.mdx b/ui-kit/flutter/v6/multi-tab-chat-ui-guide.mdx new file mode 100644 index 000000000..b9a27b738 --- /dev/null +++ b/ui-kit/flutter/v6/multi-tab-chat-ui-guide.mdx @@ -0,0 +1,120 @@ +--- +title: "Multi Tab Chat UI Guide" +--- + +This guide helps you create a multi-tab chat user interface using the CometChat V6 UIKit in Flutter. The final UI consists of three tabs: Conversations, Users, and Groups. + +##### Create the Multi-Tab Chat UI: + +Update your `lib/multi_tab_chat_ui.dart` file with the following code: + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; + +class MultiTabUIGuideExample extends StatefulWidget { + const MultiTabUIGuideExample({super.key}); + + @override + State createState() => _MultiTabUIGuideExampleState(); +} + +class _MultiTabUIGuideExampleState extends State { + + void _navigateToMessages(BuildContext context, {User? user, Group? group}) { + Navigator.push( + context, + MaterialPageRoute( + builder: (context) => Scaffold( + appBar: CometChatMessageHeader( + user: user, + group: group, + ), + body: SafeArea( + child: Column( + children: [ + Expanded( + child: CometChatMessageList( + user: user, + group: group, + ), + ), + CometChatMessageComposer( + user: user, + group: group, + ), + ], + ), + ), + ), + ), + ); + } + + @override + Widget build(BuildContext context) { + return DefaultTabController( + length: 3, + child: Scaffold( + appBar: AppBar( + title: const Text('Multi Tab UI Guide'), + backgroundColor: Colors.white, + leading: null, + automaticallyImplyLeading: false, + bottom: const TabBar( + tabs: [ + Tab(icon: Icon(Icons.chat), text: 'Conversation'), + Tab(icon: Icon(Icons.person), text: 'Users'), + Tab(icon: Icon(Icons.group), text: 'Groups'), + ], + ), + ), + body: TabBarView( + children: [ + CometChatConversations( + hideAppbar: true, + onItemTap: (conversation) { + _navigateToMessages( + context, + user: conversation.conversationWith is User + ? conversation.conversationWith as User + : null, + group: conversation.conversationWith is Group + ? conversation.conversationWith as Group + : null, + ); + }, + ), + CometChatUsers( + hideAppbar: true, + hideSearch: true, + onItemTap: (user) { + _navigateToMessages(context, user: user); + }, + ), + CometChatGroups( + hideAppbar: true, + hideSearch: true, + onItemTap: (group) { + _navigateToMessages(context, group: group); + }, + ), + ], + ), + ), + ); + } +} +``` + + + +## Key V6 Differences + +| Aspect | V5 | V6 | +|---|---|---| +| Composite widgets | `CometChatConversationsWithMessages`, `CometChatUsersWithMessages`, `CometChatGroupsWithMessages` | Not available — compose manually | +| Navigation to messages | Handled internally by composite widgets | You handle navigation and compose `MessageHeader` + `MessageList` + `MessageComposer` | +| State management | GetX | BLoC | diff --git a/ui-kit/flutter/v6/outgoing-call.mdx b/ui-kit/flutter/v6/outgoing-call.mdx new file mode 100644 index 000000000..55f369bf7 --- /dev/null +++ b/ui-kit/flutter/v6/outgoing-call.mdx @@ -0,0 +1,352 @@ +--- +title: "Outgoing Call" +description: "Full-screen view displaying recipient information and call status during an outgoing call, with automatic transition to the ongoing call screen." +--- + +`CometChatOutgoingCall` manages the outgoing call process. It displays recipient information (avatar, name) and call status, and automatically transitions to the ongoing call screen when the receiver accepts. + + + + + +--- + +## Where It Fits + +`CometChatOutgoingCall` is typically launched automatically by `CometChatCallButtons` when a call is initiated. It can also be launched manually for custom call flows. + +--- + +## Quick Start + +### Automatic (via CallButtons) + +When using `CometChatCallButtons`, the outgoing call screen is launched automatically when the user taps a call button. No manual integration needed. + +### Manual Launch + +For custom call flows: + + + +```dart +Navigator.push(context, MaterialPageRoute( + builder: (context) => CometChatOutgoingCall( + user: user, + call: callObject, + ), +)); +``` + + + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart'; +import 'package:flutter/material.dart'; + +class OutgoingCallExample extends StatefulWidget { + const OutgoingCallExample({super.key}); + + @override + State createState() => _OutgoingCallExampleState(); +} + +class _OutgoingCallExampleState extends State { + @override + Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatOutgoingCall( + user: user, + call: callObject, + ), + ), + ); + } +} +``` + + + +Prerequisites: CometChat SDK initialized, `enableCalls = true` set in UIKitSettings. See [Call Features](/ui-kit/flutter/call-features) for setup. + +--- + +## Actions and Events + +### Callback Methods + +#### `onCancelled` + +Fires when the user cancels the outgoing call. Override to customize cancel behavior. + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + onCancelled: (BuildContext context, Call call) { + // Custom cancel logic + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +### Global Events + +The component emits events via `CometChatCallEvents`: + +| Event | Description | +|---|---| +| `ccCallAccepted` | Triggers when the outgoing call is accepted | +| `ccCallRejected` | Triggers when the outgoing call is rejected | + + + +```dart +class _YourScreenState extends State with CometChatCallEventListener { + @override + void initState() { + super.initState(); + CometChatCallEvents.addCallEventsListener("unique_listener_ID", this); + } + + @override + void dispose() { + super.dispose(); + CometChatCallEvents.removeCallEventsListener("unique_listener_ID"); + } + + @override + void ccCallAccepted(Call call) { + debugPrint("Call accepted: ${call.sessionId}"); + } + + @override + void ccCallRejected(Call call) { + debugPrint("Call rejected: ${call.sessionId}"); + } + + @override + Widget build(BuildContext context) { + return const Placeholder(); + } +} +``` + + + +--- + +## Functionality + +| Property | Type | Default | Description | +|---|---|---|---| +| `user` | `User?` | `null` | Recipient user object | +| `call` | `Call` | **required** | Call object with session details | +| `callSettingsBuilder` | `CallSettingsBuilder?` | `null` | Configure call settings | +| `height` | `double?` | `null` | Widget height | +| `width` | `double?` | `null` | Widget width | +| `declineButtonIcon` | `Widget?` | `null` | Custom decline/cancel button icon | +| `declineButtonText` | `String?` | `null` | Custom decline button text | +| `disableSoundForCalls` | `bool?` | `false` | Disable outgoing call sound | +| `customSoundForCalls` | `String?` | `null` | Custom sound asset path | + +**Example — custom decline text and disabled sound:** + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + disableSoundForCalls: true, + declineButtonText: "Cancel Call", +) +``` + + + +![Image](/images/1ee27af8-outgoing_call_functionality_cometchat_screens-f0d6a773e40e452b68aa7c9b32462428.png) +![Image](/images/78c18207-outgoing_call_functionality_cometchat_screens-62cac4f18b60221eab40245dc29ea2b0.png) + +--- + +## Custom View Slots + +### Avatar View + +Replace the recipient's avatar. + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + avatarView: (context, call) { + return CircleAvatar( + radius: 50, + backgroundImage: NetworkImage(user?.avatar ?? ""), + ); + }, +) +``` + + + +### Title View + +Replace the recipient's name / call status text. + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + titleView: (context, call) { + return Text( + call.receiver?.name ?? "Unknown", + style: TextStyle(fontSize: 22, fontWeight: FontWeight.bold, color: Colors.white), + ); + }, +) +``` + + + +### Subtitle View + +Replace the subtitle (e.g., "Calling..."). + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + subtitleView: (context, call) { + return Text( + "Ringing...", + style: TextStyle(fontSize: 14, color: Colors.white70), + ); + }, +) +``` + + + +### Cancelled View + +Replace the cancel/end call button. + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + cancelledView: (context, call) { + return ElevatedButton.icon( + onPressed: () { + // Cancel call + }, + icon: Icon(Icons.call_end), + label: Text("End Call"), + style: ElevatedButton.styleFrom(backgroundColor: Colors.red), + ); + }, +) +``` + + + +--- + +## Style + + + +```dart +CometChatOutgoingCall( + user: user, + call: callObject, + outgoingCallStyle: CometChatOutgoingCallStyle( + avatarStyle: CometChatAvatarStyle( + backgroundColor: Color(0xFFFBAA75), + borderRadius: BorderRadius.circular(8), + ), + declineButtonColor: Color(0xFFF44649), + declineButtonBorderRadius: BorderRadius.circular(12), + ), +) +``` + + + + + + + +### Style Properties + +| Property | Description | +|---|---| +| `avatarStyle` | Recipient avatar appearance | +| `declineButtonColor` | Cancel button background color | +| `declineButtonBorderRadius` | Cancel button corner radius | +| `backgroundColor` | Screen background color | + +--- + +## Key V6 Differences + +| Aspect | V5 | V6 | +|---|---|---| +| Subtitle | Static `String?` | Dynamic `subtitleView: Widget? Function(BuildContext, Call)?` | +| Decline callback | `onDecline` | Renamed to `onCancelled` | +| Decline icon | URL-based `String?` | Widget-based `declineButtonIcon: Widget?` | +| State management | GetX controller | BLoC (`OutgoingCallBloc`) | +| Removed | `theme`, `avatarStyle`, `cardStyle`, `buttonStyle`, `ongoingCallConfiguration` | Integrated into main style | + +--- + +## Next Steps + + + + Handle incoming calls + + + Add voice and video call buttons + + + Complete calling setup + + + Detailed styling reference + + diff --git a/ui-kit/flutter/v6/overview.mdx b/ui-kit/flutter/v6/overview.mdx new file mode 100644 index 000000000..00ec1d9ad --- /dev/null +++ b/ui-kit/flutter/v6/overview.mdx @@ -0,0 +1,101 @@ +--- +title: "CometChat UI Kit For Flutter (V6)" +sidebarTitle: "Overview" +--- + + +This is a **beta release** of the CometChat Flutter UI Kit V6. APIs and features may change before the stable release. + + +The **CometChat UI Kit V6** for Flutter is a major architectural evolution of the Flutter Chat UIKit. It provides the same robust set of **prebuilt UI widgets** that are **modular, customizable, and highly scalable**, now built on **clean architecture** with **BLoC state management** for better testability, maintainability, and performance. + +*** + +## **What's New in V6?** + +* **BLoC State Management** – Replaces GetX with flutter_bloc for predictable, testable state. +* **Clean Architecture** – Every module follows `bloc/` + `data/` + `domain/` + `di/` layers. +* **No DataSource Decorator Chain** – Direct static method calls via `MessageTemplateUtils` replace the 10-layer decorator pattern. +* **Internalized Shared UI** – `cometchat_uikit_shared` is now part of the package, no separate dependency needed. +* **Faster Startup** – No extension registration or network calls at init time. + +*** + +## **Why Choose CometChat UI Kit V6?** + +* **Rapid Integration** – Prebuilt UI widgets for faster deployment. +* **Customizable & Flexible** – Modify the UI to align with your brand's identity. +* **Cross-Platform Compatibility** – Works seamlessly across iOS and Android platforms. +* **Scalable & Reliable** – Built on CometChat's robust chat infrastructure. +* **Testable** – BLoC pattern with `bloc_test` and `mocktail` for comprehensive testing. +* **Better Performance** – ~500-2000ms faster startup, no decorator chain overhead. + +*** + +## **Integration** + +### **UI Components (Assemble It Yourself)** + +A collection of individual widgets—like conversation lists, message lists, message composer, etc.—each with built-in chat logic so you can customize every element. + +**How It Works** + +* Import the widgets you need from the UI Kit. +* Arrange them in your desired layout, applying styling or customization as needed. +* Each widget integrates with CometChat logic via BLoC and clean architecture layers. + +**Why It's Great** + +* **Flexible Design** – You control the final UI arrangement. +* **No Extra Overhead** – Implement only the features you need. +* **Modular** – Use exactly what you want, when you want. + +[**Go to V6 Getting Started**](/ui-kit/flutter/v6/getting-started) + +*** + +## **Before Getting Started** + +Before you begin, grasp the fundamental concepts and features offered by CometChat's APIs, SDK, and UI Kit. You can find detailed information in the [Key Concepts](/fundamentals/key-concepts) documentation. + +To begin, please follow the [Getting Started](/ui-kit/flutter/v6/getting-started) guide. + +*** + +## **Next Steps for Developers** + +1. **Learn the Basics** – [Key Concepts](/fundamentals/key-concepts). +2. **Follow the Setup Guide** – [V6 Getting Started](/ui-kit/flutter/v6/getting-started) +3. **Customize UI** – Adjust styles, themes, and widgets. +4. **Test & Deploy** – Run tests and launch your chat app. + +*** + +## **Helpful Resources** + + + + +Fully functional sample applications to accelerate your development. + +[View on GitHub](https://github.com/cometchat/cometchat-uikit-flutter) + + + + + +Upgrade from V5 to V6 with our step-by-step migration guide. + +[View Migration Guide](/ui-kit/flutter/v6/upgrading-from-v5) + + + + +*** + +## **Need Help?** + +If you need assistance, check out: + +* [Developer Community](http://community.cometchat.com/) +* [Support Portal](https://help.cometchat.com/hc/en-us/requests/new) diff --git a/ui-kit/flutter/v6/property-changes.mdx b/ui-kit/flutter/v6/property-changes.mdx new file mode 100644 index 000000000..2f671c0b2 --- /dev/null +++ b/ui-kit/flutter/v6/property-changes.mdx @@ -0,0 +1,173 @@ +--- +title: "Property Changes" +--- + +This document outlines the property changes between V5 and V6 of the CometChat Flutter UI Kit. V6 introduces BLoC-based state management, removes composite widgets, and consolidates styling into `ThemeData` extensions. + +## Architectural Changes + +| Aspect | V5 | V6 | +|---|---|---| +| State Management | GetX | BLoC | +| Composite Widgets | `CometChatMessages`, `CometChatConversationsWithMessages`, etc. | Removed — compose individually | +| 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 | diff --git a/ui-kit/flutter/v6/search.mdx b/ui-kit/flutter/v6/search.mdx new file mode 100644 index 000000000..124f0f0cd --- /dev/null +++ b/ui-kit/flutter/v6/search.mdx @@ -0,0 +1,296 @@ +--- +title: "Search" +description: "Unified search component for finding conversations and messages across all chats." +--- + +`CometChatSearch` provides unified search functionality across conversations and messages. In V6, it uses a single consolidated `SearchBloc` replacing the three separate controllers from V5. + + + + + +--- + +## Where It Fits + +`CometChatSearch` is typically launched from a search button in the conversations list or message header. It searches across both conversations and messages, displaying results in categorized sections. + + + +```dart +CometChatSearch( + onConversationItemClick: (conversation) { + // Navigate to conversation + }, + onMessageItemClick: (message) { + // Navigate to message in context + }, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => CometChatSearch())); +``` + + + +Embedding as a widget: + + + +```dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatSearch(), + ), + ); +} +``` + + + +Launching from conversations with search button: + + + +```dart +CometChatConversations( + hideSearch: false, + searchReadOnly: true, + onSearchTap: () { + Navigator.push(context, MaterialPageRoute( + builder: (context) => CometChatSearch( + onConversationItemClick: (conversation) { + // Navigate to chat + }, + onMessageItemClick: (message) { + // Navigate to message + }, + ), + )); + }, +) +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()` and a user logged in. + +--- + +## Actions and Events + +### Callback Methods + +#### `onConversationItemClick` + +Fires when a conversation result is tapped. + + + +```dart +CometChatSearch( + onConversationItemClick: (conversation) { + final entity = conversation.conversationWith; + if (entity is User) { + navigateToUserChat(entity); + } else if (entity is Group) { + navigateToGroupChat(entity); + } + }, +) +``` + + + +#### `onMessageItemClick` + +Fires when a message result is tapped. + + + +```dart +CometChatSearch( + onMessageItemClick: (message) { + // Navigate to the message in its conversation + }, +) +``` + + + +#### `onBack` + +Fires when the user presses the back button. + + + +```dart +CometChatSearch( + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatSearch( + onError: (e) { + debugPrint("Search error: ${e.message}"); + }, +) +``` + + + +--- + +## Functionality + +| Property | Type | Default | Description | +|---|---|---|---| +| `showBackButton` | `bool?` | `true` | Toggle back button visibility | +| `placeholder` | `String?` | `null` | Search input placeholder text | +| `hideConversationResults` | `bool?` | `false` | Hide conversation search results | +| `hideMessageResults` | `bool?` | `false` | Hide message search results | + +--- + +## Custom View Slots + +### Conversation Item View + +Replace the conversation result item. + + + +```dart +CometChatSearch( + conversationItemView: (conversation, context) { + return ListTile( + leading: CircleAvatar(child: Text(conversation.conversationWith?.name?[0] ?? "")), + title: Text(conversation.conversationWith?.name ?? ""), + ); + }, +) +``` + + + +### Message Item View + +Replace the message result item. + + + +```dart +CometChatSearch( + messageItemView: (message, context) { + return ListTile( + title: Text(message.sender?.name ?? ""), + subtitle: message is TextMessage ? Text(message.text) : Text("Media message"), + ); + }, +) +``` + + + +### State Views + + + +```dart +CometChatSearch( + emptyStateView: (context) => Center(child: Text("No results found")), + errorStateView: (context) => Center(child: Text("Search failed")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), +) +``` + + + +--- + +## Advanced + +### BLoC Access + +The search widget uses `SearchBloc` internally: + +| Component | Description | +|---|---| +| `SearchBloc` | Single consolidated BLoC for all search types | +| `SearchEvent` | Events: `SearchTextChanged`, `ClearSearch`, `LoadMoreConversationResults`, `LoadMoreMessageResults` | +| `SearchState` | Search state with conversation and message results | + +### V5 → V6 Migration + +| V5 | V6 | +|---|---| +| `CometChatSearchController` | `SearchBloc` | +| `CometChatConversationsSearchController` | Merged into `SearchBloc` | +| `CometChatMessagesSearchController` | Merged into `SearchBloc` | +| `SearchUtils` | Inlined into `SearchBloc` | +| 3 separate controllers | 1 unified BLoC | + +--- + +## Style + + + +```dart +CometChatSearch( + searchStyle: CometChatSearchStyle( + backgroundColor: Colors.white, + searchBoxBackgroundColor: Color(0xFFF5F5F5), + searchBoxBorderRadius: BorderRadius.circular(12), + ), +) +``` + + + + + + + +--- + +## Next Steps + + + + Browse recent conversations + + + Display messages in a conversation + + + Detailed styling reference + + + Browse available users + + diff --git a/ui-kit/flutter/v6/shortcut-formatter-guide.mdx b/ui-kit/flutter/v6/shortcut-formatter-guide.mdx new file mode 100644 index 000000000..12ccabf9e --- /dev/null +++ b/ui-kit/flutter/v6/shortcut-formatter-guide.mdx @@ -0,0 +1,139 @@ +--- +title: "Shortcut Formatter" +--- + +## Introduction + +The `ShortcutFormatter` class extends `CometChatTextFormatter` to handle shortcuts within messages. This guide walks you through implementing shortcut extensions in your CometChat V6 application. + +## Setup + +1. Create the ShortcutFormatter class by extending `CometChatTextFormatter`: + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; + +class ShortcutFormatter extends CometChatTextFormatter { + @override + void init() { + trackingCharacter ??= "!"; + } + + bool isShortcutTracking = false; + + void prepareShortcuts(TextEditingController textEditingController) { + CometChat.callExtension('message-shortcuts', 'GET', '/v1/fetch', null, + onSuccess: (map) { + if (map.isNotEmpty) { + Map data = map["data"]; + if (data.isNotEmpty) { + Map shortcuts = data["shortcuts"]; + if (shortcuts.isNotEmpty) { + parseData(shortcuts: shortcuts, textEditingController: textEditingController); + } + } + } + }, + onError: (error) {}, + ); + } + + void parseData({Map? shortcuts, required TextEditingController textEditingController}) async { + if (shortcuts == null || shortcuts.isEmpty) { + suggestionListEventSink?.add([]); + if (onSearch != null) onSearch!(null); + CometChatUIEvents.hidePanel(composerId, CustomUIPosition.composerPreview); + } else { + CometChatUIEvents.hidePanel(composerId, CustomUIPosition.composerPreview); + if (suggestionListEventSink != null && shortcuts.isNotEmpty) { + List list = []; + shortcuts.forEach((key, value) => list.add(SuggestionListItem( + id: key, + title: "$key → $value", + onTap: () { + int cursorPos = textEditingController.selection.base.offset; + String left = textEditingController.text.substring(0, cursorPos - 1); + String right = textEditingController.text.substring(cursorPos); + textEditingController.text = "$left$value $right"; + updatePreviousText(textEditingController.text); + textEditingController.selection = TextSelection( + baseOffset: cursorPos - 1 + "$value".length + 1, + extentOffset: cursorPos - 1 + "$value".length + 1, + ); + resetMatchTracker(); + isShortcutTracking = false; + CometChatUIEvents.hidePanel(composerId, CustomUIPosition.composerPreview); + }, + ))); + suggestionListEventSink?.add(list); + } + } + } + + void updatePreviousText(String text) { + previousTextEventSink?.add(text); + } + + void resetMatchTracker() { + suggestionListEventSink?.add([]); + if (onSearch != null) onSearch!(null); + } + + @override + void onChange(TextEditingController textEditingController, String previousText) { + var cursorPosition = textEditingController.selection.base.offset; + if (textEditingController.text.isEmpty) { + resetMatchTracker(); + return; + } + // Handle shortcut tracking logic + String previousCharacter = cursorPosition == 0 ? "" : textEditingController.text[cursorPosition - 1]; + bool isSpace = cursorPosition == 1 || (textEditingController.text.length > 1 && cursorPosition > 1 && + (textEditingController.text[cursorPosition - 2] == " " || textEditingController.text[cursorPosition - 2] == "\n")); + + if (isShortcutTracking) { + isShortcutTracking = false; + if (onSearch != null) onSearch!(null); + CometChatUIEvents.hidePanel(composerId, CustomUIPosition.composerPreview); + } else if (previousCharacter == trackingCharacter && isSpace) { + isShortcutTracking = true; + if (onSearch != null) onSearch!(trackingCharacter); + CometChatUIEvents.showPanel(composerId, CustomUIPosition.composerPreview, + (context) => getLoadingIndicator(context, cometChatTheme)); + prepareShortcuts(textEditingController); + } + } + + @override + TextStyle getMessageInputTextStyle(CometChatTheme theme) { + throw UnimplementedError(); + } + + @override + void handlePreMessageSend(BuildContext context, BaseMessage baseMessage) {} + + @override + void onScrollToBottom(TextEditingController textEditingController) {} +} +``` + + + +## Usage + +Pass the `ShortcutFormatter` to the `textFormatters` property of `CometChatMessageComposer`: + + + +```dart +CometChatMessageComposer( + user: user, + textFormatters: [ShortcutFormatter()], +) +``` + + + + diff --git a/ui-kit/flutter/v6/sound-manager.mdx b/ui-kit/flutter/v6/sound-manager.mdx new file mode 100644 index 000000000..7151fe40d --- /dev/null +++ b/ui-kit/flutter/v6/sound-manager.mdx @@ -0,0 +1,61 @@ +--- +title: "Sound Manager" +--- + +## Overview + +The `SoundManager` is a helper class responsible for managing and playing various types of audio in the CometChat V6 UI Kit. This includes sound events for incoming and outgoing messages and calls. + +## Methods + +### Play Sound + +The SoundManager plays pre-defined or custom sounds based on user interactions with the chat interface. + + + +```dart +// Play default sounds: +SoundManager().play(sound: Sound.incomingMessage); +SoundManager().play(sound: Sound.outgoingMessage); +``` + + + +### Stop Sound + +Stop any sound currently being played: + + + +```dart +SoundManager().stop(); +``` + + + +## Usage + +Play a custom sound: + + + +```dart +SoundManager().play(sound: Sound.outgoingMessage, customSound: "assetPath"); +``` + + + +## Sound Enum Reference + +| Sound | Asset | +|---|---| +| incomingMessage | assets/sound/incoming_message.wav | +| outgoingMessage | assets/sound/outgoing_message.wav | +| incomingMessageFromOther | assets/sound/incoming_message.wav | +| outgoingCall | assets/sound/outgoing_call.wav | +| incomingCall | assets/sound/incoming_call.wav | + + +In V6, the `CometChatConversations` widget provides `disableSoundForMessages` and `customSoundForMessages` properties to control sound behavior at the widget level. + diff --git a/ui-kit/flutter/v6/theme-introduction.mdx b/ui-kit/flutter/v6/theme-introduction.mdx new file mode 100644 index 000000000..2b7f02a34 --- /dev/null +++ b/ui-kit/flutter/v6/theme-introduction.mdx @@ -0,0 +1,84 @@ +--- +title: "Theming In CometChat Flutter UI Kit V6" +sidebarTitle: "Theming" +--- + +CometChat's theming framework is a robust system that empowers developers to define the look and feel of their applications with precision and consistency. It follows three essential design system principles: Color, Typography, and Shape. + +> The theming system is identical between V5 and V6. All theme classes, properties, and APIs work the same way. + +## Theming Overview + +Theming in the UI Kit consists of three core components: + +- **Color:** Managed through `CometChatColorPalette`, it controls the application's color scheme, including primary, neutral, alert, and text colors. +- **Typography:** Defined via `CometChatTypography`, it standardizes text styles, such as font size and weight. +- **Shape:** Configured using `CometChatSpacing`, it defines the structure of margins, paddings, and border radii. + +## Key Benefits + +- Achieve consistent UI design across your application. +- Support for light and dark themes. +- Easy scalability and customization for app-specific requirements. + +## Light and Dark Themes + +The Chat UI Kit supports both light and dark themes. V6 adds dedicated icon variants: +- `assets/icons/light/` — light mode icons +- `assets/icons/dark/` — dark mode icons +- `assets/icons/svg/calls/` — SVG call icons + +## Custom Theme + +The Chat UI Kit offers robust support for creating customized themes using `CometChatColorPalette`, `CometChatTypography`, and `CometChatSpacing` with Flutter's `ThemeExtension`. + + + +```dart +ThemeData( + fontFamily: 'Times New Roman', + extensions: [ + CometChatColorPalette( + primary: Color(0xFFF76808), + ), + ], +) +``` + + + +## Core Components + +### Color + +The `CometChatColorPalette` class manages colors in your app: + +- **Primary Colors:** Base colors and extended shades. +- **Neutral Colors:** Shades for surfaces and backgrounds. +- **Alert Colors:** Colors for states like success, error, warning, and info. +- **Text Colors:** Differentiated for primary, secondary, and disabled states. + +### Typography + +The `CometChatTypography` class standardizes text styles: + +- **Headings:** Text styles for various heading levels. +- **Body:** Styling for regular text. +- **Captions:** Smaller text style for labels. +- **Buttons:** Text style for button text. +- **Links:** Styles for clickable links. +- **Titles:** Style for main titles or component headers. + +### Spacing + +The `CometChatSpacing` class defines layout structure: + +- **Padding:** Internal spacing within elements. +- **Margin:** Space between elements. +- **Radius:** Corner rounding of UI elements. + +## Best Practices + +- **Ensure Contrast:** Follow accessibility guidelines to maintain a minimum contrast ratio. +- **Consistency:** Use a consistent color palette across all components. +- **Adaptability:** Test your theme in various scenarios, such as low-light and high-contrast environments. diff --git a/ui-kit/flutter/v6/threaded-messages-header.mdx b/ui-kit/flutter/v6/threaded-messages-header.mdx new file mode 100644 index 000000000..c80efb38c --- /dev/null +++ b/ui-kit/flutter/v6/threaded-messages-header.mdx @@ -0,0 +1,235 @@ +--- +title: "Threaded Messages Header" +description: "Header component for threaded conversations showing the parent message, reply count, and thread navigation." +--- + +`CometChatThreadedHeader` displays the parent message of a thread along with reply count and provides the container for threaded message list and composer. It enables organized threaded conversations within a chat. + + + + + +--- + +## Where It Fits + +`CometChatThreadedHeader` is used when a user taps "Reply in Thread" on a message. It wraps the parent message display with a `CometChatMessageList` (filtered by `parentMessageId`) and `CometChatMessageComposer` for thread replies. + + + +```dart +CometChatThreadedHeader( + parentMessage: parentMessage, + loggedInUser: loggedInUser, +) +``` + + + +--- + +## Quick Start + + + +```dart +import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; +import 'package:flutter/material.dart'; + +class ThreadScreen extends StatelessWidget { + final BaseMessage parentMessage; + final User loggedInUser; + + const ThreadScreen({ + super.key, + required this.parentMessage, + required this.loggedInUser, + }); + + @override + Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatThreadedHeader( + parentMessage: parentMessage, + loggedInUser: loggedInUser, + ), + ), + ); + } +} +``` + + + +Typically launched from the message list when a user selects "Reply in Thread": + + + +```dart +CometChatMessageList( + user: user, + onThreadRepliesClick: (message, context, {bubbleView}) { + Navigator.push(context, MaterialPageRoute( + builder: (context) => ThreadScreen( + parentMessage: message, + loggedInUser: CometChatUIKit.loggedInUser!, + ), + )); + }, +) +``` + + + +Prerequisites: CometChat SDK initialized, a user logged in, and a valid `BaseMessage` object as the parent message. + +--- + +## Actions and Events + +### Callback Methods + +#### `onBack` + +Fires when the user presses the back button. + + + +```dart +CometChatThreadedHeader( + parentMessage: parentMessage, + loggedInUser: loggedInUser, + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatThreadedHeader( + parentMessage: parentMessage, + loggedInUser: loggedInUser, + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +### SDK Events (Real-Time, Automatic) + +| SDK Listener | Internal behavior | +|---|---| +| New thread reply received | Increments reply count | +| Parent message edited | Updates parent message display | +| Parent message deleted | Updates parent message display | + +--- + +## Functionality + +| Property | Type | Default | Description | +|---|---|---|---| +| `parentMessage` | `BaseMessage` | **required** | The parent message of the thread | +| `loggedInUser` | `User` | **required** | The currently logged-in user | +| `showBackButton` | `bool?` | `true` | Toggle back button visibility | +| `title` | `String?` | `null` | Custom title text | +| `hideMessageComposer` | `bool?` | `false` | Hide the message composer | + +--- + +## Custom View Slots + +### Bubble View + +Replace the parent message bubble display. + + + +```dart +CometChatThreadedHeader( + parentMessage: parentMessage, + loggedInUser: loggedInUser, + bubbleView: (message) { + if (message is TextMessage) { + return Container( + padding: EdgeInsets.all(12), + decoration: BoxDecoration( + color: Color(0xFFF5F5F5), + borderRadius: BorderRadius.circular(8), + ), + child: Text(message.text), + ); + } + return null; + }, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +The threaded header uses `ThreadedHeaderBloc` internally: + +| Component | Description | +|---|---| +| `ThreadedHeaderBloc` | Manages threaded header state | +| `ThreadedHeaderEvent` | Events: `InitializeThreadedHeader`, `IncrementReplyCount`, `UpdateParentMessage` | +| `ThreadedHeaderState` | Threaded header state with parent message and reply count | + +--- + +## Style + + + +```dart +CometChatThreadedHeader( + parentMessage: parentMessage, + loggedInUser: loggedInUser, + style: CometChatThreadedHeaderStyle( + backgroundColor: Colors.white, + replyCountTextColor: Color(0xFF727272), + ), +) +``` + + + + + + + +--- + +## Next Steps + + + + Display messages in a conversation + + + Compose and send messages + + + Complete threaded messages implementation + + + Detailed styling reference + + diff --git a/ui-kit/flutter/v6/troubleshooting.mdx b/ui-kit/flutter/v6/troubleshooting.mdx new file mode 100644 index 000000000..0bc3c4c3c --- /dev/null +++ b/ui-kit/flutter/v6/troubleshooting.mdx @@ -0,0 +1,112 @@ +--- +title: "Troubleshooting" +description: "Common failure modes and fixes for the CometChat Flutter V6 UI Kit." +--- + +## Initialization and Login + +| Symptom | Cause | Fix | +|---|---|---| +| `CometChatUIKit.init()` fails silently | Invalid App ID, Region, or Auth Key | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/) | +| Blank screen after login | Component rendered before `init()` or `login()` completes | Ensure `init()` → `login()` order completes before rendering any UI Kit component. See [Methods](/ui-kit/flutter/v6/methods) | +| Component renders but shows no data | User not logged in | Call `CometChatUIKit.login("UID")` after init resolves | +| Login fails with "UID not found" | UID doesn't exist in your CometChat app | Create the user via Dashboard, SDK, or REST API first | +| `CometChatUIKit.loggedInUser` returns null | User not logged in or session expired | Call `login()` or `loginWithAuthToken()` first | +| Auth Key exposed in production | Using Auth Key instead of Auth Token | Switch to `loginWithAuthToken()` for production. Generate tokens server-side via the REST API | + +--- + +## Theming and Styling + +| Symptom | Cause | Fix | +|---|---|---| +| Theme not applied | `ThemeExtension` not added to `MaterialApp` | Add CometChat style extensions to your `ThemeData.extensions` list | +| Dark mode not working | Brightness not detected | CometChat theme uses `MediaQuery.platformBrightnessOf(context)`. Ensure your `MaterialApp` supports dark mode | +| Custom colors not applying | Overriding wrong style class | Check [Component Styling](/ui-kit/flutter/v6/component-styling) for the correct style class per component | +| Component-level style ignored | Style object not passed correctly | Ensure you pass the style to the `style` property, not as a `ThemeExtension` | +| Styles apply in light mode but not dark | Only light theme configured | Configure both light and dark themes in `MaterialApp` with separate `ThemeData` instances | +| Bubble style not applying | Style linked to wrong direction | Define separate styles for `CometChatOutgoingMessageBubbleStyle` and `CometChatIncomingMessageBubbleStyle` — changing one does not affect the other | + +--- + +## Components + +| Symptom | Cause | Fix | +|---|---|---| +| Component not rendering | `init()` or `login()` not complete | Ensure both complete before building any CometChat widget | +| Message list is empty | Invalid `User` or `Group` object | Fetch the user or group via the SDK before passing it to the component | +| `onThreadRepliesClick` not firing | Callback not set | Pass the callback to `CometChatMessageList(onThreadRepliesClick: ...)` | +| Custom template not rendering | Template key doesn't match message | Ensure `type` and `category` on your template match the message's `type` and `category` exactly | +| `addTemplate` not overriding default | Template appended, not replaced | `addTemplate` appends to the list. The template map uses last-write-wins by `category_type` key, so your template must have the same key to override | +| Keyboard covers composer | `resizeToAvoidBottomInset` not set | Set `resizeToAvoidBottomInset: true` on your `Scaffold` | +| Swipe-to-reply not working | Disabled or message not eligible | Check `enableSwipeToReply` is `true`, message has a valid ID, and is not deleted or an action message | +| Audio playback issues | Multiple audio states | The UI Kit uses `AudioStateManager` internally. Ensure you're not conflicting with other audio players | + +--- + +## Calling + +| Symptom | Cause | Fix | +|---|---|---| +| Call buttons not appearing | Calls not enabled | Ensure `enableCalls = true` is set in your `UIKitSettingsBuilder` | +| Incoming call screen not showing | Call listener not registered | Ensure `CometChat.addCallListener()` is called in your app initialization | +| Call connects but no audio/video | Missing permissions | Request camera and microphone permissions before initiating calls | + +--- + +## Extensions + +| Symptom | Cause | Fix | +|---|---|---| +| Extension feature not appearing | Extension not activated in Dashboard | Enable the specific extension from your [Dashboard](/fundamentals/extensions-overview) | +| Stickers not showing | Sticker extension not enabled | Activate [Sticker Extension](/fundamentals/stickers) in Dashboard | +| Polls option missing | Polls extension not enabled | Activate [Polls Extension](/fundamentals/polls) in Dashboard | +| Link preview not rendering | Link Preview extension not enabled | Activate [Link Preview Extension](/fundamentals/link-preview) in Dashboard | + +--- + +## BLoC and State Management + +| Symptom | Cause | Fix | +|---|---|---| +| BLoC already closed error | External BLoC disposed prematurely | If you provide a custom BLoC via `messageListBloc`, ensure it outlives the widget | +| State not updating after BLoC event | Event dispatched to wrong BLoC instance | Ensure you're dispatching events to the same BLoC instance the widget is using | +| Duplicate messages appearing | Multiple BLoC instances for same conversation | Use a single BLoC instance per conversation. Don't create a new one on every rebuild | + +--- + +## Localization + +| Symptom | Cause | Fix | +|---|---|---| +| UI text not translated | Locale not set | Ensure your `MaterialApp` has the correct `locale` and `supportedLocales` configured | +| String overrides not appearing | Wrong key | Verify the key matches exactly. See [Localize](/ui-kit/flutter/v6/localize) | + +--- + +## Sound + +| Symptom | Cause | Fix | +|---|---|---| +| No sound plays | Sound disabled | Check `disableSoundForMessages` is not set to `true` | +| Custom sound not playing | Asset not found | Ensure the sound file is added to your `pubspec.yaml` assets and the path is correct | + +--- + +## Text Formatters + +| Symptom | Cause | Fix | +|---|---|---| +| Mentions render as plain text | Formatter not added | Pass `CometChatMentionsFormatter()` in the `textFormatters` list | +| `textFormatters` has no effect | Empty list passed | Add at least one formatter to the list | +| Markdown not rendering | `MarkdownTextFormatter` not included | Add `MarkdownTextFormatter()` to your `textFormatters` list or use `RichTextConfiguration` on the composer | + +--- + +## Events + +| Symptom | Cause | Fix | +|---|---|---| +| Event listener not firing | Subscribed to wrong event class | Check the [Events](/ui-kit/flutter/v6/events) page for exact event class names | +| Duplicate event triggers | Multiple registrations without cleanup | Remove listeners when the widget is disposed | +| Listener ID collision | Non-unique listener tag | Use a unique string for each listener registration | diff --git a/ui-kit/flutter/v6/upgrading-from-v5.mdx b/ui-kit/flutter/v6/upgrading-from-v5.mdx new file mode 100644 index 000000000..8c1cf7c41 --- /dev/null +++ b/ui-kit/flutter/v6/upgrading-from-v5.mdx @@ -0,0 +1,185 @@ +--- +title: "Upgrading From V5" +sidebarTitle: "Upgrading From V5" +--- + +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 | GetX (`get: ^4.6.5`) | BLoC (`flutter_bloc: ^8.1.0`) | +| Architecture | Flat layout with controllers | Clean Architecture (bloc/data/domain/di) | +| Data Access | DataSource decorator chain (10 layers) | `MessageTemplateUtils` static methods (1 hop) | +| Extensions | Registered via `UIKitSettings` | Built-in, no registration needed | +| Shared UI | External `cometchat_uikit_shared` package | Internalized into `lib/shared_ui/` | +| Composite Widgets | `CometChatMessages`, `CometChatConversationsWithMessages` | Removed — compose UI yourself | + +## Step-by-Step Migration + +### 1. Update Imports + +```dart +// 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 +// 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 +// V5 +CometChatUIKit.getDataSource().getTextMessageBubble(msg, ctx, align); +ChatConfigurator.getDataSource().getAllMessageTemplates(); + +// V6 +MessageTemplateUtils.getTextMessageBubble(msg, ctx, align); +MessageTemplateUtils.getAllMessageTemplates(); +``` + +### 4. Replace Composite Widgets + +```dart +// V5 — composite widget +CometChatMessages(user: user); + +// V6 — compose yourself +Column( + children: [ + CometChatMessageHeader(user: user), + Expanded(child: CometChatMessageList(user: user)), + CometChatMessageComposer(user: user), + ], +) +``` + +### 5. Widget Renames + +```dart +// V5 +CometChatEditPreview( + editPreviewTitle: "Edit Message", + editPreviewSubtitle: text, +); + +// V6 +CometChatMessagePreview( + messagePreviewTitle: "Edit Message", + messagePreviewSubtitle: text, + message: baseMessage, +); +``` + +### 6. Update Dependencies + +**Install V6 via CLI (hosted on Cloudsmith):** + +```bash +dart pub add cometchat_chat_uikit:6.0.0-beta1 --hosted-url https://dart.cloudsmith.io/cometchat/cometchat/ +``` + +Or add manually to `pubspec.yaml`: + +```yaml +dependencies: + cometchat_chat_uikit: + hosted: https://dart.cloudsmith.io/cometchat/cometchat/ + version: 6.0.0-beta1 + flutter_bloc: ^8.1.0 + equatable: ^2.0.5 + video_player: ^2.7.2 + http: ^1.0.0 + flutter_image: ^4.1.0 + image_picker: ^1.0.5 + flutter_svg: ^2.0.17 + flutter_cache_manager: ^3.4.1 + cached_network_image: ^3.3.1 + cometchat_calls_sdk: ^4.2.0 + permission_handler: ^11.3.1 + diffutil_dart: ^3.0.0 + scrollview_observer: ^1.23.0 +``` + +**Remove from `pubspec.yaml`:** + +```yaml +dependencies: + cometchat_uikit_shared: + path: ../shared_uikit # internalized — no longer needed +``` + +### 7. State Management Migration (Advanced) + +If you were directly using GetX controllers: + +```dart +// V5 — GetX +GetBuilder( + init: CometChatConversationsController(...), + builder: (controller) => buildUI(controller.list), +); + +// V6 — BLoC +BlocProvider( + create: (_) => ConversationsBloc()..add(LoadConversations()), + child: BlocBuilder( + builder: (context, state) { + if (state is ConversationsLoaded) return buildUI(state.conversations); + return const CircularProgressIndicator(); + }, + ), +); +``` + +### Controller → BLoC Mapping + +| V5 Controller | V6 BLoC | +|---|---| +| `CometChatConversationsController` | `ConversationsBloc` | +| `CometChatUsersController` | `UsersBloc` | +| `CometChatGroupsController` | `GroupsBloc` | +| `CometChatGroupMembersController` | `GroupMembersBloc` | +| `CometChatMessageComposerController` | `MessageComposerBloc` | +| `CometChatMessageHeaderController` | `MessageHeaderBloc` | +| `CometChatMessageListController` | `MessageListBloc` | +| `CometchatMessageInformationController` | `MessageInformationBloc` | +| `CometChatThreadedHeaderController` | `ThreadedHeaderBloc` | +| `CometChatSearchController` | `SearchBloc` | + +## Migration Checklist + +1. ☐ Replace all `CometChatXxxController` usage with `XxxBloc` +2. ☐ Replace `GetBuilder` with `BlocBuilder` +3. ☐ Replace `CometChatUIKit.getDataSource().xxx()` with `MessageTemplateUtils.xxx()` +4. ☐ Remove `extensions` and `aiFeature` from `UIKitSettings` +5. ☐ Update imports from `src/` to `chat_ui/src/` +6. ☐ Replace `cometchat_uikit_shared` package import with internal `shared_ui/` +7. ☐ Rename `CometChatEditPreview` → `CometChatMessagePreview` +8. ☐ Replace composite widgets with individual widget composition +9. ☐ Add new dependencies (flutter_bloc, equatable, etc.) +10. ☐ Remove `cometchat_uikit_shared` dependency +11. ☐ Test all features after migration diff --git a/ui-kit/flutter/v6/users.mdx b/ui-kit/flutter/v6/users.mdx new file mode 100644 index 000000000..fec746ab4 --- /dev/null +++ b/ui-kit/flutter/v6/users.mdx @@ -0,0 +1,503 @@ +--- +title: "Users" +description: "Scrollable list of all available users with search, avatars, names, and online/offline status indicators." +--- + +`CometChatUsers` renders a scrollable list of all available users with real-time presence updates, search, avatars, and online/offline status indicators. + +--- + +## Where It Fits + +`CometChatUsers` is a list component. It renders all available users and emits the selected `User` via `onItemTap`. Wire it to `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer` to build a direct messaging layout. + + + +```dart +CometChatUsers( + onItemTap: (context, user) { + // Navigate to chat with this user + }, +) +``` + + + +--- + +## Quick Start + +Using Navigator: + + + +```dart +Navigator.push(context, MaterialPageRoute(builder: (context) => const CometChatUsers())); +``` + + + +Embedding as a widget: + + + +```dart +@override +Widget build(BuildContext context) { + return Scaffold( + body: SafeArea( + child: CometChatUsers(), + ), + ); +} +``` + + + +Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()`, a user logged in, and the UI Kit dependency added. + +--- + +## Filtering Users + +Pass a `UsersRequestBuilder` to control what loads: + + + +```dart +CometChatUsers( + usersRequestBuilder: UsersRequestBuilder() + ..limit = 20 + ..friendsOnly = true, +) +``` + + + +### Filter Recipes + +| Recipe | Builder property | +| --- | --- | +| Friends only | `..friendsOnly = true` | +| Limit per page | `..limit = 10` | +| Search by keyword | `..searchKeyword = "john"` | +| Hide blocked users | `..hideBlockedUsers = true` | +| Filter by roles | `..roles = ["admin", "moderator"]` | +| Filter by tags | `..tags = ["vip"]` | +| Online users only | `..userStatus = CometChatConstants.userStatusOnline` | +| Filter by UIDs | `..UIDs = ["uid1", "uid2"]` | + +--- + +## Actions and Events + +### Callback Methods + +#### `onItemTap` + +Fires when a user row is tapped. Primary navigation hook. + + + +```dart +CometChatUsers( + onItemTap: (context, user) { + // Navigate to chat screen + }, +) +``` + + + +#### `onItemLongPress` + +Fires when a user row is long-pressed. + + + +```dart +CometChatUsers( + onItemLongPress: (context, user) { + // Show context menu + }, +) +``` + + + +#### `onBack` + +Fires when the user presses the back button in the app bar. + + + +```dart +CometChatUsers( + onBack: () { + Navigator.pop(context); + }, +) +``` + + + +#### `onSelection` + +Fires when users are selected/deselected in multi-select mode. + + + +```dart +CometChatUsers( + selectionMode: SelectionMode.multiple, + activateSelection: ActivateSelection.onClick, + onSelection: (selectedUsers, context) { + // Handle selected users + }, +) +``` + + + +#### `onError` + +Fires on internal errors. + + + +```dart +CometChatUsers( + onError: (e) { + debugPrint("Error: ${e.message}"); + }, +) +``` + + + +#### `onLoad` + +Fires when the list is successfully fetched and loaded. + + + +```dart +CometChatUsers( + onLoad: (userList) { + debugPrint("Loaded ${userList.length}"); + }, +) +``` + + + +#### `onEmpty` + +Fires when the list is empty after loading. + + + +```dart +CometChatUsers( + onEmpty: () { + debugPrint("No users found"); + }, +) +``` + + + +### SDK Events (Real-Time, Automatic) + +The component listens to these SDK events internally. No manual setup needed. + +| SDK Listener | Internal behavior | +| --- | --- | +| `onUserOnline` | Updates online status indicator for the user | +| `onUserOffline` | Updates offline status indicator for the user | +| Connection reconnected | Triggers silent refresh to sync user list | + +--- + +## Functionality + +| Property | Type | Default | Description | +| --- | --- | --- | --- | +| `title` | `String?` | `null` | Custom app bar title | +| `showBackButton` | `bool` | `true` | Toggle back button | +| `hideAppbar` | `bool?` | `false` | Toggle app bar visibility | +| `hideSearch` | `bool` | `false` | Toggle search bar | +| `usersStatusVisibility` | `bool?` | `true` | Show online/offline status indicator | +| `stickyHeaderVisibility` | `bool?` | `false` | Show alphabetical sticky header | +| `selectionMode` | `SelectionMode?` | `null` | Enable selection mode (`single` or `multiple`) | +| `searchPlaceholder` | `String?` | `null` | Search placeholder text | +| `searchKeyword` | `String?` | `null` | Pre-fill search keyword | + +--- + +## Custom View Slots + +### Leading View + +Replace the avatar / left section. + + + +```dart +CometChatUsers( + leadingView: (context, user) { + return CircleAvatar( + child: Text(user.name?[0] ?? ""), + ); + }, +) +``` + + + +### Title View + +Replace the name / title text. + + + +```dart +CometChatUsers( + titleView: (context, user) { + return Text( + user.name ?? "", + style: TextStyle(fontWeight: FontWeight.bold), + ); + }, +) +``` + + + +### Subtitle View + +Replace the subtitle text below the user's name. + + + +```dart +CometChatUsers( + subtitleView: (context, user) { + return Text( + user.status ?? "offline", + maxLines: 1, + overflow: TextOverflow.ellipsis, + ); + }, +) +``` + + + +### Trailing View + +Replace the right section of each user item. + + + +```dart +CometChatUsers( + trailingView: (context, user) { + return Text(user.role ?? ""); + }, +) +``` + + + +### List Item View + +Replace the entire list item row. + + + +```dart +CometChatUsers( + listItemView: (user) { + return ListTile( + leading: CircleAvatar(child: Text(user.name?[0] ?? "")), + title: Text(user.name ?? ""), + subtitle: Text(user.status ?? "offline"), + ); + }, +) +``` + + + +### State Views + + + +```dart +CometChatUsers( + emptyStateView: (context) => Center(child: Text("No users found")), + errorStateView: (context) => Center(child: Text("Something went wrong")), + loadingStateView: (context) => Center(child: CircularProgressIndicator()), +) +``` + + + +--- + +## Common Patterns + +### Minimal list — hide all chrome + + + +```dart +CometChatUsers( + hideAppbar: true, + hideSearch: true, + stickyHeaderVisibility: false, +) +``` + + + +### Friends-only list + + + +```dart +CometChatUsers( + usersRequestBuilder: UsersRequestBuilder() + ..friendsOnly = true, +) +``` + + + +### Online users only + + + +```dart +CometChatUsers( + usersRequestBuilder: UsersRequestBuilder() + ..userStatus = CometChatConstants.userStatusOnline, +) +``` + + + +--- + +## Advanced + +### BLoC Access + +Provide a custom `UsersBloc` to override behavior: + + + +```dart +CometChatUsers( + usersBloc: CustomUsersBloc(), +) +``` + + + +### Extending UsersBloc + +`UsersBloc` uses the `ListBase` mixin with override hooks: + + + +```dart +class CustomUsersBloc extends UsersBloc { + @override + void onItemAdded(User item, List updatedList) { + // Custom sorting logic + super.onItemAdded(item, updatedList); + } + + @override + void onListReplaced(List previousList, List newList) { + // Filter out specific users + final filtered = newList.where((u) => u.role != "bot").toList(); + super.onListReplaced(previousList, filtered); + } +} +``` + + + +For `ListBase` override hooks (`onItemAdded`, `onItemRemoved`, `onItemUpdated`, `onListCleared`, `onListReplaced`), see [BLoC & Data — ListBase Hooks](/ui-kit/flutter/v6/customization-bloc-data#listbase-hooks). + +### Public BLoC Events + +| Event | Description | +| --- | --- | +| `LoadUsers({searchKeyword, silent})` | Load initial users. `silent: true` keeps existing list visible. | +| `LoadMoreUsers()` | Load next page (pagination) | +| `RefreshUsers()` | Refresh the list | +| `SearchUsers(keyword)` | Search users with debouncing | +| `ToggleUserSelection(uid)` | Toggle selection state | +| `ClearUserSelection()` | Clear all selections | +| `UpdateUser(user)` | Update a specific user | + +### Public BLoC Methods + +| Method | Returns | Description | +| --- | --- | --- | +| `getStatusNotifier(uid)` | `ValueNotifier` | Per-user status notifier for isolated rebuilds | +| `getUserStatus(uid)` | `String` | Current status for a user (`online` / `offline`) | + +--- + +## Style + + + +```dart +CometChatUsers( + usersStyle: CometChatUsersStyle( + avatarStyle: CometChatAvatarStyle( + borderRadius: BorderRadius.circular(8), + backgroundColor: Color(0xFFFBAA75), + ), + statusIndicatorStyle: CometChatStatusIndicatorStyle(), + ), +) +``` + + + +### Style Properties + +| Property | Description | +| --- | --- | +| `backgroundColor` | List background color | +| `avatarStyle` | Avatar appearance | +| `statusIndicatorStyle` | Online/offline indicator | +| `searchBoxStyle` | Search box appearance | + +See [Component Styling](/ui-kit/flutter/v6/component-styling) for the full reference. + +--- + +## Next Steps + + + + Browse recent conversations + + + Browse and search available groups + + + Detailed styling reference + + + Customize message bubble structure + + \ No newline at end of file