From d1b696f08cd2fbdc0d4326b9099dc980ca7d07cc Mon Sep 17 00:00:00 2001 From: rajdubey Date: Mon, 16 Nov 2026 17:56:40 +0530 Subject: [PATCH 1/7] docs(angular): offline support for the Angular UI Kit Add the Offline Support page for Angular UI Kit v5, an Offline Support section in Core Features, the nav entry after core-features in the Angular v5 Features > Chat group, and the page in llms-angular-v5. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WEaVigCRBjkftm78T25MQA --- docs.json | 1 + ui-kit/angular/core-features.mdx | 15 +- ui-kit/angular/llms-angular-v5.mdx | 1 + ui-kit/angular/offline-support.mdx | 468 +++++++++++++++++++++++++++++ 4 files changed, 484 insertions(+), 1 deletion(-) create mode 100644 ui-kit/angular/offline-support.mdx diff --git a/docs.json b/docs.json index 40eea0779..60d74eb3b 100644 --- a/docs.json +++ b/docs.json @@ -2589,6 +2589,7 @@ "group": "Chat", "pages": [ "ui-kit/angular/core-features", + "ui-kit/angular/offline-support", "ui-kit/angular/extensions", "ui-kit/angular/ai-features" ] diff --git a/ui-kit/angular/core-features.mdx b/ui-kit/angular/core-features.mdx index 912129e70..a960197a3 100644 --- a/ui-kit/angular/core-features.mdx +++ b/ui-kit/angular/core-features.mdx @@ -9,7 +9,7 @@ description: "Review CometChat Angular UI Kit core features for messaging, media | --- | --- | | Package | `@cometchat/chat-uikit-angular` | | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")` — must complete before rendering any component | -| Core features | Instant Messaging, Media Sharing, Read Receipts, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Pin & Save Messages, Search, Threaded Conversations, Thread Subscription, Moderation, Report Message, Group Chat | +| Core features | Instant Messaging, Media Sharing, Read Receipts, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Pin & Save Messages, Search, Threaded Conversations, Thread Subscription, Moderation, Report Message, Group Chat, Offline Support | | Key components | `CometChatConversations` → [Conversations](/ui-kit/angular/components/cometchat-conversations), `CometChatMessageList` → [Message List](/ui-kit/angular/components/cometchat-message-list), `CometChatMessageComposer` → [Message Composer](/ui-kit/angular/components/cometchat-message-composer), `CometChatMessageHeader` → [Message Header](/ui-kit/angular/components/cometchat-message-header), `CometChatUsers` → [Users](/ui-kit/angular/components/cometchat-users), `CometChatGroups` → [Groups](/ui-kit/angular/components/cometchat-groups), `CometChatGroupMembers` → [Group Members](/ui-kit/angular/components/cometchat-group-members) | | CSS class prefix | `.cometchat-` | | Theming | Override CSS variables on `.cometchat` class. See [Theming](/ui-kit/angular/customization/theming) | @@ -276,6 +276,19 @@ Conversation and Advanced Search enables users to quickly find conversations, me See the [Search Messages Guide](/ui-kit/angular/guides/search-messages) for detailed implementation instructions. +## Offline Support + +Offline Support keeps the chat usable when the network drops. Chats and messages the user has already loaded appear at once from the device, messages sent offline are queued and go out by themselves on reconnect, and unsent messages can be retried or deleted. It is available from v5.3.0 with Chat SDK 4.3.0 or later, and is **off by default**. Turn it on with `setOfflineConfig({ enabled: true })` on the `UIKitSettingsBuilder`. + +| Component | Functionality | +| --- | --- | +| [cometchat-conversations](/ui-kit/angular/components/cometchat-conversations) | Shows saved chats first, then merges the server page; shows **Connect to load chats** offline with nothing saved. | +| [cometchat-message-list](/ui-kit/angular/components/cometchat-message-list) | Shows saved messages, a **Connect to load more** row past them, and **Not sent yet** / **Not sent. Tap to retry** on unsent messages, with Retry and Delete. | +| [cometchat-message-composer](/ui-kit/angular/components/cometchat-message-composer) | Queues text and media sent while offline. | +| [cometchat-search](/ui-kit/angular/components/cometchat-search) | Shows **Connect to search** for a keyword search that cannot run offline. | + +See the [Offline Support guide](/ui-kit/angular/offline-support). + --- ## Next Steps diff --git a/ui-kit/angular/llms-angular-v5.mdx b/ui-kit/angular/llms-angular-v5.mdx index 4be4c090f..11422b874 100644 --- a/ui-kit/angular/llms-angular-v5.mdx +++ b/ui-kit/angular/llms-angular-v5.mdx @@ -48,6 +48,7 @@ exhaustive inputs, long-tail components, theming tokens, or feature enablement. ## Core & configuration - [Core Features](/ui-kit/angular/core-features) +- [Offline Support](/ui-kit/angular/offline-support) - [Methods](/ui-kit/angular/methods) - [Events](/ui-kit/angular/events) - [Sound Manager](/ui-kit/angular/sound-manager) diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx new file mode 100644 index 000000000..d36d2fa64 --- /dev/null +++ b/ui-kit/angular/offline-support.mdx @@ -0,0 +1,468 @@ +--- +title: "Offline Support" +sidebarTitle: "Offline Support" +description: "Show cached chats and messages without a network and queue messages to send on reconnect with the CometChat Angular UI Kit." +--- + + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-uikit-angular` 5.3.0 or later | +| Chat SDK | `@cometchat/chat-sdk-javascript` 4.3.0 or later | +| Default | Off. Nothing changes until you turn it on | +| Enable | `new UIKitSettingsBuilder().setOfflineConfig({ enabled: true })` before `CometChatUIKit.init(UIKitSettings)` | +| Config type | `CometChatOfflineConfig`. Passed to the Chat SDK unchanged. Options: [OfflineConfig options](/sdk/javascript/offline-reference#offlineconfig-options) | +| Runtime check | `CometChat.isOfflineEnabled()`. The UI Kit reads it every time, not your config | +| Inputs | `hideOfflineNotices` on `cometchat-message-list` and `cometchat-conversations` | +| Events | `CometChatMessageEvents.ccMessageSendStateChanged`, `CometChatMessageEvents.ccOfflineCacheReset` | +| Service signals | `connectToSearch`, `searchFailed` on `SearchConversationsService` and `SearchMessagesService` | +| Component method | `CometChatMessageListComponent.retryOfflineRead()` | +| Option ids | `CometChatUIKitConstants.MessageOption.retryMessage`, `CometChatUIKitConstants.MessageOption.discardMessage` | +| Quiet rejection | `CometChatUIKit.send*` rejects with code `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset | + + + +## Overview + +With offline support on, the UI Kit keeps working when the network drops. The [JavaScript Chat SDK](/sdk/javascript/offline-overview) keeps a cache on the device and an outbox of unsent messages. The UI Kit components read from that cache first, show each message's send state, and catch up when the connection returns. + +**Works offline:** + +- Conversations, users, groups, group members, messages, threads, reactions, the notification feed, and pinned and saved messages that the user has already loaded appear at once from the device. +- Messages, including photos, videos and files, can be sent. They are queued and go out by themselves when the connection returns. +- Unsent messages can be retried or deleted. +- Media the device has already downloaded plays and opens from the device. + +**Needs a connection:** + +- The first load of anything the user has never opened while online. +- A keyword search with no saved match. +- Editing, deleting, reacting to, pinning or saving a sent message. +- Message information, calls, and AI agent streamed replies. + +## Requirements + +| Requirement | Version | +| --- | --- | +| Angular UI Kit | `@cometchat/chat-uikit-angular` **5.3.0** or later (v5 only) | +| Chat SDK | `@cometchat/chat-sdk-javascript` **4.3.0** or later | +| Angular | 18 to 21, as for the rest of UI Kit v5 | + +The UI Kit's peer dependency on the Chat SDK stays `^4.2.0`, so upgrading the UI Kit does not force an SDK upgrade. With SDK 4.2.x, `setOfflineConfig()` is ignored and the UI Kit works online only. Install SDK 4.3.0 or later to use offline support: + +```bash +npm install @cometchat/chat-uikit-angular@5.3.0 @cometchat/chat-sdk-javascript@4.3.0 +``` + +The browser needs IndexedDB for the cache. Where it is missing or blocked (for example, in some private-browsing modes), offline support stays off for that session. See [Supported runtimes](/sdk/javascript/offline-enable#supported-runtimes). + + +UI Kit v4 has no offline support. Turning on the SDK's offline support under UI Kit v4 is not supported. + + +## Enable Offline Support + +Offline support is **off by default**. Call `setOfflineConfig()` on the `UIKitSettingsBuilder` with `enabled: true`, before `CometChatUIKit.init()`. The UI Kit passes the object to the Chat SDK's `AppSettingsBuilder.setOfflineConfig()` unchanged. + +```ts title="src/main.ts" expandable +import { bootstrapApplication } from "@angular/platform-browser"; +import { App } from "./app/app"; +import { appConfig } from "./app/app.config"; +import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-angular"; + +const UIKitSettings = new UIKitSettingsBuilder() + .setAppId("APP_ID") + .setRegion("REGION") + .setAuthKey("AUTH_KEY") + .subscribePresenceForAllUsers() + .setOfflineConfig({ + enabled: true, + // Any other OfflineConfig option, for example: + // encryption: true, + // maxPendingMessages: 50, + }) + .build(); + +CometChatUIKit.init(UIKitSettings) + ?.then(() => { + bootstrapApplication(App, appConfig).catch((err) => console.error(err)); + }) + .catch((error) => { + console.error("CometChat UI Kit initialization failed:", error); + }); +``` + +The config is typed as `CometChatOfflineConfig`. It lists exactly the SDK's options, so a misspelled key such as `enable` is a compile error. For what each option does and its default, see [OfflineConfig options](/sdk/javascript/offline-reference#offlineconfig-options). For encryption and media caching, see [Encrypt the Cache](/sdk/javascript/offline-encryption) and [Media Caching](/sdk/javascript/offline-media-caching). + + +Offline support turns on only with an explicit `enabled: true`. A config without `enabled` leaves it off. + + +Whether offline support is running can change after init: it is off before anyone logs in, and the SDK can turn it off, for example when the encrypted cache cannot open. The components check `CometChat.isOfflineEnabled()` each time they need to. Do the same in your own code instead of reading back the config you passed. See [Verify it is active](/sdk/javascript/offline-enable). + +## How the Components Behave Offline + +### Lists + +This applies to [Conversations](/ui-kit/angular/components/cometchat-conversations), [Users](/ui-kit/angular/components/cometchat-users), [Groups](/ui-kit/angular/components/cometchat-groups), [Group Members](/ui-kit/angular/components/cometchat-group-members), [Reaction List](/ui-kit/angular/components/cometchat-reaction-list), [Notification Feed](/ui-kit/angular/components/notification-feed), [Pinned Messages](/ui-kit/angular/components/cometchat-pinned-messages) and [Saved Messages](/ui-kit/angular/components/cometchat-saved-messages). + +- **Saved rows first.** The list paints the rows saved on the device straight away, then merges in the server page when it arrives. +- **Offline with nothing saved.** The list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, reactions, notifications, messages), with no Retry button. It loads once by itself when the connection is back. +- **Rows on screen stay.** If a load fails while rows are showing, the rows stay and nothing is drawn over them. +- **Reconnect.** The SDK catches every list up. The components make no extra fetch of their own, and messages that arrived meanwhile appear without a sound and without extra unread counts. + +### Search + +- **Keyword search.** A search with a keyword that cannot reach the server, and has no saved match, shows **Connect to search** with a second line, **Search needs an internet connection.** It runs again once by itself when the connection is back. +- **Filters only.** A list opened with a filter and no keyword (online users, tags, a request builder with no search term) is a plain list, not a search. Offline with nothing saved, it shows that list's **Connect to load …** text. +- **The [Search](/ui-kit/angular/components/cometchat-search) component** searches conversations and messages together: + - It shows **Connect to search** only when every failed request was a not-connected one. + - A search by filters alone is answered from the device. When nothing is saved, it shows the plain empty state (**No Results**), not **Connect to search**. + - It waits for both scopes before it treats a failure as an error. See [Errors and Callbacks](#errors-and-callbacks). + +### Message List and Threads + +[Message List](/ui-kit/angular/components/cometchat-message-list) behaves as follows: + +- **Cached history.** A chat opens with the messages saved on the device, then updates with the server page. A chat opened offline with nothing saved shows **Connect to load messages**. +- **Connect to load more.** Offline, scrolling past the saved messages shows a tappable **Connect to load more** row at that edge: at the top for older messages, at the bottom for newer ones. The list never ends there. When the connection is back, the page behind the row loads once by itself, older edge first. Tapping the row or scrolling to that end also loads it. +- **Jump to a message.** With `goToMessageId`, a saved message opens with the saved messages around it. Offline, if the target is neither saved nor reachable, the chat opens on its newest saved page as a normal offline open, with no error. +- **Start from unread.** With `startFromUnreadMessages`, the chat opens on its newest page from the device, then moves to the unread divider. +- **Threads.** A thread view shows the same offline states as the main list. See [Limitations](#limitations) for what is saved for threads. + + +The message list's default request lets the SDK save each page for offline use. If you pass your own `messagesRequestBuilder` with extra filters, the request is sent exactly as you built it. The SDK may then not save its pages, so that chat has less to show offline. See [Cache-supported filters](/sdk/javascript/offline-reference#cache-supported-filters). + + +### Composer and Sending + +[Message Composer](/ui-kit/angular/components/cometchat-message-composer) and Message List handle sends as follows: + +- **Queued sends.** A message sent offline appears at once with a clock icon and **Not sent yet**. It is queued, not failed, and sends by itself when the connection returns. +- **Failed sends.** A message the server refuses shows the error mark and **Not sent. Tap to retry**, whatever the reason. A failed message is never retried automatically. +- **Retry and Delete.** Every own message that is waiting, sending, or failed offers only **Retry** and **Delete** in its menu. Reply, thread, react, edit, pin, save, info and copy all need a sent message, so they are hidden until it is sent. + - **Delete** shows the usual confirmation, then removes the message from this device for good, offline too, and it stays removed after a restart. + - Retry or Delete on a message whose send is already under way changes nothing, and a short **Sending… try again in a moment** notice shows. +- **Queue limits.** When the outbox is full (`maxPendingMessages`), or a file is larger than the offline budget, the message shows as not sent with one notice: **Too many messages waiting to send** or **File too large to send offline**. Retry sends it once there is room. +- **Media attachments.** A photo, video or file picked or dropped while offline goes straight to the outbox: its row shows at once and it uploads on reconnect. Online, the attachment tray works as before. + +For how the SDK queues sends, see [Send While Offline](/sdk/javascript/offline-send). + +### Media + +- Images, videos, audio and files that were downloaded while online open from the device when offline. +- An image or video with no saved copy shows **Available when online** while offline. +- Online, tapping an image, video or file the device has no copy of downloads and caches it. Playing an audio file does the same; the audio plays from its URL and uses the saved copy next time. + +### Edits, Deletes and Reactions + +Editing, deleting, reacting to, pinning and saving a **sent** message need a connection. Offline, they end with the usual error and leave nothing half-done. Edits, deletes and reactions made on other devices sync in when the connection returns. + +### Presence + +Nobody shows as online while the connection is down, in any list or header, and screen readers do not announce anyone as online. Presence comes back with the connection. + +### Logout and Switching Users + +The cache belongs to one user. Logging out, a session expiring, or logging in as a different user deletes the cache, including any unsent messages. You don't clear anything yourself. See [One cache per user](/sdk/javascript/offline-overview#one-cache-per-user). + +## Offline States and Texts + +These are the texts the components show in their offline states. Each one is a localization key, so you can change the text with `CometChatLocalize.addTranslation()`, as for any other string. See [Localization](/ui-kit/angular/customization/localization). + +| Text | Where it appears | Key | +| --- | --- | --- | +| Connect to load chats | Conversations | `conversations_connect_to_load` | +| Connect to load users | Users | `users_connect_to_load` | +| Connect to load groups | Groups | `groups_connect_to_load` | +| Connect to load members | Group Members | `group_members_connect_to_load` | +| Connect to load messages | Message List, threads, Pinned Messages, Saved Messages | `message_list_connect_to_load` | +| Connect to load reactions | Reaction List | `reaction_list_connect_to_load` | +| Connect to load notifications | Notification Feed | `notification_feed_connect_to_load` | +| Connect to search | Searchable lists | `conversations_connect_to_search` | +| Connect to search | Search component | `search_connect_to_search_messages` | +| Search needs an internet connection. | Second line under **Connect to search** | `list_connect_to_search_subtitle` | +| Connect to load more | Message List edge row | `message_list_connect_to_load_more` | +| Not sent yet | Unsent own message | `message_list_not_sent_yet` | +| Not sent. Tap to retry | Failed own message | `message_list_not_sent_tap_to_retry` | +| Sending… try again in a moment | Retry or Delete during a send | `message_list_send_in_flight` | +| Too many messages waiting to send | Outbox full | `message_list_queue_full` | +| File too large to send offline | File over the offline budget | `message_list_file_too_large_offline` | +| Available when online | Image or video with no saved copy | `message_bubble_media_available_when_online` | + +```typescript +import { CometChatLocalize } from "@cometchat/chat-uikit-angular"; + +CometChatLocalize.addTranslation({ + "en-US": { + "conversations_connect_to_load": "You're offline. Reconnect to see your chats.", + "message_list_connect_to_load_more": "Reconnect to load more", + }, +}); +``` + +## Errors and Callbacks + +### The error output + +The list components' `(error)` output follows one rule while offline support is on: + +| Situation | What shows | `(error)` | +| --- | --- | --- | +| Offline, nothing on screen | The offline state (**Connect to load …**), or your `errorView` if you passed one | Fires once | +| Keyword search offline, no saved match | **Connect to search** | Does not fire | +| Online, a real error, nothing on screen | The error view with Retry, or your `errorView`. Not reloaded by itself | Fires once | +| Rows on screen, offline | Rows stay | Does not fire | +| Rows on screen, online, a load the user or app started (opening, refresh, search, filter, paging, jump to a message, Retry) | Rows stay | Fires once | +| Rows on screen, online, a load the UI Kit started (reconnect, sync, cache reset) | Rows stay | Does not fire | +| The server answers with an empty list | The empty view, or your `emptyView` | Does not fire | + +In the Search component with both scopes: + +- If both scopes fail, at least one for a real reason, the error view shows and `(error)` fires for each. +- If one scope fails and the other has results, the results stay and `(error)` fires once for the failed scope. +- If one scope fails and nothing is shown, the plain empty state (**No Results**, or your own empty view) shows, with no `(error)` and no run on reconnect. + +### Send promises + +`CometChatUIKit.sendTextMessage()`, `sendMediaMessage()` and `sendCustomMessage()` behave as follows when offline support is on: + +- They resolve when the message is sent. +- They reject on a final failure. +- They never reject only because the message was queued. +- When the user logs out, switches user, or the offline cache resets before a queued message is sent, the promise rejects once, quietly, with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. The components show no error for it. Treat it as "dropped", not as a failure to report. + +```typescript +import { CometChat } from "@cometchat/chat-sdk-javascript"; +import { CometChatUIKit } from "@cometchat/chat-uikit-angular"; + +const message = new CometChat.TextMessage("UID", "Hello", CometChat.RECEIVER_TYPE.USER); + +CometChatUIKit.sendTextMessage(message) + .then((sent) => console.log("Sent", sent)) + .catch((error) => { + if (error?.code === "ERROR_OFFLINE_MESSAGE_DISCARDED") return; // logout or cache reset + console.error("Send failed", error); + }); +``` + +See [Error codes](/sdk/javascript/offline-reference#error-codes) for the other offline codes. + +### Events + +Two events on `CometChatMessageEvents` fire only while offline support is on: + +| Event | Payload | When | +| --- | --- | --- | +| `ccMessageSendStateChanged` | `IMessageSendStateChanged`: `{ message, state, reason? }`, where `state` is `MessageSendState`: `'sending'`, `'sent'`, `'failed'` or `'discarded'`. `reason` is the SDK's failure reason for `failed` and `discarded` | Once per send-state change of an own message | +| `ccOfflineCacheReset` | `IOfflineCacheReset`: `{ reason, pendingMessagesLost }`, where `pendingMessagesLost` is `null` when the SDK cannot know | The SDK rebuilt its offline cache. The lists reload | + +```typescript +import { Component, DestroyRef, OnInit, inject } from "@angular/core"; +import { takeUntilDestroyed } from "@angular/core/rxjs-interop"; +import { + CometChatMessageEvents, + IMessageSendStateChanged, + IOfflineCacheReset, +} from "@cometchat/chat-uikit-angular"; + +@Component({ selector: "app-offline-log", standalone: true, template: "" }) +export class OfflineLogComponent implements OnInit { + private destroyRef = inject(DestroyRef); + + ngOnInit(): void { + CometChatMessageEvents.ccMessageSendStateChanged + .pipe(takeUntilDestroyed(this.destroyRef)) + .subscribe(({ message, state, reason }: IMessageSendStateChanged) => { + console.log("Send state", message.getMuid(), state, reason); + }); + + CometChatMessageEvents.ccOfflineCacheReset + .pipe(takeUntilDestroyed(this.destroyRef)) + .subscribe(({ reason, pendingMessagesLost }: IOfflineCacheReset) => { + console.log("Cache reset", reason, pendingMessagesLost); + }); + } +} +``` + +`ccMessageSent` keeps its contract: one `inprogress`, then one `success` or `error` per message. A queued message stays `inprogress` until it is sent. + + +**Group events can come from catch-up.** With offline support on, group actions that happened while the user was away (a kick, a ban, a scope change, or the user leaving from another device) arrive in the SDK's catch-up. The UI Kit then also emits `CometChatGroupEvents.ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberScopeChanged` and `ccGroupLeft`, with the same payload as before. These events no longer always mean "this user just did it". Check `kickedBy` or `message.getActionBy()` before you show a toast for the user's own action, and handle the case where the kicked user is the signed-in user, for example by closing the chat. + + +### Search service signals + +[`SearchConversationsService`](/ui-kit/angular/api-reference/search-conversations-service) and [`SearchMessagesService`](/ui-kit/angular/api-reference/search-messages-service) expose offline state as signals. Both are always `false` while offline support is off. + +| Member | Type | Meaning | +| --- | --- | --- | +| `connectToSearch` | `WritableSignal` | `true` when a keyword search could not reach the server and nothing saved matches. `fetchState` is `empty`, `search()` does not reject, and the search runs once more by itself when the connection is back. | +| `searchFailed` | `WritableSignal` | `true` when a search inside the Search component failed with a real error and nothing is shown. `fetchState` is `empty` and the Search component decides, once both scopes answer, whether to show the error view or the empty state. Always `false` when you use the service outside the Search component. | +| `reconnectSearchError$` | `Subject` | Emits when the search the service re-ran by itself on reconnect fails. A search you start rejects to you instead. | + +```typescript +import { Component, computed, inject } from "@angular/core"; +import { SearchConversationsService } from "@cometchat/chat-uikit-angular"; + +@Component({ + selector: "app-conversation-search", + standalone: true, + providers: [SearchConversationsService], + template: ` + + @if (offlineMiss()) { +

Connect to search

+ } + `, +}) +export class ConversationSearchComponent { + private search = inject(SearchConversationsService); + offlineMiss = computed(() => this.search.connectToSearch()); + + run(keyword: string): void { + this.search.search(keyword, []).catch((error) => console.error(error)); + } +} +``` + +## Customization + +### Hide the offline notices + +`cometchat-message-list` and `cometchat-conversations` take a `hideOfflineNotices` input (default `false`): + +| Component | Notices it hides | +| --- | --- | +| `cometchat-message-list` | The notices about unsent messages: a message removed, messages not sent, the outbox full, and a cache reset | +| `cometchat-conversations` | The notice shown when the offline cache was reset and unsent messages were, or may have been, lost | + +```html + + +``` + +The input has no effect while offline support is off. + +### Your own empty and error views + +An `errorView` you pass to a list shows instead of the built-in offline state (**Connect to load …**). An `emptyView` shows when the server answers with an empty list, and in the Search component's plain empty state. + +### Your own "Connect to load more" control + +The built-in **Connect to load more** row calls the message list's public `retryOfflineRead()` method, which reads the page behind the blocked edge. To trigger it from your own control, call it on a `viewChild` reference: + +```typescript +import { Component, viewChild } from "@angular/core"; +import { CometChat } from "@cometchat/chat-sdk-javascript"; +import { CometChatMessageListComponent } from "@cometchat/chat-uikit-angular"; + +@Component({ + selector: "app-chat", + standalone: true, + imports: [CometChatMessageListComponent], + template: ` + + + `, +}) +export class ChatComponent { + user!: CometChat.User; + private list = viewChild.required("list"); + + loadMore(): void { + this.list().retryOfflineRead(); + } +} +``` + +### Message options on unsent messages + +The **Retry** and **Delete** options on an unsent message use the ids `CometChatUIKitConstants.MessageOption.retryMessage` and `CometChatUIKitConstants.MessageOption.discardMessage`. Use them to find these options when you customize the message menu. + +### Theming + +The offline states use the theme's existing colors and fonts. Override them with these CSS variables: + +| Variable | Default | Used for | +| --- | --- | --- | +| `--cometchat-message-bubble-offline-pending-color` | `var(--cometchat-text-color-secondary)` | **Not sent yet** next to the clock | +| `--cometchat-message-bubble-offline-pending-font` | `var(--cometchat-font-caption1-regular)` | **Not sent yet** | +| `--cometchat-message-bubble-offline-retry-color` | `var(--cometchat-error-color)` | **Not sent. Tap to retry** | +| `--cometchat-message-bubble-offline-retry-font` | `var(--cometchat-font-caption1-regular)` | **Not sent. Tap to retry** | +| `--cometchat-message-bubble-offline-retry-focus-outline-color` | `var(--cometchat-primary-color)` | Keyboard focus ring on **Not sent. Tap to retry** | +| `--cometchat-message-bubble-offline-failed-tint` | `transparent` | Background of a failed unsent message | +| `--cometchat-message-bubble-offline-failed-icon-color` | `var(--cometchat-error-color)` | Failed mark on an unsent message | +| `--cometchat-message-list-offline-footer-color` | `var(--cometchat-primary-color)` | **Connect to load more** | +| `--cometchat-message-list-offline-footer-font` | `var(--cometchat-font-caption1-medium)` | **Connect to load more** | +| `--cometchat-message-list-offline-notice-background` | `var(--cometchat-background-color-02)` | Message list notices | +| `--cometchat-message-list-offline-notice-border` | `1px solid var(--cometchat-border-color-light)` | Message list notices | +| `--cometchat-message-list-offline-notice-color` | `var(--cometchat-text-color-primary)` | Message list notices | +| `--cometchat-message-list-offline-notice-font` | `var(--cometchat-font-caption1-regular)` | Message list notices | +| `--cometchat-conversations-offline-notice-background` | `var(--cometchat-background-color-02)` | Conversation list notice | +| `--cometchat-conversations-offline-notice-border` | `1px solid var(--cometchat-border-color-light)` | Conversation list notice | +| `--cometchat-conversations-offline-notice-color` | `var(--cometchat-text-color-primary)` | Conversation list notice | +| `--cometchat-conversations-offline-notice-font` | `var(--cometchat-font-caption1-regular)` | Conversation list notice | +| `--cometchat-conversations-receipt-error-color` | `var(--cometchat-error-color)` | Failed mark on a conversation's last-message preview | +| `--cometchat-image-bubble-offline-placeholder-color` | `var(--cometchat-text-color-secondary)` | **Available when online** on an image | +| `--cometchat-image-bubble-offline-placeholder-font` | `var(--cometchat-font-caption1-regular)` | **Available when online** on an image | +| `--cometchat-video-bubble-offline-placeholder-color` | `var(--cometchat-text-color-secondary)` | **Available when online** on a video | +| `--cometchat-video-bubble-offline-placeholder-font` | `var(--cometchat-font-caption1-regular)` | **Available when online** on a video | + +```css +.cometchat { + --cometchat-message-list-offline-footer-color: #0b7bff; + --cometchat-message-bubble-offline-failed-tint: rgba(244, 70, 73, 0.06); +} +``` + +See [Theming](/ui-kit/angular/customization/theming) for where to put overrides. + +## With Offline Support Turned Off + +Apps that don't turn offline support on keep today's behavior: no cache, no outbox, no offline states, and neither offline event fires. UI Kit 5.3.0 still includes a few changes that apply with offline support off: + +- **Fixes.** On reconnect, the conversation list keeps the freshly fetched copy of a row. A failed send shows the error mark instead of the clock. The server copy of your own message keeps its quote and thread-subscribed flag. A `messagesRequestBuilder` you pass is no longer changed by the UI Kit. +- **Send error metadata.** When `CometChatUIKit.sendTextMessage()`, `sendMediaMessage()` or `sendCustomMessage()` fails, `metadata.error` is merged into the message's existing metadata instead of replacing it, so your own metadata keys survive. +- **Test identifiers.** Message rows, the message menu, conversation rows, notices, the list footer, the composer input, attachment tray tiles, and the empty and error views carry `data-testid` and `data-cc-*` attributes. They hold no message text and are not read by screen readers, but DOM snapshot tests may change. +- **Bundle size.** Chat SDK 4.3 adds about 0.54 MB to an app's initial bundle, and UI Kit 5.3.0 about 0.12 MB, whether offline support is on or off. +- **Reconnect.** As in 5.2.x, the message list makes no fetch of its own on reconnect. Messages missed during a drop appear when the chat is reopened. + +## Limitations + +- The cache holds only what the user has loaded while online, plus what syncs on reconnect. A user who has never used the app online has nothing to show offline. +- Keyword search, message information, calls and AI agent streamed replies need a connection. +- A thread opened online is not saved for offline use, because the SDK does not cache a page read with a parent message id. +- After a quick reconnect, missed messages can take up to about 10 seconds to appear. +- After a restart, the reason a message failed may be unknown. It is still offered Retry. +- If a send got no answer while the device was connected, that chat can stall until the next reconnect. +- If a send acknowledgement is lost, the message can be stored twice on the server. +- With the app open in several tabs, rebuilding the cache in one tab can drop another tab's unsent messages. That tab's rows update to match. +- The browser cache encrypts message content but not lookup metadata, and downloaded media is stored unencrypted. See [What is and isn't encrypted](/sdk/javascript/offline-encryption#what-is-and-isnt-encrypted). + +--- + +## Next Steps + + + + How the JavaScript SDK caches, queues and syncs + + + Every OfflineConfig option, listener and error code + + + The outbox, retry, discard and queue limits + + + Catch-up on reconnect and cache resets + + + Inputs, outputs and custom views + + + All UI Kit events, including the offline ones + + From 72a7fe0edd1552f9120f2f43ef6aa76b201bd0e7 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:52:16 +0530 Subject: [PATCH 2/7] docs(ENG-57591): bring Angular offline support docs up to date with UI Kit 5.3.0 - Offline Support page: match the kit and SDK as of the latest fixes. Jumps from messages on screen keep them, the reactions list keeps its counts, "Available when online" covers audio and files, the Search component reports through (searchError), your emptyView wins over Connect to search, hideOfflineNotices covers every message list notice, the notice strings and plural keys are listed, a failed edit leaves edit mode and reaches (error), and edits are never queued. Media picked offline is no longer promised. The thread limitation is scoped to Chat SDK 4.3.0. - Methods: setOfflineConfig() next to the other init settings, with an example, and what logout does to the offline cache and open sends. - Integration, Quickstart, Events, Localization, Core Features and the Conversations, Message List, Message Composer and Search pages: short offline notes and links, hideOfflineNotices and retryOfflineRead rows, and the offline events. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- .../components/cometchat-conversations.mdx | 4 ++ .../components/cometchat-message-composer.mdx | 1 + .../components/cometchat-message-list.mdx | 7 ++- .../angular/components/cometchat-search.mdx | 4 +- ui-kit/angular/core-features.mdx | 6 +- ui-kit/angular/customization/localization.mdx | 2 + ui-kit/angular/events.mdx | 4 ++ ui-kit/angular/integration.mdx | 5 ++ ui-kit/angular/methods.mdx | 21 +++++++ ui-kit/angular/offline-support.mdx | 60 ++++++++++++------- ui-kit/angular/quickstart.mdx | 3 + 11 files changed, 88 insertions(+), 29 deletions(-) diff --git a/ui-kit/angular/components/cometchat-conversations.mdx b/ui-kit/angular/components/cometchat-conversations.mdx index 056d7a26e..ef6684ad7 100644 --- a/ui-kit/angular/components/cometchat-conversations.mdx +++ b/ui-kit/angular/components/cometchat-conversations.mdx @@ -44,6 +44,7 @@ The component follows a **Hybrid Approach** architecture where: - **Context Menu**: Customizable actions for each conversation - **Sound Notifications**: Optional notification sounds for new messages - **Error Handling**: Comprehensive error handling with retry logic +- **Offline Support**: With offline support on, saved chats show at once and the list shows **Connect to load chats** offline with nothing saved. See [Offline Support](/ui-kit/angular/offline-support) ## Keyboard Accessibility @@ -177,6 +178,7 @@ export class ChatComponent { |----------|------|---------|-------------| | `hideReceipts` | `boolean` | `false` | Hide message read receipts in conversation items | | `hideError` | `boolean` | `false` | Hide error views when errors occur | +| `hideOfflineNotices` | `boolean` | `false` | Hide the notice shown when the offline cache was reset and unsent messages were lost. No effect while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#hide-the-offline-notices) | | `hidePinConversation` | `boolean` | `false` | Hide the pin/unpin option in the row context menu. See [Pinned Conversations](#pinned-conversations) | | `hideDeleteConversation` | `boolean` | `false` | Hide delete option in context menu | | `hideUserStatus` | `boolean` | `false` | Hide online/offline status indicators | @@ -1433,6 +1435,8 @@ The service includes automatic retry logic with exponential backoff for recovera - Timeout errors: Retries with increasing delays (1s, 2s, 4s) - Authentication errors: No retry (requires user action) +With [offline support](/ui-kit/angular/offline-support) on, this retry does not run. A load that fails offline with nothing on screen shows **Connect to load chats** and loads once by itself when the connection is back; a real error shows the error view with Retry. + ### Custom Error View Provide a custom error view with retry functionality: diff --git a/ui-kit/angular/components/cometchat-message-composer.mdx b/ui-kit/angular/components/cometchat-message-composer.mdx index 725ce80dd..aaaa144b4 100644 --- a/ui-kit/angular/components/cometchat-message-composer.mdx +++ b/ui-kit/angular/components/cometchat-message-composer.mdx @@ -46,6 +46,7 @@ The component follows a **Service-Based Architecture** where: - **Full Accessibility**: WCAG 2.1 Level AA compliant with keyboard navigation and screen reader support - **Extensive Customization**: Template inputs for all UI sections - **Lightweight**: No external rich text editor dependencies (100KB+ smaller bundle) +- **Offline Support**: With offline support on, text messages sent offline are queued and sent on reconnect. Edits are never queued: a failed edit leaves edit mode and reaches the `(error)` output. See [Offline Support](/ui-kit/angular/offline-support#composer-and-sending) diff --git a/ui-kit/angular/components/cometchat-message-list.mdx b/ui-kit/angular/components/cometchat-message-list.mdx index 114a2e633..e2f21226a 100644 --- a/ui-kit/angular/components/cometchat-message-list.mdx +++ b/ui-kit/angular/components/cometchat-message-list.mdx @@ -46,6 +46,7 @@ The component follows a **Hybrid Approach** architecture where: - **Text Formatters**: Extensible text formatting for mentions, links, and custom patterns - **Keyboard Navigation**: Full keyboard accessibility (WCAG 2.1 Level AA compliant) - **Sound Notifications**: notification sounds for new messages +- **Offline Support**: With offline support on, saved messages show at once, a **Connect to load more** row marks the end of what is saved, and unsent messages show **Not sent yet** or **Not sent. Tap to retry** with Retry and Delete. See [Offline Support](/ui-kit/angular/offline-support) @@ -375,6 +376,7 @@ This section provides a complete reference of all @Input properties, @Output eve | `hideAvatar` | `boolean` | `false` | Hides user avatars next to messages. | | `hideGroupActionMessages` | `boolean` | `false` | Hides system messages for group actions (member joined, left, etc.). | | `hideError` | `boolean` | `false` | Hides error views when errors occur during message loading. | +| `hideOfflineNotices` | `boolean` | `false` | Hides the offline notices about unsent messages (removed, not sent, outbox full, file too large, send under way, cache reset). No effect while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#hide-the-offline-notices). | | `hideReplyInThreadOption` | `boolean` | `false` | Hides the "Reply in Thread" option from message context menu. | | `hideThreadSubscriptionOption` | `boolean` | `false` | Hides the thread follow/unfollow option from the message context menu, without turning the feature off. See [Thread Subscription](#thread-subscription). | | `hidePinMessageOption` | `boolean` | `false` | Hides "Pin message" from the Organise flyout. See [Pin and Save](#pin-and-save). | @@ -591,6 +593,7 @@ if (this.messageList.isMessageTranslated(messageId)) { | `getMessageOptions` | `message: CometChat.BaseMessage` | `CometChatActionsIcon[]` | Returns the available context menu options for a message based on hide* inputs. | | `handleKeydown` | `event: KeyboardEvent` | `void` | Handles keyboard navigation events. Called automatically but can be triggered manually. | | `handleRetryClick` | none | `void` | Retries loading messages after an error. | +| `retryOfflineRead` | none | `void` | Offline support: reads the page behind the **Connect to load more** row, as tapping the row does. See [Offline Support](/ui-kit/angular/offline-support#your-own-connect-to-load-more-control). | | `copyMessageToClipboard` | `message: CometChat.BaseMessage` | `Promise` | Copies the text content of a message to the clipboard. | ### CalendarObject Interface @@ -4569,7 +4572,7 @@ Mobile devices require additional optimization considerations: |--------|---------|--------|--------------| | CPU | Fast | Limited | Reduce JS execution time | | Memory | 8-16GB | 2-4GB | Limit message history | -| Network | Fast | Variable | Implement offline support | +| Network | Fast | Variable | Turn on [offline support](/ui-kit/angular/offline-support) | | Battery | N/A | Critical | Reduce background processing | | Touch | N/A | Primary | Optimize touch handlers | @@ -4673,7 +4676,7 @@ Follow this checklist to ensure optimal performance: #### Mobile Optimization - [ ] Reduce page size for mobile devices - [ ] Implement touch-optimized interactions -- [ ] Consider offline support for poor connectivity +- [ ] Consider [offline support](/ui-kit/angular/offline-support) for poor connectivity - [ ] Test on actual mobile devices #### Monitoring diff --git a/ui-kit/angular/components/cometchat-search.mdx b/ui-kit/angular/components/cometchat-search.mdx index b293a2099..72b912e84 100644 --- a/ui-kit/angular/components/cometchat-search.mdx +++ b/ui-kit/angular/components/cometchat-search.mdx @@ -312,6 +312,8 @@ When both conversation and message sections are active, the component coordinate When only one scope is active (via `searchIn`, `uid`, or `guid`), that section handles its own empty/error states independently. +With [offline support](/ui-kit/angular/offline-support#search) on, a keyword search that cannot reach the server, with no saved match, shows **Connect to search** instead of an error when every failed request was a not-connected one, and runs again once when the connection is back. Errors still reach `(searchError)`. + ## Advanced Usage @@ -861,5 +863,5 @@ export class SearchDemoComponent implements OnInit { - [SearchConversationsService](/ui-kit/angular/api-reference/search-conversations-service) — Conversation search state, SDK queries, real-time listeners - [SearchMessagesService](/ui-kit/angular/api-reference/search-messages-service) — Message search state, attachment-type filtering, scoped queries - [CometChatTemplatesService](/ui-kit/angular/api-reference/templates-service) — Template resolution priority chain and global template overrides -- [Accessibility](/ui-kit/angular/accessibility#search) — Cross-component keyboard accessibility reference +- [Accessibility](/ui-kit/angular/accessibility) — Cross-component keyboard accessibility reference - [Events](/ui-kit/angular/events) — UIKit event bus for decoupled component communication diff --git a/ui-kit/angular/core-features.mdx b/ui-kit/angular/core-features.mdx index a960197a3..ff7b3496b 100644 --- a/ui-kit/angular/core-features.mdx +++ b/ui-kit/angular/core-features.mdx @@ -278,13 +278,13 @@ See the [Search Messages Guide](/ui-kit/angular/guides/search-messages) for deta ## Offline Support -Offline Support keeps the chat usable when the network drops. Chats and messages the user has already loaded appear at once from the device, messages sent offline are queued and go out by themselves on reconnect, and unsent messages can be retried or deleted. It is available from v5.3.0 with Chat SDK 4.3.0 or later, and is **off by default**. Turn it on with `setOfflineConfig({ enabled: true })` on the `UIKitSettingsBuilder`. +Offline Support keeps the chat usable when the network drops. Chats and messages the user has already loaded appear at once from the device, text messages sent offline are queued and go out by themselves on reconnect, and unsent messages can be retried or deleted. It is available from v5.3.0 with Chat SDK 4.3.0 or later, and is **off by default**. Turn it on with `setOfflineConfig({ enabled: true })` on the `UIKitSettingsBuilder`. | Component | Functionality | | --- | --- | | [cometchat-conversations](/ui-kit/angular/components/cometchat-conversations) | Shows saved chats first, then merges the server page; shows **Connect to load chats** offline with nothing saved. | -| [cometchat-message-list](/ui-kit/angular/components/cometchat-message-list) | Shows saved messages, a **Connect to load more** row past them, and **Not sent yet** / **Not sent. Tap to retry** on unsent messages, with Retry and Delete. | -| [cometchat-message-composer](/ui-kit/angular/components/cometchat-message-composer) | Queues text and media sent while offline. | +| [cometchat-message-list](/ui-kit/angular/components/cometchat-message-list) | Shows saved messages, a **Connect to load more** row past them, **Not sent yet** on queued messages and **Not sent. Tap to retry** on failed ones, with Retry and Delete. | +| [cometchat-message-composer](/ui-kit/angular/components/cometchat-message-composer) | Queues text messages sent while offline. | | [cometchat-search](/ui-kit/angular/components/cometchat-search) | Shows **Connect to search** for a keyword search that cannot run offline. | See the [Offline Support guide](/ui-kit/angular/offline-support). diff --git a/ui-kit/angular/customization/localization.mdx b/ui-kit/angular/customization/localization.mdx index ee81e9301..27a3a0a68 100644 --- a/ui-kit/angular/customization/localization.mdx +++ b/ui-kit/angular/customization/localization.mdx @@ -65,6 +65,8 @@ CometChatLocalize.addTranslation({ Existing keys are replaced; new keys are added. All other translations remain unchanged. +The texts of the offline states (**Connect to load chats**, **Not sent yet**, and so on) are keys like any other. See [Offline States and Texts](/ui-kit/angular/offline-support#offline-states-and-texts) for the list. + --- ## Using the Translate Pipe diff --git a/ui-kit/angular/events.mdx b/ui-kit/angular/events.mdx index eb8163113..4b27a76da 100644 --- a/ui-kit/angular/events.mdx +++ b/ui-kit/angular/events.mdx @@ -40,6 +40,8 @@ Events provide decoupled communication between UIKit components using a publish/ | **ccGroupMemberAdded** | Triggered when a user is added to the group. | | **ccOwnershipChanged** | Triggered when the group ownership is assigned to another group member. | +With [offline support](/ui-kit/angular/offline-support) on, `ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberScopeChanged` and `ccGroupLeft` also fire for group actions that happened while the user was away, when they arrive in the SDK's catch-up. Check `kickedBy` or `message.getActionBy()` before you treat one as the signed-in user's own action. + ## CometChatMessageEvents `CometChatMessageEvents` emits events when the logged-in user acts on a message object. This category includes both UIKit-level events and CometChat SDK listener events. @@ -53,6 +55,8 @@ Events provide decoupled communication between UIKit components using a publish/ | **ccReplyToMessage** | Triggered when the user successfully replies to a message. | | **ccMessageDeleted** | Triggered when the user successfully deletes a message. | | **ccMessageRead** | Triggered when the sent message is read by the receiver. | +| **ccMessageSendStateChanged** | Offline support only. Fires once per send-state change of an own message, with `IMessageSendStateChanged`: `{ message, state, reason? }`, where `state` is `'sending'`, `'sent'`, `'failed'` or `'discarded'`. Never fires while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#events). | +| **ccOfflineCacheReset** | Offline support only. Fires when the SDK rebuilt its offline cache, with `IOfflineCacheReset`: `{ reason, pendingMessagesLost }` (`null` when the SDK cannot know). The lists reload. See [Offline Support](/ui-kit/angular/offline-support#events). | | **ccCardActionClicked** | Triggered when a user taps an interactive element on a card (developer card or nested agent card). Carries an `ICardActionEvent` with the owning `message` (or `null` for a streaming card), the raw renderer `action`, and the originating `elementId`/`cardJson`. The UIKit forwards the action untouched and runs no behavior. See the [Card Messages guide](/ui-kit/angular/guides/card-messages#handling-card-actions). | ### SDK Listener Events diff --git a/ui-kit/angular/integration.mdx b/ui-kit/angular/integration.mdx index dc9fc019d..ba6a9b9ae 100644 --- a/ui-kit/angular/integration.mdx +++ b/ui-kit/angular/integration.mdx @@ -110,6 +110,7 @@ const UIKitSettings = new UIKitSettingsBuilder() .setAuthKey(environment.cometchat.authKey) .subscribePresenceForAllUsers() // .setCallingEnabled(true) // uncomment to enable voice/video calling + // .setOfflineConfig({ enabled: true }) // uncomment for offline support (UI Kit 5.3.0+, Chat SDK 4.3.0+) .build(); // init() is typed Promise | undefined (it returns undefined only for null settings), hence ?. @@ -129,6 +130,10 @@ CometChatUIKit.init(UIKitSettings) `init()` must resolve before you call `login()`. If you call `login()` before init completes, it will fail silently. + +Offline support is off by default. To show cached chats without a network and queue messages sent offline, add `.setOfflineConfig({ enabled: true })` to the builder. It needs UI Kit 5.3.0 or later and Chat SDK 4.3.0 or later. See [Offline Support](/ui-kit/angular/offline-support). + + --- ## Step 4 — Login diff --git a/ui-kit/angular/methods.mdx b/ui-kit/angular/methods.mdx index e2d0acec9..8a9e21068 100644 --- a/ui-kit/angular/methods.mdx +++ b/ui-kit/angular/methods.mdx @@ -30,6 +30,7 @@ Auth Key is for development/testing only. In production, generate Auth Tokens on | `setAdminHost(adminHost)` | `string` | Override the admin API host (custom/on-premise deployments) | | `setClientHost(clientHost)` | `string` | Override the client API host (custom/on-premise deployments) | | `setStorageMode(storageMode)` | `CometChat.StorageMode` | Set the storage mode for SDK data persistence | +| `setOfflineConfig(config)` | `CometChatOfflineConfig` | Turn on offline support: cached chats and messages, and queued sends. Off unless `config.enabled` is `true`. Needs UI Kit 5.3.0+ and Chat SDK 4.3.0+. See [Offline Support](#offline-support) | | `build()` | — | Returns the configured `UIKitSettings` instance | ```typescript expandable @@ -44,6 +45,24 @@ const UIKitSettings = new UIKitSettingsBuilder() .build(); ``` +### Offline Support + +`setOfflineConfig()` turns on the Chat SDK's offline support and the UI Kit's offline states. It is **off by default**, and stays off unless the config has `enabled: true`. The UI Kit passes the object to the Chat SDK's `AppSettingsBuilder.setOfflineConfig()` unchanged. It needs UI Kit 5.3.0 or later and Chat SDK 4.3.0 or later; with an older SDK the setting is ignored and the UI Kit works online only. + +```typescript +import { UIKitSettingsBuilder } from '@cometchat/chat-uikit-angular'; + +const UIKitSettings = new UIKitSettingsBuilder() + .setAppId('APP_ID') + .setRegion('REGION') + .setAuthKey('AUTH_KEY') + .subscribePresenceForFriends() + .setOfflineConfig({ enabled: true }) + .build(); +``` + +The config is typed as `CometChatOfflineConfig`, which lists the SDK's offline options (for example `maxPendingMessages`, `mediaCaching` and `encryption`). See [Offline Support](/ui-kit/angular/offline-support) for what changes in the components, and [OfflineConfig options](/sdk/javascript/offline-reference#offlineconfig-options) for every option and its default. + --- ## Methods @@ -159,6 +178,8 @@ import { CometChatUIKit } from '@cometchat/chat-uikit-angular'; CometChatUIKit.logout(); ``` +With [offline support](/ui-kit/angular/offline-support) on, logging out deletes the user's offline cache on this device, including messages that were not sent yet. Open `sendTextMessage()`, `sendMediaMessage()` and `sendCustomMessage()` promises for those messages reject with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. Logging in as a different user does the same for the previous user's cache. + --- ### Create User diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx index d36d2fa64..3dad7c89e 100644 --- a/ui-kit/angular/offline-support.mdx +++ b/ui-kit/angular/offline-support.mdx @@ -16,7 +16,7 @@ description: "Show cached chats and messages without a network and queue message | Runtime check | `CometChat.isOfflineEnabled()`. The UI Kit reads it every time, not your config | | Inputs | `hideOfflineNotices` on `cometchat-message-list` and `cometchat-conversations` | | Events | `CometChatMessageEvents.ccMessageSendStateChanged`, `CometChatMessageEvents.ccOfflineCacheReset` | -| Service signals | `connectToSearch`, `searchFailed` on `SearchConversationsService` and `SearchMessagesService` | +| Service signals | `connectToSearch`, `searchFailed`, `reconnectSearchError$` on `SearchConversationsService` and `SearchMessagesService` | | Component method | `CometChatMessageListComponent.retryOfflineRead()` | | Option ids | `CometChatUIKitConstants.MessageOption.retryMessage`, `CometChatUIKitConstants.MessageOption.discardMessage` | | Quiet rejection | `CometChatUIKit.send*` rejects with code `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset | @@ -30,15 +30,15 @@ With offline support on, the UI Kit keeps working when the network drops. The [J **Works offline:** - Conversations, users, groups, group members, messages, threads, reactions, the notification feed, and pinned and saved messages that the user has already loaded appear at once from the device. -- Messages, including photos, videos and files, can be sent. They are queued and go out by themselves when the connection returns. +- Text messages can be sent. They are queued and go out by themselves when the connection returns. - Unsent messages can be retried or deleted. -- Media the device has already downloaded plays and opens from the device. +- Media the SDK has saved on the device plays and opens from the device. **Needs a connection:** - The first load of anything the user has never opened while online. - A keyword search with no saved match. -- Editing, deleting, reacting to, pinning or saving a sent message. +- Editing, deleting, reacting to, pinning or saving a sent message. These are not queued. - Message information, calls, and AI agent streamed replies. ## Requirements @@ -47,12 +47,11 @@ With offline support on, the UI Kit keeps working when the network drops. The [J | --- | --- | | Angular UI Kit | `@cometchat/chat-uikit-angular` **5.3.0** or later (v5 only) | | Chat SDK | `@cometchat/chat-sdk-javascript` **4.3.0** or later | -| Angular | 18 to 21, as for the rest of UI Kit v5 | The UI Kit's peer dependency on the Chat SDK stays `^4.2.0`, so upgrading the UI Kit does not force an SDK upgrade. With SDK 4.2.x, `setOfflineConfig()` is ignored and the UI Kit works online only. Install SDK 4.3.0 or later to use offline support: ```bash -npm install @cometchat/chat-uikit-angular@5.3.0 @cometchat/chat-sdk-javascript@4.3.0 +npm install @cometchat/chat-uikit-angular@^5.3.0 @cometchat/chat-sdk-javascript@^4.3.0 ``` The browser needs IndexedDB for the cache. Where it is missing or blocked (for example, in some private-browsing modes), offline support stays off for that session. See [Supported runtimes](/sdk/javascript/offline-enable#supported-runtimes). @@ -110,6 +109,7 @@ This applies to [Conversations](/ui-kit/angular/components/cometchat-conversatio - **Saved rows first.** The list paints the rows saved on the device straight away, then merges in the server page when it arrives. - **Offline with nothing saved.** The list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, reactions, notifications, messages), with no Retry button. It loads once by itself when the connection is back. - **Rows on screen stay.** If a load fails while rows are showing, the rows stay and nothing is drawn over them. +- **Reaction counts.** Offline with no reactions loaded, the Reaction List shows **Connect to load reactions** and keeps its tabs, with the counts the message already carries. - **Reconnect.** The SDK catches every list up. The components make no extra fetch of their own, and messages that arrived meanwhile appear without a sound and without extra unread counts. ### Search @@ -127,7 +127,10 @@ This applies to [Conversations](/ui-kit/angular/components/cometchat-conversatio - **Cached history.** A chat opens with the messages saved on the device, then updates with the server page. A chat opened offline with nothing saved shows **Connect to load messages**. - **Connect to load more.** Offline, scrolling past the saved messages shows a tappable **Connect to load more** row at that edge: at the top for older messages, at the bottom for newer ones. The list never ends there. When the connection is back, the page behind the row loads once by itself, older edge first. Tapping the row or scrolling to that end also loads it. -- **Jump to a message.** With `goToMessageId`, a saved message opens with the saved messages around it. Offline, if the target is neither saved nor reachable, the chat opens on its newest saved page as a normal offline open, with no error. +- **Jump to a message.** A saved target opens with the saved messages around it. + - When the chat opens on a target (`goToMessageId`, or the unread anchor) that is neither saved nor reachable offline, it opens on its newest saved page as a normal offline open, with no error. + - From messages already on screen (a quoted reply, a search result), the messages on screen stay until the target is found. If it cannot be read offline, nothing changes and nothing is reported. + - If the target cannot be read for another reason, for example it was deleted, `(error)` fires once. The messages on screen stay, or an opening chat shows its newest page; with nothing to show, the error view shows. - **Start from unread.** With `startFromUnreadMessages`, the chat opens on its newest page from the device, then moves to the unread divider. - **Threads.** A thread view shows the same offline states as the main list. See [Limitations](#limitations) for what is saved for threads. @@ -140,24 +143,25 @@ The message list's default request lets the SDK save each page for offline use. [Message Composer](/ui-kit/angular/components/cometchat-message-composer) and Message List handle sends as follows: - **Queued sends.** A message sent offline appears at once with a clock icon and **Not sent yet**. It is queued, not failed, and sends by itself when the connection returns. -- **Failed sends.** A message the server refuses shows the error mark and **Not sent. Tap to retry**, whatever the reason. A failed message is never retried automatically. +- **Failed sends.** A message the server refuses shows the error mark and **Not sent. Tap to retry**, whatever the reason. A failed message stays failed until the user taps it or chooses **Retry**. - **Retry and Delete.** Every own message that is waiting, sending, or failed offers only **Retry** and **Delete** in its menu. Reply, thread, react, edit, pin, save, info and copy all need a sent message, so they are hidden until it is sent. - **Delete** shows the usual confirmation, then removes the message from this device for good, offline too, and it stays removed after a restart. - Retry or Delete on a message whose send is already under way changes nothing, and a short **Sending… try again in a moment** notice shows. -- **Queue limits.** When the outbox is full (`maxPendingMessages`), or a file is larger than the offline budget, the message shows as not sent with one notice: **Too many messages waiting to send** or **File too large to send offline**. Retry sends it once there is room. -- **Media attachments.** A photo, video or file picked or dropped while offline goes straight to the outbox: its row shows at once and it uploads on reconnect. Online, the attachment tray works as before. + - If the SDK no longer holds an unsent message (for example, its chat was removed from the cache), Retry or Delete removes it from the screen. +- **Queue limits.** When the outbox is full (`maxPendingMessages`), the message shows as not sent with the notice **Too many messages waiting to send**. A media send the SDK refuses because it would go over the offline storage budget shows **File too large to send offline**. Retry sends it once there is room. +- **Editing.** An edit is sent straight to the server and is never queued. When it fails, for example offline, the composer has already left edit mode and cleared, and the error goes to the composer's `(error)` output. For how the SDK queues sends, see [Send While Offline](/sdk/javascript/offline-send). ### Media -- Images, videos, audio and files that were downloaded while online open from the device when offline. -- An image or video with no saved copy shows **Available when online** while offline. +- Images, videos, audio, voice notes and files the SDK has saved open and play from the device when offline. By default the SDK saves incoming media as it arrives; with `mediaCaching` set to `OFF` it saves none and the UI Kit loads media from its URL. See [Media Caching](/sdk/javascript/offline-media-caching). +- An image, video, audio file or file with no saved copy shows **Available when online** while offline. - Online, tapping an image, video or file the device has no copy of downloads and caches it. Playing an audio file does the same; the audio plays from its URL and uses the saved copy next time. ### Edits, Deletes and Reactions -Editing, deleting, reacting to, pinning and saving a **sent** message need a connection. Offline, they end with the usual error and leave nothing half-done. Edits, deletes and reactions made on other devices sync in when the connection returns. +Editing, deleting, reacting to, pinning and saving a **sent** message need a connection. They are not queued: offline, each one fails with the SDK's not-connected error. Edits, deletes and reactions made on other devices sync in when the connection returns. ### Presence @@ -189,7 +193,13 @@ These are the texts the components show in their offline states. Each one is a l | Sending… try again in a moment | Retry or Delete during a send | `message_list_send_in_flight` | | Too many messages waiting to send | Outbox full | `message_list_queue_full` | | File too large to send offline | File over the offline budget | `message_list_file_too_large_offline` | -| Available when online | Image or video with no saved copy | `message_bubble_media_available_when_online` | +| Available when online | Image, video, audio or file with no saved copy | `message_bubble_media_available_when_online` | +| 1 unsent message was removed | Message List notice | `message_list_unsent_message_removed` | +| `{{count}}` message wasn't sent | Message List notice | `message_list_messages_not_sent_one`, `message_list_messages_not_sent_other` | +| `{{count}}` unsent message couldn't be recovered | Cache reset notice | `message_list_unsent_messages_lost_one`, `message_list_unsent_messages_lost_other` | +| Some unsent messages may not have been sent | Cache reset notice | `message_list_unsent_messages_maybe_lost` | + +The counted notices use plural keys: `_one` and `_other`, plus `_few` and `_many` in languages that need them. The UI Kit picks the form for the current language and falls back to `_other`, replacing `{{count}}` with the number. ```typescript import { CometChatLocalize } from "@cometchat/chat-uikit-angular"; @@ -218,11 +228,11 @@ The list components' `(error)` output follows one rule while offline support is | Rows on screen, online, a load the UI Kit started (reconnect, sync, cache reset) | Rows stay | Does not fire | | The server answers with an empty list | The empty view, or your `emptyView` | Does not fire | -In the Search component with both scopes: +The Search component reports through its `(searchError)` output instead. With both scopes: -- If both scopes fail, at least one for a real reason, the error view shows and `(error)` fires for each. -- If one scope fails and the other has results, the results stay and `(error)` fires once for the failed scope. -- If one scope fails and nothing is shown, the plain empty state (**No Results**, or your own empty view) shows, with no `(error)` and no run on reconnect. +- If both scopes fail, at least one for a real reason, the error view shows and `(searchError)` fires for each. +- If one scope fails and the other has results, the results stay and `(searchError)` fires once for the failed scope. +- If one scope fails and nothing is shown, the plain empty state (**No Results**, or your own empty view) shows, with no `(searchError)` and no run on reconnect. ### Send promises @@ -231,7 +241,7 @@ In the Search component with both scopes: - They resolve when the message is sent. - They reject on a final failure. - They never reject only because the message was queued. -- When the user logs out, switches user, or the offline cache resets before a queued message is sent, the promise rejects once, quietly, with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. The components show no error for it. Treat it as "dropped", not as a failure to report. +- When the user logs out or switches user before a queued message is sent, or the offline cache resets and loses unsent messages, the promise rejects once, quietly, with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. The components show no error for it. Treat it as "dropped", not as a failure to report. ```typescript import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -336,7 +346,7 @@ export class ConversationSearchComponent { | Component | Notices it hides | | --- | --- | -| `cometchat-message-list` | The notices about unsent messages: a message removed, messages not sent, the outbox full, and a cache reset | +| `cometchat-message-list` | Every message list notice: a message removed, messages not sent, the outbox full, a file too large to send offline, **Sending… try again in a moment**, and a cache reset (the message list shows cache reset notices only when no `cometchat-conversations` is on screen) | | `cometchat-conversations` | The notice shown when the offline cache was reset and unsent messages were, or may have been, lost | ```html @@ -348,7 +358,11 @@ The input has no effect while offline support is off. ### Your own empty and error views -An `errorView` you pass to a list shows instead of the built-in offline state (**Connect to load …**). An `emptyView` shows when the server answers with an empty list, and in the Search component's plain empty state. +Your own views win over the built-in offline states: + +- An `errorView` you pass to a list shows instead of **Connect to load …** (on the Notification Feed, `errorStateView`). +- An `emptyView` you pass to Conversations, Users, Groups or Group Members shows instead of **Connect to search**. It also shows when the server answers with an empty list, and in the Search component's plain empty state. +- On Conversations, Users, Groups, Group Members and Message List, `hideError` hides **Connect to load …** along with the error view. ### Your own "Connect to load more" control @@ -380,7 +394,7 @@ export class ChatComponent { ### Message options on unsent messages -The **Retry** and **Delete** options on an unsent message use the ids `CometChatUIKitConstants.MessageOption.retryMessage` and `CometChatUIKitConstants.MessageOption.discardMessage`. Use them to find these options when you customize the message menu. +The **Retry** and **Delete** options on an unsent message use the ids `CometChatUIKitConstants.MessageOption.retryMessage` and `CometChatUIKitConstants.MessageOption.discardMessage`. Use them to find these options when you customize the message menu. `hideDeleteMessageOption` also hides **Delete** on unsent messages. ### Theming @@ -434,7 +448,7 @@ Apps that don't turn offline support on keep today's behavior: no cache, no outb - The cache holds only what the user has loaded while online, plus what syncs on reconnect. A user who has never used the app online has nothing to show offline. - Keyword search, message information, calls and AI agent streamed replies need a connection. -- A thread opened online is not saved for offline use, because the SDK does not cache a page read with a parent message id. +- Chat SDK 4.3.0 does not save a page of thread replies for offline use, so a thread opened online may have little or nothing to show offline. Later SDK versions save thread replies like the rest of the chat. - After a quick reconnect, missed messages can take up to about 10 seconds to appear. - After a restart, the reason a message failed may be unknown. It is still offered Retry. - If a send got no answer while the device was connected, that chat can stall until the next reconnect. diff --git a/ui-kit/angular/quickstart.mdx b/ui-kit/angular/quickstart.mdx index 5672e5e18..96b2cb13b 100644 --- a/ui-kit/angular/quickstart.mdx +++ b/ui-kit/angular/quickstart.mdx @@ -120,6 +120,9 @@ CometChatUIKit.init(uiKitSettings) To enable voice and video calling, install `@cometchat/calls-sdk-javascript` and add `.setCallingEnabled(true)` to the builder. Without this, call buttons are hidden across all components. See [Call Features](/ui-kit/angular/call-features) for details. + + Offline support is off by default. To turn it on, add `.setOfflineConfig({ enabled: true })` to the builder (UI Kit 5.3.0+ and Chat SDK 4.3.0+). See [Offline Support](/ui-kit/angular/offline-support). + ## Step 5: Login a User From 5a0e7819c5eb38cf98705dc0bbab663c4a3187a0 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:55:54 +0530 Subject: [PATCH 3/7] docs(ENG-57591): don't imply media picked offline is queued The queue-limit, send-promise, logout and hideOfflineNotices wording now covers text and custom messages only, so no page promises that a photo, video or file sent offline goes out on reconnect. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/angular/components/cometchat-message-list.mdx | 2 +- ui-kit/angular/methods.mdx | 2 +- ui-kit/angular/offline-support.mdx | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/ui-kit/angular/components/cometchat-message-list.mdx b/ui-kit/angular/components/cometchat-message-list.mdx index e2f21226a..11681b4e8 100644 --- a/ui-kit/angular/components/cometchat-message-list.mdx +++ b/ui-kit/angular/components/cometchat-message-list.mdx @@ -376,7 +376,7 @@ This section provides a complete reference of all @Input properties, @Output eve | `hideAvatar` | `boolean` | `false` | Hides user avatars next to messages. | | `hideGroupActionMessages` | `boolean` | `false` | Hides system messages for group actions (member joined, left, etc.). | | `hideError` | `boolean` | `false` | Hides error views when errors occur during message loading. | -| `hideOfflineNotices` | `boolean` | `false` | Hides the offline notices about unsent messages (removed, not sent, outbox full, file too large, send under way, cache reset). No effect while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#hide-the-offline-notices). | +| `hideOfflineNotices` | `boolean` | `false` | Hides the offline notices about unsent messages (removed, not sent, outbox full, send under way, cache reset, and the other notices listed on the Offline Support page). No effect while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#hide-the-offline-notices). | | `hideReplyInThreadOption` | `boolean` | `false` | Hides the "Reply in Thread" option from message context menu. | | `hideThreadSubscriptionOption` | `boolean` | `false` | Hides the thread follow/unfollow option from the message context menu, without turning the feature off. See [Thread Subscription](#thread-subscription). | | `hidePinMessageOption` | `boolean` | `false` | Hides "Pin message" from the Organise flyout. See [Pin and Save](#pin-and-save). | diff --git a/ui-kit/angular/methods.mdx b/ui-kit/angular/methods.mdx index 8a9e21068..09e461d40 100644 --- a/ui-kit/angular/methods.mdx +++ b/ui-kit/angular/methods.mdx @@ -178,7 +178,7 @@ import { CometChatUIKit } from '@cometchat/chat-uikit-angular'; CometChatUIKit.logout(); ``` -With [offline support](/ui-kit/angular/offline-support) on, logging out deletes the user's offline cache on this device, including messages that were not sent yet. Open `sendTextMessage()`, `sendMediaMessage()` and `sendCustomMessage()` promises for those messages reject with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. Logging in as a different user does the same for the previous user's cache. +With [offline support](/ui-kit/angular/offline-support) on, logging out deletes the user's offline cache on this device, including messages that were not sent yet. Open `sendTextMessage()` and `sendCustomMessage()` promises for those messages reject with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. Logging in as a different user does the same for the previous user's cache. --- diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx index 3dad7c89e..210d9b3b8 100644 --- a/ui-kit/angular/offline-support.mdx +++ b/ui-kit/angular/offline-support.mdx @@ -19,7 +19,7 @@ description: "Show cached chats and messages without a network and queue message | Service signals | `connectToSearch`, `searchFailed`, `reconnectSearchError$` on `SearchConversationsService` and `SearchMessagesService` | | Component method | `CometChatMessageListComponent.retryOfflineRead()` | | Option ids | `CometChatUIKitConstants.MessageOption.retryMessage`, `CometChatUIKitConstants.MessageOption.discardMessage` | -| Quiet rejection | `CometChatUIKit.send*` rejects with code `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset | +| Quiet rejection | `CometChatUIKit.sendTextMessage()` / `sendCustomMessage()` for a queued message rejects with code `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset | @@ -148,7 +148,7 @@ The message list's default request lets the SDK save each page for offline use. - **Delete** shows the usual confirmation, then removes the message from this device for good, offline too, and it stays removed after a restart. - Retry or Delete on a message whose send is already under way changes nothing, and a short **Sending… try again in a moment** notice shows. - If the SDK no longer holds an unsent message (for example, its chat was removed from the cache), Retry or Delete removes it from the screen. -- **Queue limits.** When the outbox is full (`maxPendingMessages`), the message shows as not sent with the notice **Too many messages waiting to send**. A media send the SDK refuses because it would go over the offline storage budget shows **File too large to send offline**. Retry sends it once there is room. +- **Queue limits.** When the outbox is full (`maxPendingMessages`), the message shows as not sent with the notice **Too many messages waiting to send**. Retry sends it once there is room. - **Editing.** An edit is sent straight to the server and is never queued. When it fails, for example offline, the composer has already left edit mode and cleared, and the error goes to the composer's `(error)` output. For how the SDK queues sends, see [Send While Offline](/sdk/javascript/offline-send). @@ -192,7 +192,7 @@ These are the texts the components show in their offline states. Each one is a l | Not sent. Tap to retry | Failed own message | `message_list_not_sent_tap_to_retry` | | Sending… try again in a moment | Retry or Delete during a send | `message_list_send_in_flight` | | Too many messages waiting to send | Outbox full | `message_list_queue_full` | -| File too large to send offline | File over the offline budget | `message_list_file_too_large_offline` | +| File too large to send offline | Message List notice | `message_list_file_too_large_offline` | | Available when online | Image, video, audio or file with no saved copy | `message_bubble_media_available_when_online` | | 1 unsent message was removed | Message List notice | `message_list_unsent_message_removed` | | `{{count}}` message wasn't sent | Message List notice | `message_list_messages_not_sent_one`, `message_list_messages_not_sent_other` | @@ -236,7 +236,7 @@ The Search component reports through its `(searchError)` output instead. With bo ### Send promises -`CometChatUIKit.sendTextMessage()`, `sendMediaMessage()` and `sendCustomMessage()` behave as follows when offline support is on: +`CometChatUIKit.sendTextMessage()` and `sendCustomMessage()` behave as follows when offline support is on: - They resolve when the message is sent. - They reject on a final failure. @@ -346,7 +346,7 @@ export class ConversationSearchComponent { | Component | Notices it hides | | --- | --- | -| `cometchat-message-list` | Every message list notice: a message removed, messages not sent, the outbox full, a file too large to send offline, **Sending… try again in a moment**, and a cache reset (the message list shows cache reset notices only when no `cometchat-conversations` is on screen) | +| `cometchat-message-list` | Every message list notice: a message removed, messages not sent, the outbox full, **File too large to send offline**, **Sending… try again in a moment**, and a cache reset (the message list shows cache reset notices only when no `cometchat-conversations` is on screen) | | `cometchat-conversations` | The notice shown when the offline cache was reset and unsent messages were, or may have been, lost | ```html From ae8a1db5a3759b3480c59a2d34cf786bf8ced5e1 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 16:57:32 +0530 Subject: [PATCH 4/7] docs(ENG-57591): drop the offline file-size notice from the Angular docs Listing "File too large to send offline" read as if smaller files could be sent offline. The strings table and the hideOfflineNotices row no longer name it. Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/angular/offline-support.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx index 210d9b3b8..10d46b526 100644 --- a/ui-kit/angular/offline-support.mdx +++ b/ui-kit/angular/offline-support.mdx @@ -192,7 +192,6 @@ These are the texts the components show in their offline states. Each one is a l | Not sent. Tap to retry | Failed own message | `message_list_not_sent_tap_to_retry` | | Sending… try again in a moment | Retry or Delete during a send | `message_list_send_in_flight` | | Too many messages waiting to send | Outbox full | `message_list_queue_full` | -| File too large to send offline | Message List notice | `message_list_file_too_large_offline` | | Available when online | Image, video, audio or file with no saved copy | `message_bubble_media_available_when_online` | | 1 unsent message was removed | Message List notice | `message_list_unsent_message_removed` | | `{{count}}` message wasn't sent | Message List notice | `message_list_messages_not_sent_one`, `message_list_messages_not_sent_other` | @@ -346,7 +345,7 @@ export class ConversationSearchComponent { | Component | Notices it hides | | --- | --- | -| `cometchat-message-list` | Every message list notice: a message removed, messages not sent, the outbox full, **File too large to send offline**, **Sending… try again in a moment**, and a cache reset (the message list shows cache reset notices only when no `cometchat-conversations` is on screen) | +| `cometchat-message-list` | All of its offline notices, including a message removed, messages not sent, the outbox full, **Sending… try again in a moment**, and a cache reset (the message list shows cache reset notices only when no `cometchat-conversations` is on screen) | | `cometchat-conversations` | The notice shown when the offline cache was reset and unsent messages were, or may have been, lost | ```html From 624d5cd730b26dd4338dc1cebc73fc45df971da4 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 19:53:55 +0530 Subject: [PATCH 5/7] docs(ENG-57591): search services are component-provided; tighten offline reconnect and searchError wording Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/angular/api-reference/introduction.mdx | 2 +- ui-kit/angular/api-reference/search-conversations-service.mdx | 3 ++- ui-kit/angular/api-reference/search-messages-service.mdx | 3 ++- ui-kit/angular/offline-support.mdx | 4 ++-- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/ui-kit/angular/api-reference/introduction.mdx b/ui-kit/angular/api-reference/introduction.mdx index 306fcbe13..56bb29146 100644 --- a/ui-kit/angular/api-reference/introduction.mdx +++ b/ui-kit/angular/api-reference/introduction.mdx @@ -10,7 +10,7 @@ description: "Reference for CometChat UIKit Angular injectable services." | Purpose | Index of the Angular UI Kit's injectable services — start here to find the right one | | Package | `@cometchat/chat-uikit-angular` v5.x | | Services | `ChatStateService` · `FormatterConfigService` · `MessageBubbleConfigService` · `RichTextEditorService` · `SearchConversationsService` · `SearchMessagesService` · `CometChatTemplatesService` | -| Injected with | `inject()` — all are `providedIn: 'root'` | +| Injected with | `inject()` — all are `providedIn: 'root'` except `SearchConversationsService` and `SearchMessagesService`, which are component-provided (add them to your component's `providers`) | | Full list | See [Services](#services) | diff --git a/ui-kit/angular/api-reference/search-conversations-service.mdx b/ui-kit/angular/api-reference/search-conversations-service.mdx index 7581e143f..6380c8b0e 100644 --- a/ui-kit/angular/api-reference/search-conversations-service.mdx +++ b/ui-kit/angular/api-reference/search-conversations-service.mdx @@ -11,7 +11,7 @@ description: Signal-based service for conversation search state, SDK queries, pa | Class | `SearchConversationsService` | | Package | `@cometchat/chat-uikit-angular` v5.x | | Import | `import { SearchConversationsService } from "@cometchat/chat-uikit-angular";` | -| Injected with | `private svc = inject(SearchConversationsService);` — `providedIn: 'root'`, no module wiring | +| Injected with | `private svc = inject(SearchConversationsService);` — add `providers: [SearchConversationsService]` to your component. Not root-provided: `CometChatSearch` provides its own instance. | | Key methods | `search` · `loadMore` · `attachListeners` · `detachListeners` · `reset` | | Full API | See [Methods](#methods) | | Usage | See [Usage](#usage) | @@ -134,6 +134,7 @@ import { SearchConversationsService } from '@cometchat/chat-uikit-angular'; import { CometChatSearchFilter, States } from '@cometchat/chat-uikit-angular'; @Component({ + providers: [SearchConversationsService], selector: 'app-custom-search', template: ` @switch (service.fetchState()) { diff --git a/ui-kit/angular/api-reference/search-messages-service.mdx b/ui-kit/angular/api-reference/search-messages-service.mdx index 3f6f35cf7..cba00314c 100644 --- a/ui-kit/angular/api-reference/search-messages-service.mdx +++ b/ui-kit/angular/api-reference/search-messages-service.mdx @@ -11,7 +11,7 @@ description: Signal-based service for message search state, SDK queries, attachm | Class | `SearchMessagesService` | | Package | `@cometchat/chat-uikit-angular` v5.x | | Import | `import { SearchMessagesService } from "@cometchat/chat-uikit-angular";` | -| Injected with | `private svc = inject(SearchMessagesService);` — `providedIn: 'root'`, no module wiring | +| Injected with | `private svc = inject(SearchMessagesService);` — add `providers: [SearchMessagesService]` to your component. Not root-provided: `CometChatSearch` provides its own instance. | | Key methods | `search` · `loadMore` · `reset` | | Full API | See [Methods](#methods) | | Usage | See [Usage](#usage) | @@ -110,6 +110,7 @@ import { SearchMessagesService } from '@cometchat/chat-uikit-angular'; import { CometChatSearchFilter, States } from '@cometchat/chat-uikit-angular'; @Component({ + providers: [SearchMessagesService], selector: 'app-message-search', template: ` @if (service.fetchState() === States.loaded) { diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx index 10d46b526..f9df49dff 100644 --- a/ui-kit/angular/offline-support.mdx +++ b/ui-kit/angular/offline-support.mdx @@ -110,7 +110,7 @@ This applies to [Conversations](/ui-kit/angular/components/cometchat-conversatio - **Offline with nothing saved.** The list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, reactions, notifications, messages), with no Retry button. It loads once by itself when the connection is back. - **Rows on screen stay.** If a load fails while rows are showing, the rows stay and nothing is drawn over them. - **Reaction counts.** Offline with no reactions loaded, the Reaction List shows **Connect to load reactions** and keeps its tabs, with the counts the message already carries. -- **Reconnect.** The SDK catches every list up. The components make no extra fetch of their own, and messages that arrived meanwhile appear without a sound and without extra unread counts. +- **Reconnect.** The SDK catches every list up. The components make no refresh fetch of their own, apart from the one-time reads above, and messages that arrived meanwhile appear without a sound and without extra unread counts. ### Search @@ -229,7 +229,7 @@ The list components' `(error)` output follows one rule while offline support is The Search component reports through its `(searchError)` output instead. With both scopes: -- If both scopes fail, at least one for a real reason, the error view shows and `(searchError)` fires for each. +- If both scopes fail, at least one for a real reason, the error view shows and `(searchError)` fires once for each scope that failed for a real reason. - If one scope fails and the other has results, the results stay and `(searchError)` fires once for the failed scope. - If one scope fails and nothing is shown, the plain empty state (**No Results**, or your own empty view) shows, with no `(searchError)` and no run on reconnect. From df2ebe00103d7951a67b5692c4dc5e1db0bb7e78 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 19:54:24 +0530 Subject: [PATCH 6/7] docs(ENG-57591): scope searchError to real failures when the other scope has results Co-Authored-By: Claude Opus 5.5 Co-authored-by: multica-agent --- ui-kit/angular/offline-support.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx index f9df49dff..dc0744f11 100644 --- a/ui-kit/angular/offline-support.mdx +++ b/ui-kit/angular/offline-support.mdx @@ -230,7 +230,7 @@ The list components' `(error)` output follows one rule while offline support is The Search component reports through its `(searchError)` output instead. With both scopes: - If both scopes fail, at least one for a real reason, the error view shows and `(searchError)` fires once for each scope that failed for a real reason. -- If one scope fails and the other has results, the results stay and `(searchError)` fires once for the failed scope. +- If one scope fails and the other has results, the results stay and `(searchError)` fires once for the failed scope if it failed for a real reason. - If one scope fails and nothing is shown, the plain empty state (**No Results**, or your own empty view) shows, with no `(searchError)` and no run on reconnect. ### Send promises From a1476f7c04cce777c7ee6bf996eea2283b3c2d11 Mon Sep 17 00:00:00 2001 From: rajdubey Date: Thu, 19 Nov 2026 23:10:51 +0530 Subject: [PATCH 7/7] docs(ENG-57591): Angular UI Kit supports Angular 18-22 The release kit (5.3.0, uikit-angular temp-release-offline-v5 @ ef1bdb85) declares @angular/core and @angular/common ">=18.0.0 <23.0.0" (Angular 22 support, uikit-angular #590). The docs still said 17-21 and "Angular 22 is not supported yet"; published 5.2.3 already dropped 17 (">=18.0.0 <22.0.0"). - overview, integration, quickstart: Angular 18-22 from UI Kit 5.3.0, 5.2.x up to 21; scaffold with @angular/cli@22; Node versions per Angular major (Angular 22 engines: ^22.22.3 || ^24.15.0 || >=26.0.0); dompurify peer ^3.4.17. - AppComponent note: "Angular 18-19" (17 is no longer supported). - Zoneless notes: "Angular 21+". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01XbguTt1cqFxTDQyroF6wHx --- ui-kit/angular/angular-conversation.mdx | 4 ++-- ui-kit/angular/angular-one-to-one-chat.mdx | 2 +- ui-kit/angular/angular-tab-based-chat.mdx | 4 ++-- .../formatter-config-service.mdx | 2 +- .../api-reference/templates-service.mdx | 2 +- .../cometchat-ai-assistant-chat.mdx | 2 +- .../components/cometchat-conversations.mdx | 2 +- .../components/cometchat-message-list.mdx | 4 ++-- .../customization/date-time-formatting.mdx | 2 +- .../angular/customization/migration-guide.mdx | 4 ++-- .../angular/guides/custom-message-types.mdx | 2 +- ui-kit/angular/integration.mdx | 20 +++++++++---------- ui-kit/angular/overview.mdx | 2 +- ui-kit/angular/quickstart.mdx | 8 ++++---- ui-kit/angular/troubleshooting.mdx | 6 +++--- 15 files changed, 33 insertions(+), 33 deletions(-) diff --git a/ui-kit/angular/angular-conversation.mdx b/ui-kit/angular/angular-conversation.mdx index d9e1f2327..87de3b8b3 100644 --- a/ui-kit/angular/angular-conversation.mdx +++ b/ui-kit/angular/angular-conversation.mdx @@ -42,7 +42,7 @@ Three sections working together: Wire the conversation list and message components together in your root component. The UIKit's `ChatStateService` handles all the wiring — when a user clicks a conversation, `cometchat-conversations` updates the service, and the message components automatically react to the change. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```ts title="src/app/app.ts" expandable @@ -128,7 +128,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; }) export class App implements OnInit { chatStateService = inject(ChatStateService); - isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (Angular 21 default) + isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (the default since Angular 21) ngOnInit(): void { CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => { diff --git a/ui-kit/angular/angular-one-to-one-chat.mdx b/ui-kit/angular/angular-one-to-one-chat.mdx index b51973c6c..c2480ec71 100644 --- a/ui-kit/angular/angular-one-to-one-chat.mdx +++ b/ui-kit/angular/angular-one-to-one-chat.mdx @@ -44,7 +44,7 @@ Everything goes in the root component (`App` in `src/app/app.ts`) — no extra f The app fetches a user (or group) on mount, sets it as the active entity via `ChatStateService`, and renders the three message components. The components auto-subscribe to the service — no prop passing needed. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```ts title="src/app/app.ts" expandable diff --git a/ui-kit/angular/angular-tab-based-chat.mdx b/ui-kit/angular/angular-tab-based-chat.mdx index 2c0e6c76d..5b89a27da 100644 --- a/ui-kit/angular/angular-tab-based-chat.mdx +++ b/ui-kit/angular/angular-tab-based-chat.mdx @@ -42,7 +42,7 @@ Three sections working together: Wire everything together. `ChatStateService` handles the state — `cometchat-conversations` and `cometchat-users` automatically update the service when an item is clicked, and the message components auto-subscribe. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```ts title="src/app/app.ts" expandable @@ -190,7 +190,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; }) export class App implements OnInit { chatStateService = inject(ChatStateService); - isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (Angular 21 default) + isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (the default since Angular 21) activeTab: "chats" | "calls" | "users" = "chats"; ngOnInit(): void { diff --git a/ui-kit/angular/api-reference/formatter-config-service.mdx b/ui-kit/angular/api-reference/formatter-config-service.mdx index e4013d464..5a159f946 100644 --- a/ui-kit/angular/api-reference/formatter-config-service.mdx +++ b/ui-kit/angular/api-reference/formatter-config-service.mdx @@ -97,7 +97,7 @@ Replaces the built-in default formatters with custom formatters. **Use Case:** When you want complete control over which formatters are used globally. **Example:** -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable // In app initialization (main.ts or app.ts) diff --git a/ui-kit/angular/api-reference/templates-service.mdx b/ui-kit/angular/api-reference/templates-service.mdx index 1ced859bc..1fbbf6e1e 100644 --- a/ui-kit/angular/api-reference/templates-service.mdx +++ b/ui-kit/angular/api-reference/templates-service.mdx @@ -261,7 +261,7 @@ interface MessageListTemplates { ### Shared Loading + Component-Specific Override -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable @Component({ diff --git a/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx b/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx index 6b26fbfb0..77f51cc65 100644 --- a/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx +++ b/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx @@ -74,7 +74,7 @@ import { `, }) export class AiChatComponent implements OnInit { - // A signal so the view updates when the fetch resolves — required in zoneless apps (Angular 21 default) + // A signal so the view updates when the fetch resolves — required in zoneless apps (the default since Angular 21) agentUser = signal(undefined); constructor(private streamingService: CometChatAIStreamingService) {} diff --git a/ui-kit/angular/components/cometchat-conversations.mdx b/ui-kit/angular/components/cometchat-conversations.mdx index ef6684ad7..f542d1a85 100644 --- a/ui-kit/angular/components/cometchat-conversations.mdx +++ b/ui-kit/angular/components/cometchat-conversations.mdx @@ -1129,7 +1129,7 @@ The component supports both service-level and component-level configuration. Ser Configure the ConversationsService to set defaults for all component instances: -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable import { Component, OnInit } from '@angular/core'; diff --git a/ui-kit/angular/components/cometchat-message-list.mdx b/ui-kit/angular/components/cometchat-message-list.mdx index 11681b4e8..f224ab7e1 100644 --- a/ui-kit/angular/components/cometchat-message-list.mdx +++ b/ui-kit/angular/components/cometchat-message-list.mdx @@ -88,7 +88,7 @@ import { CometChatMessageListComponent } from '@cometchat/chat-uikit-angular'; ` }) export class ChatComponent implements OnInit { - // A signal so the view updates when the fetch resolves — required in zoneless apps (Angular 21 default) + // A signal so the view updates when the fetch resolves — required in zoneless apps (the default since Angular 21) chatUser = signal(undefined); async ngOnInit(): Promise { @@ -4711,7 +4711,7 @@ This section provides comprehensive, copy-paste ready code examples for common u This example demonstrates the complete setup process for integrating CometChatMessageList into your Angular application, including CometChat initialization, user login, and component configuration. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name in `main.ts` instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name in `main.ts` instead. diff --git a/ui-kit/angular/customization/date-time-formatting.mdx b/ui-kit/angular/customization/date-time-formatting.mdx index afd1b72b0..5482bf2b3 100644 --- a/ui-kit/angular/customization/date-time-formatting.mdx +++ b/ui-kit/angular/customization/date-time-formatting.mdx @@ -201,7 +201,7 @@ const tz = CometChatLocalize.getTimezone(); -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable import { Component, OnInit, signal } from '@angular/core'; diff --git a/ui-kit/angular/customization/migration-guide.mdx b/ui-kit/angular/customization/migration-guide.mdx index 9dd66af92..17b5a3e64 100644 --- a/ui-kit/angular/customization/migration-guide.mdx +++ b/ui-kit/angular/customization/migration-guide.mdx @@ -106,7 +106,7 @@ To ensure consistency and scalability, the new theming system adheres to the **B } ``` -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript app.ts import { Component, OnInit, signal } from '@angular/core'; @@ -121,7 +121,7 @@ import { Component, OnInit, signal } from '@angular/core'; ` }) export class App implements OnInit { - // A signal, so the template refreshes from the media-query listener on zoneless Angular 21 + // A signal, so the template refreshes from the media-query listener on zoneless Angular 21+ theme = signal<'light' | 'dark'>('light'); ngOnInit(): void { diff --git a/ui-kit/angular/guides/custom-message-types.mdx b/ui-kit/angular/guides/custom-message-types.mdx index aee824546..cb418a7c2 100644 --- a/ui-kit/angular/guides/custom-message-types.mdx +++ b/ui-kit/angular/guides/custom-message-types.mdx @@ -106,7 +106,7 @@ Use `ConversationSubtitleService` to control the last message text shown in the ### Register a Subtitle Formatter -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable import { inject } from '@angular/core'; diff --git a/ui-kit/angular/integration.mdx b/ui-kit/angular/integration.mdx index ba6a9b9ae..67fa48b10 100644 --- a/ui-kit/angular/integration.mdx +++ b/ui-kit/angular/integration.mdx @@ -9,8 +9,8 @@ description: "Add CometChat to an Angular app in 6 steps: create project, instal | Field | Value | | --- | --- | | Package | `@cometchat/chat-uikit-angular` v5 | -| Angular | 17–21 (`@angular/core` / `@angular/common` `>=17.0.0 <22.0.0`). Angular 22 is not supported yet — scaffold with `npx @angular/cli@21 new` | -| Peer deps | `@cometchat/chat-sdk-javascript` ^4.2.0, `@cometchat/cards-angular` ^1.0.0, `dompurify` ^3.0.0; optional `@cometchat/calls-sdk-javascript` ^5.0.3 (calling only) | +| Angular | 18–22 (`@angular/core` / `@angular/common` `>=18.0.0 <23.0.0`, UI Kit 5.3.0 and later). UI Kit 5.2.x supports up to Angular 21 | +| Peer deps | `@cometchat/chat-sdk-javascript` ^4.2.0, `@cometchat/cards-angular` ^1.0.0, `dompurify` ^3.4.17; optional `@cometchat/calls-sdk-javascript` ^5.0.3 (calling only) | | Init | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()` | | Login | `CometChatUIKit.login("UID")` — must resolve before rendering components | | Order | `init()` → `login()` → render. Breaking this order = blank screen | @@ -35,8 +35,8 @@ You need three things from the [CometChat Dashboard](https://app.cometchat.com/) | Region | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) | You also need: -- Node.js 20.19+, 22.12+ or 24+ (what Angular 21 requires) and npm installed -- Angular 17–21. The UI Kit declares `@angular/core` `>=17.0.0 <22.0.0`, so Angular 22 — what an unversioned `ng new` / `@angular/cli@latest` now creates — fails `npm install` with `ERESOLVE` +- The Node.js version your Angular major requires (Angular 22: 22.22.3+, 24.15+ or 26+; Angular 21: 20.19+, 22.12+ or 24+) and npm installed +- Angular 18–22. UI Kit 5.3.0 and later declare `@angular/core` `>=18.0.0 <23.0.0`. UI Kit 5.2.x declares `<22.0.0`, so with 5.2.x an Angular 22 app fails `npm install` with `ERESOLVE` Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](/rest-api/chat-apis) and use `loginWithAuthToken()`. Never ship Auth Keys in client code. @@ -47,11 +47,11 @@ Auth Key is for development only. In production, generate Auth Tokens server-sid ## Step 1 — Create an Angular Project ```bash -npx @angular/cli@21 new my-app --style css --ssr false +npx @angular/cli@22 new my-app --style css --ssr false cd my-app ``` -This creates a new Angular 21 project with CSS styling and no server-side rendering. CometChat UIKit components require a browser environment. Pin the CLI major (`@21`) — the latest CLI scaffolds Angular 22, which the UI Kit does not support yet. For an existing app, check the major with `npx ng version`. +This creates a new Angular 22 project with CSS styling and no server-side rendering. CometChat UIKit components require a browser environment. Pin the CLI major (`@22`), so a future CLI doesn't scaffold an Angular major the UI Kit doesn't support yet. For an existing app, check the major with `npx ng version`. --- @@ -146,7 +146,7 @@ After init resolves, log the user in. For development, use one of the pre-create Add the login logic to your root component — replace the contents of `src/app/app.ts`. The component below uses an inline template, so the generated `app.html` and `app.css` are no longer used; you can delete them. Use `CometChatUIKit.getLoggedinUser()` to check for an existing session before calling `login()`. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name here and in `main.ts` instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name here and in `main.ts` instead. ```ts title="src/app/app.ts" expandable @@ -169,7 +169,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; `, }) export class App implements OnInit { - // A signal, not a plain boolean: Angular 21 apps are zoneless by default, so a + // A signal, not a plain boolean: Angular 21 and later apps are zoneless by default, so a // plain field changed inside a promise callback never re-renders the view. isLoggedIn = signal(false); @@ -197,7 +197,7 @@ Key points: - `getLoggedinUser()` checks for an existing session so you don't re-login unnecessarily. - `login(uid)` skips the API call if a session already exists and returns the cached user. - Components must not render until login resolves — gate rendering with `@if` on a signal. -- Keep state that changes in a promise or subscription callback in a `signal()`. New Angular 21 projects are zoneless (no `zone.js`), so assigning a plain field there (`this.isLoggedIn = true`) doesn't refresh the view — the app stays on "Loading..." and dev mode can throw `NG0100: ExpressionChangedAfterItHasBeenChecked`. Signals work the same with and without `zone.js`, so this code also runs on Angular 17–20. +- Keep state that changes in a promise or subscription callback in a `signal()`. New Angular 21+ projects are zoneless (no `zone.js`), so assigning a plain field there (`this.isLoggedIn = true`) doesn't refresh the view — the app stays on "Loading..." and dev mode can throw `NG0100: ExpressionChangedAfterItHasBeenChecked`. Signals work the same with and without `zone.js`, so this code also runs on Angular 17–20. For production, use `loginWithAuthToken()` instead of Auth Key. Generate tokens server-side via the REST API. @@ -277,7 +277,7 @@ The UIKit ships icons, images, and audio files that Angular's build system won't } ``` -Keep the entries the CLI generated (`public` on Angular 18+; `src/favicon.ico` and `src/assets` on Angular 17) — replacing the array instead of appending to it stops your own static files from being served. +Keep the entries the CLI generated (such as `public`) — replacing the array instead of appending to it stops your own static files from being served. Skipping this step will cause all UIKit icons, empty-state images, and notification sounds to fail with 404 errors. diff --git a/ui-kit/angular/overview.mdx b/ui-kit/angular/overview.mdx index aaee7d875..d87dca3fd 100644 --- a/ui-kit/angular/overview.mdx +++ b/ui-kit/angular/overview.mdx @@ -11,7 +11,7 @@ description: "Use CometChat Angular UI Kit to add standalone chat components, vo | Package | `@cometchat/chat-uikit-angular` v5.x | | Peer deps | `@cometchat/chat-sdk-javascript`, `@cometchat/cards-angular`, `dompurify` | | Calling | Optional — `@cometchat/calls-sdk-javascript` | -| Angular | v17, v18, v19, v20, v21 (peer range `>=17 <22`; Angular 22 is not supported yet) | +| Angular | v18, v19, v20, v21, v22 (peer range `>=18 <23` from UI Kit 5.3.0; UI Kit 5.2.x supports up to Angular 21) | | Localization | 19 languages built-in | | Source | [GitHub](https://github.com/cometchat/cometchat-uikit-angular/tree/v5) | | AI Skills | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) | diff --git a/ui-kit/angular/quickstart.mdx b/ui-kit/angular/quickstart.mdx index 96b2cb13b..94b068651 100644 --- a/ui-kit/angular/quickstart.mdx +++ b/ui-kit/angular/quickstart.mdx @@ -6,12 +6,12 @@ Follow these steps to integrate CometChat UIKit into your Angular application. ## Prerequisites -- Node.js 20.19+, 22.12+ or 24+ (what Angular 21 requires) -- Angular 17, 18, 19, 20 or 21 — the UI Kit declares `@angular/core` `>=17.0.0 <22.0.0` +- The Node.js version your Angular major requires (Angular 22: 22.22.3+, 24.15+ or 26+; Angular 21: 20.19+, 22.12+ or 24+) +- Angular 18, 19, 20, 21 or 22 — UI Kit 5.3.0 and later declare `@angular/core` `>=18.0.0 <23.0.0` - A CometChat account with App ID and Auth Key -Angular 22 is not supported yet: installing the UI Kit into an Angular 22 app fails with `ERESOLVE`. The latest Angular CLI scaffolds Angular 22, so create new apps with a pinned CLI: `npx @angular/cli@21 new my-app --style css --ssr false`. +Angular 22 needs UI Kit 5.3.0 or later: UI Kit 5.2.x declares `<22.0.0`, so installing it into an Angular 22 app fails with `ERESOLVE`. Create new apps with a pinned CLI major: `npx @angular/cli@22 new my-app --style css --ssr false`. ## Step 1: Install the Package @@ -85,7 +85,7 @@ The UIKit ships icons, images, and audio files that Angular's build system won't } ``` -Keep the entries the CLI generated (`public` on Angular 18+; `src/favicon.ico` and `src/assets` on Angular 17) — replacing the array instead of appending to it stops your own static files from being served. +Keep the entries the CLI generated (such as `public`) — replacing the array instead of appending to it stops your own static files from being served. Skipping this step will cause all UIKit icons, empty-state images, and notification sounds to fail with 404 errors. diff --git a/ui-kit/angular/troubleshooting.mdx b/ui-kit/angular/troubleshooting.mdx index 3f4f03e02..5c7782a10 100644 --- a/ui-kit/angular/troubleshooting.mdx +++ b/ui-kit/angular/troubleshooting.mdx @@ -23,7 +23,7 @@ description: "Common failure modes and fixes for the CometChat Angular UIKit." | Login fails with "UID not found" | UID doesn't exist in your CometChat app | Create the user via Dashboard, SDK, or API first | | Blank screen after login | Component mounted before init/login completes | Use state to conditionally render after login resolves | | Console warns "The 'allowSignalWrites' flag is deprecated" on Angular 19+ | Emitted by the UI Kit's own code; Angular 19 made the flag a no-op | Harmless — it doesn't affect behavior and needs no change in your app | -| Stuck on "Loading..." after login succeeds, or `NG0100: ExpressionChangedAfterItHasBeenChecked` (Angular 21) | New Angular 21 apps are zoneless, so a plain field set in a promise, `await` or subscription callback (`this.isLoggedIn = true`) doesn't re-render | Keep that state in a `signal()` and update it with `.set()`, as in [Integration](/ui-kit/angular/integration) Step 4. Works with and without `zone.js` | +| Stuck on "Loading..." after login succeeds, or `NG0100: ExpressionChangedAfterItHasBeenChecked` (Angular 21+) | New Angular 21+ apps are zoneless, so a plain field set in a promise, `await` or subscription callback (`this.isLoggedIn = true`) doesn't re-render | Keep that state in a `signal()` and update it with `.set()`, as in [Integration](/ui-kit/angular/integration) Step 4. Works with and without `zone.js` | | `getLoggedinUser()` returns null | User not logged in or session expired | Call `login()` or `loginWithAuthToken()` first | | `sendTextMessage()` fails | User not logged in or invalid receiver | Ensure login completes before sending messages | | Auth Key exposed in production | Using Auth Key instead of Auth Token | Switch to [Auth Token](/ui-kit/angular/methods#login-using-auth-token) for production | @@ -779,7 +779,7 @@ import { CometChat } from '@cometchat/chat-sdk-javascript'; template: `` }) export class ChatHeaderComponent implements OnInit { - // A signal so the view updates after the promise resolves (required on zoneless Angular 21) + // A signal so the view updates after the promise resolves (required on zoneless Angular 21+) selectedUser = signal(undefined); ngOnInit(): void { @@ -2200,7 +2200,7 @@ import { CometChat } from '@cometchat/chat-sdk-javascript'; template: `` }) export class ChatComposerComponent implements OnInit { - // A signal so the view updates after the promise resolves (required on zoneless Angular 21) + // A signal so the view updates after the promise resolves (required on zoneless Angular 21+) selectedUser = signal(undefined); ngOnInit(): void {