diff --git a/docs.json b/docs.json
index 40eea0779..4663677e8 100644
--- a/docs.json
+++ b/docs.json
@@ -1409,6 +1409,7 @@
"group": "Chat",
"pages": [
"ui-kit/ios/core-features",
+ "ui-kit/ios/offline-support",
"ui-kit/ios/extensions",
"ui-kit/ios/ai-features"
]
diff --git a/ui-kit/ios/compact-message-composer.mdx b/ui-kit/ios/compact-message-composer.mdx
index 464bcb5d9..e3fb69e0b 100644
--- a/ui-kit/ios/compact-message-composer.mdx
+++ b/ui-kit/ios/compact-message-composer.mdx
@@ -275,6 +275,10 @@ compactComposer.enableMultipleAttachments = false
This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/ui-kit/ios/message-list)).
+### Sending while offline
+
+With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send files from the tray while connected. With `enableMultipleAttachments = false`, a picked photo, video, audio file or document is sent as a single media message instead, and is queued like a voice note. In edit mode, tapping Send leaves edit mode at once. If the edit then fails, the message keeps its old text, `onError` fires and a notice shows, and the next message you type is sent as a new message.
+
---
## Rich Text Formatting
diff --git a/ui-kit/ios/conversations.mdx b/ui-kit/ios/conversations.mdx
index 91baf9b81..45904aec4 100644
--- a/ui-kit/ios/conversations.mdx
+++ b/ui-kit/ios/conversations.mdx
@@ -42,6 +42,7 @@ The `CometChatConversations` component displays a list of all conversations (one
"hideSearch": { "type": "Bool", "default": false },
"hideReceipts": { "type": "Bool", "default": false },
"hideUserStatus": { "type": "Bool", "default": false },
+ "hideOfflineNotices": { "type": "Bool", "default": false, "note": "Offline support only (v5.3.0+)" },
"hideGroupType": { "type": "Bool", "default": false },
"hideDeleteConversationOption": { "type": "Bool", "default": false },
"hideNavigationBar": { "type": "Bool", "default": false },
@@ -1135,6 +1136,17 @@ Hides the entire navigation bar.
| Type | `Bool` |
| Default | `false` |
+### hideOfflineNotices
+
+*Available since v5.3.0*
+
+Hides the [offline support](/ui-kit/ios/offline-support#hide-offline-notices) notices about the whole cache, such as unsent messages that couldn't be recovered. With offline support on, the list shows saved conversations first, and **Connect to load chats** when nothing is saved and there is no connection.
+
+| | |
+|---|---|
+| Type | `Bool` |
+| Default | `false` |
+
### hideReceipts
Hides read/delivered receipt indicators.
diff --git a/ui-kit/ios/core-features.mdx b/ui-kit/ios/core-features.mdx
index 803f8232a..4ce367bbb 100644
--- a/ui-kit/ios/core-features.mdx
+++ b/ui-kit/ios/core-features.mdx
@@ -18,7 +18,8 @@ description: "Review CometChat iOS UI Kit core features for messaging, media sha
{"name": "threadedConversations", "description": "Reply to specific messages in threads", "component": "CometChatThreadedMessageHeader", "enabledByDefault": true},
{"name": "threadSubscription", "description": "Subscribe to or unsubscribe from a thread's replies", "component": "CometChatMessageList", "enabledByDefault": false},
{"name": "groupChat", "description": "Create and manage group conversations", "component": "CometChatGroups", "enabledByDefault": true},
- {"name": "search", "description": "Search across conversations and messages", "component": "CometChatSearch", "enabledByDefault": true}
+ {"name": "search", "description": "Search across conversations and messages", "component": "CometChatSearch", "enabledByDefault": true},
+ {"name": "offlineSupport", "description": "Show saved chats without a connection and queue text messages until reconnect; turn on with UIKitSettings.setOfflineConfig(_:)", "component": "CometChatMessageList", "enabledByDefault": false}
],
"relatedComponents": ["CometChatMessageList", "CometChatConversations", "CometChatMessageList", "CometChatMessageComposer"]
}
@@ -827,6 +828,30 @@ class SearchViewController: UIViewController {
- [MessageHeader](/ui-kit/ios/message-header) - Search within conversation
- [Conversations](/ui-kit/ios/conversations) - Search conversations
+## Offline Support
+
+*Available since v5.3.0*
+
+Show chats the user has opened before without a connection, and queue text messages sent offline until the connection returns. Photos, videos and files picked in the attachment tray need a connection to upload. Lists show their saved rows first, unsent messages offer Retry and Delete, and every screen shows a clear "Connect to load …" state when it has nothing saved. Offline support is off by default.
+
+```swift lines
+import CometChatUIKitSwift
+import CometChatSDK
+
+let uikitSettings = UIKitSettings()
+ .set(appID: "APP_ID")
+ .set(region: "REGION")
+ .set(authKey: "AUTH_KEY")
+ .setOfflineConfig(OfflineConfig.Builder().setEnabled(true).build())
+ .build()
+
+CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
+ // Log in and show the UI Kit screens as usual.
+}
+```
+
+UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for requirements, component behaviour, texts, styling and events.
+
## Moderation
Automatically filter inappropriate content.
diff --git a/ui-kit/ios/events.mdx b/ui-kit/ios/events.mdx
index f7c01fd7d..d6479376c 100644
--- a/ui-kit/ios/events.mdx
+++ b/ui-kit/ios/events.mdx
@@ -580,6 +580,8 @@ CometChatMessageEvents.ccMessageSaved(message: savedMessage, status: .success)
| `onVoiceCall` | Voice call initiated |
| `onVideoCall` | Video call initiated |
| `onMessageError` | Message operation failed |
+| `ccMessageSendStateChanged` | An own message moved between sending, sent, failed and discarded. Only with [offline support](/ui-kit/ios/offline-support#offline-events) on |
+| `ccOfflineCacheReset` | The Chat SDK reset its offline cache. Only with [offline support](/ui-kit/ios/offline-support#offline-events) on |
## Card Events
diff --git a/ui-kit/ios/getting-started.mdx b/ui-kit/ios/getting-started.mdx
index 5db0e5e1c..6bc44a033 100644
--- a/ui-kit/ios/getting-started.mdx
+++ b/ui-kit/ios/getting-started.mdx
@@ -17,6 +17,7 @@ description: "Integrate CometChat iOS UI Kit with project setup, package install
| Auth Key | Dev/testing only. Use Auth Token in production |
| Calling | Optional. Add `CometChatCallsSDK` 5.0.4 (Up to Next Major Version) to enable |
| Dependencies | `CometChatSDK` 4.1.10+ (resolved automatically by the UI Kit package) |
+| Offline support | Optional, off by default, from UI Kit 5.3.0. UI Kit 5.3.0 and later need `CometChatSDK` 4.2.1+ (the Dependencies row above is for the 5.2.x releases). `UIKitSettings().setOfflineConfig(_:)` before `build()`. See [Offline Support](/ui-kit/ios/offline-support) |
| AI Skills | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
@@ -238,6 +239,10 @@ After running the app, you should see:
For production, use [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-auth-token) instead of Auth Key. Generate tokens server-side via the REST API.
+
+To let users open saved chats and queue text messages without a connection, add `.setOfflineConfig(OfflineConfig(enabled: true))` to `UIKitSettings` before `.build()`. Offline support is off by default and is available from UI Kit 5.3.0. UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support).
+
+
Having issues? Check the [Troubleshooting Guide](/ui-kit/ios/troubleshooting) for common problems and solutions.
diff --git a/ui-kit/ios/guide-threaded-messages.mdx b/ui-kit/ios/guide-threaded-messages.mdx
index 15198b5d0..0aa476a45 100644
--- a/ui-kit/ios/guide-threaded-messages.mdx
+++ b/ui-kit/ios/guide-threaded-messages.mdx
@@ -188,7 +188,7 @@ navigationItem.leftBarButtonItem = UIBarButtonItem(
|----------|----------|
| Parent message deleted | Display a fallback UI or disable the composer |
| No replies | Show an empty state (e.g., "No replies yet") |
-| Offline mode | Disable the composer and queue thread operations |
+| Offline mode | With [offline support](/ui-kit/ios/offline-support) on, the composer stays enabled: text replies and voice notes are queued and sent when the connection returns. Editing, deleting and reacting need a connection. Photos, videos and files picked in the attachment tray need a connection to upload |
## Error Handling
diff --git a/ui-kit/ios/llms-ios-v5.mdx b/ui-kit/ios/llms-ios-v5.mdx
index 45bffa8d2..165f9d36f 100644
--- a/ui-kit/ios/llms-ios-v5.mdx
+++ b/ui-kit/ios/llms-ios-v5.mdx
@@ -132,6 +132,7 @@ component-level corrections from the component pages on top.
- [Color Resources](/ui-kit/ios/color-resources)
## Features and extras
+- [Offline Support](/ui-kit/ios/offline-support)
- [Extensions](/ui-kit/ios/extensions)
- [Campaigns](/ui-kit/ios/campaigns)
- [Localize](/ui-kit/ios/localize)
diff --git a/ui-kit/ios/localize.mdx b/ui-kit/ios/localize.mdx
index 9e6197848..c5687127c 100644
--- a/ui-kit/ios/localize.mdx
+++ b/ui-kit/ios/localize.mdx
@@ -115,6 +115,8 @@ All localization keys used by the SDK are available in our [GitHub repository](h
- Provide custom translations for them in your app
- Keep your localization files in sync with SDK updates
+The texts that [offline support](/ui-kit/ios/offline-support) shows, such as "Connect to load chats", "Not sent yet" and "Available when online", are listed with their keys in [Offline states and texts](/ui-kit/ios/offline-support#offline-states-and-texts). Override them the same way.
+
By using the `CometChatLocalize` class, you can provide a user-friendly, localized experience to your users, enhancing the overall user experience within your application.
---
diff --git a/ui-kit/ios/message-bubble-styling.mdx b/ui-kit/ios/message-bubble-styling.mdx
index aee661bb9..6f2c393d5 100644
--- a/ui-kit/ios/message-bubble-styling.mdx
+++ b/ui-kit/ios/message-bubble-styling.mdx
@@ -28,6 +28,8 @@ There are two primary classes for styling message bubbles:
Both classes provide properties for customizing background color, border, corner radius, and specific styles for individual message types.
+With [offline support](/ui-kit/ios/offline-support#message-list-and-threads) on, an image, video, audio or file bubble with no copy on the device and no connection shows a placeholder with the file name, size and "Available when online". Style that text, and the "Not sent yet" and "Not sent. Tap to retry" lines under unsent messages, with [`CometChatMessageList.offlineStyle`](/ui-kit/ios/offline-support#offline-style).
+
---
## Properties
diff --git a/ui-kit/ios/message-composer.mdx b/ui-kit/ios/message-composer.mdx
index ff2b2845a..0dead27eb 100644
--- a/ui-kit/ios/message-composer.mdx
+++ b/ui-kit/ios/message-composer.mdx
@@ -378,6 +378,10 @@ composer.enableMultipleAttachments = false
This is composer-side only: received multi-attachment messages still render with the grouped bubbles (see [Message List](/ui-kit/ios/message-list)).
+### Sending while offline
+
+With [offline support](/ui-kit/ios/offline-support#composer-and-unsent-messages) on, text messages and voice notes sent without a connection are queued and go out when the connection returns. Files staged in the tray still need a connection to upload, so they aren't queued. The tray keeps them for that chat, so they come back when the chat is opened again. Send files from the tray while connected. With `enableMultipleAttachments = false`, a picked photo, video, audio file or document is sent as a single media message instead, and is queued like a voice note. An edit that fails keeps the edited text and the edit banner, calls `onError` and shows a notice.
+
---
## Common Patterns
diff --git a/ui-kit/ios/message-list.mdx b/ui-kit/ios/message-list.mdx
index 45c34fb35..55a265f18 100644
--- a/ui-kit/ios/message-list.mdx
+++ b/ui-kit/ios/message-list.mdx
@@ -61,6 +61,7 @@ The `CometChatMessageList` component displays a scrollable list of messages in a
"hideThreadSubscriptionOption": { "type": "Bool", "default": false },
"hideGroupActionMessages": { "type": "Bool", "default": false },
"hideNewMessageIndicator": { "type": "Bool", "default": false },
+ "hideOfflineNotices": { "type": "Bool", "default": false, "note": "Offline support only (v5.3.0+)" },
"hideEmptyView": { "type": "Bool", "default": false },
"hideErrorView": { "type": "Bool", "default": false },
"hideLoadingView": { "type": "Bool", "default": false }
@@ -262,6 +263,12 @@ Setting it to `false` renders every media message with the classic single-attach
---
+## Offline Support
+
+With [offline support](/ui-kit/ios/offline-support#message-list-and-threads) on, the list (and a thread's replies) shows saved history at once, then updates it from the server. Own messages that aren't sent yet offer only **Retry** and **Delete**. At the end of the saved messages with no connection, the list shows **Connect to load more**. Use `hideOfflineNotices` to hide the offline notices, and the static `CometChatMessageList.offlineStyle` ([Offline style](/ui-kit/ios/offline-support#offline-style)) to style them.
+
+---
+
## Actions and Events
### Callback Props
@@ -1734,6 +1741,17 @@ Hides the new message indicator.
| Type | `Bool` |
| Default | `false` |
+### hideOfflineNotices
+
+*Available since v5.3.0*
+
+Hides the [offline support](/ui-kit/ios/offline-support#hide-offline-notices) notices (a removed unsent message, a full queue, unsent messages that couldn't be recovered), the "Connect to load more" rows and the "Jump to latest" pill. Has no effect while offline support is off.
+
+| | |
+|---|---|
+| Type | `Bool` |
+| Default | `false` |
+
### hidePinMessageOption
*Available since v5.1.22*
diff --git a/ui-kit/ios/methods.mdx b/ui-kit/ios/methods.mdx
index cfc026465..870829b3e 100644
--- a/ui-kit/ios/methods.mdx
+++ b/ui-kit/ios/methods.mdx
@@ -15,6 +15,7 @@ sidebar_label: "Methods"
- **Logout:** `CometChatUIKit.logout(user:result:)`
- **Create user:** `CometChatUIKit.createUser(user:onSuccess:onError:)`
- **Send message:** `CometChatUIKit.sendTextMessage(message:onSuccess:onError:)`, `sendMediaMessage`, `sendCustomMessage`
+- **Offline support:** `UIKitSettings().setOfflineConfig(_:)` before `build()`. Off by default. See [Offline Support](/ui-kit/ios/offline-support)
- **Related:** [Getting Started](/ui-kit/ios/getting-started) · [Events](/ui-kit/ios/events) · [SDK Overview](/sdk/ios/overview)
@@ -51,6 +52,7 @@ Replace **APP_ID**, **REGION**, and **AUTH_KEY** with your CometChat App ID, Reg
| **setAutoEstablishSocketConnection** | `Boolean` | Configures if web socket connections will established automatically on app initialization or be done manually, set to true by default |
| **setAIFeatures** | `List` | Sets the AI Features that need to be added in UI Kit |
| **setExtensions** | `List` | Sets the list of extension that need to be added in UI Kit |
+| **setOfflineConfig(_:)** | `OfflineConfig` | Turns on offline support by passing the Chat SDK's `OfflineConfig` to the SDK. Off unless the config has `enabled` set to `true`. Needs UI Kit 5.3.0 or later. See [Offline Support](/ui-kit/ios/offline-support) |
#### Example
@@ -76,6 +78,38 @@ CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
+#### Enable offline support
+
+Offline support is off by default. To turn it on, pass an `OfflineConfig` from the Chat SDK to `setOfflineConfig(_:)` before you call `build()` and `CometChatUIKit.init`. Saved chats then open without a connection, and text messages sent offline are queued until the connection returns.
+
+
+
+```swift lines
+import CometChatUIKitSwift
+import CometChatSDK
+
+let uiKitSettings = UIKitSettings()
+ .set(appID: "your_appId")
+ .set(region: "your_region")
+ .set(authKey: "your_authKey")
+ .subscribePresenceForAllUsers()
+ .setOfflineConfig(OfflineConfig(enabled: true))
+ .build()
+
+CometChatUIKit.init(uiKitSettings: uiKitSettings) { result in
+ switch result {
+ case .success:
+ print("Initialization success")
+ case .failure(let error):
+ print("CometChat exception: \(error)")
+ }
+}
+```
+
+
+
+UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. See [Offline Support](/ui-kit/ios/offline-support) for the requirements, what each component does offline, and the other `OfflineConfig` options.
+
---
### Login using Auth Key
@@ -145,6 +179,10 @@ CometChatUIKit.logout(user: user) { (result) in
+
+With [offline support](/ui-kit/ios/offline-support) on, logout also ends the user's offline session. The Chat SDK deletes the user's offline cache, the UI Kit deletes the avatars it saved and clears the screens on display, and messages still waiting to be sent are discarded. A pending `sendFormMessage`, `sendCardMessage` or `sendSchedulerMessage` calls `onError` once with `ERROR_OFFLINE_MESSAGE_DISCARDED`. Logging in as a different user does the same for the previous user.
+
+
---
### Create User
@@ -172,6 +210,10 @@ CometChatUIKit.create(user: user) { result in
### Base Message
+
+With [offline support](/ui-kit/ios/offline-support) on, `sendTextMessage`, `sendMediaMessage`, `sendCustomMessage`, `sendFormMessage`, `sendCardMessage` and `sendSchedulerMessage` queue the message when there is no connection. It shows in the message list at once and is sent when the connection returns. A media message's files are copied to the device when it is queued. For what the form, card and scheduler completions report while a message is queued or discarded, see [Send completions](/ui-kit/ios/offline-support#send-completions).
+
+
#### Text Message
To send a text message to a single user or a group, use the `sendTextMessage()` function. This function requires a `TextMessage` object containing the necessary information for delivering the message.
diff --git a/ui-kit/ios/offline-support.mdx b/ui-kit/ios/offline-support.mdx
new file mode 100644
index 000000000..e32de5cbc
--- /dev/null
+++ b/ui-kit/ios/offline-support.mdx
@@ -0,0 +1,386 @@
+---
+title: "Offline Support"
+sidebarTitle: "Offline Support"
+description: "Turn on offline support in the CometChat iOS UI Kit so saved chats open without a connection, text messages queue until reconnect, and every list shows clear offline states."
+---
+
+
+
+| Field | Value |
+| --- | --- |
+| Default | Off. Nothing changes until you pass an `OfflineConfig` |
+| Enable | `UIKitSettings().setOfflineConfig(OfflineConfig(enabled: true))` before `build()`, then `CometChatUIKit.init(uiKitSettings:)` |
+| UI Kit | `CometChatUIKitSwift` 5.3.0 or later (Swift Package Manager) |
+| Chat SDK | `CometChatSDK` 4.2.1 or later (resolved by the UI Kit package) |
+| `OfflineConfig` options | [iOS SDK offline reference](/sdk/ios/offline-reference) |
+| Styling | `CometChatMessageList.offlineStyle` (`CometChatOfflineStyle`) |
+| Hide notices | `hideOfflineNotices` on `CometChatMessageList` and `CometChatConversations` |
+| Events | `ccMessageSendStateChanged`, `ccOfflineCacheReset` on `CometChatMessageEventListener` |
+| Discarded send | `CometChatUIKit.sendFormMessage` / `sendCardMessage` / `sendSchedulerMessage` call `onError` with `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset |
+
+
+
+With offline support turned on, the iOS UI Kit reads from the Chat SDK's on-device cache. Chats the user has opened before appear at once, even with no connection. Text messages and voice notes sent while offline wait in a queue and go out when the connection returns. Photos, videos, audio files and documents picked in the attachment tray (the default) need a connection: the tray uploads each file as soon as it's picked. Every list shows a clear state when it has nothing saved and can't reach the server.
+
+The UI Kit builds on the Chat SDK's offline support. This page covers what the UI Kit adds on top. For cache settings, encryption, media caching and sync, see the [iOS SDK offline docs](/sdk/ios/offline-overview).
+
+## Overview
+
+**Works offline:**
+- Conversations, users, groups and group members you have loaded before show at once from the cache.
+- Saved message history, including threads, opens without a connection.
+- New text messages and voice notes are queued and sent automatically on reconnect. So are messages sent with `CometChatUIKit.sendTextMessage`, `sendCustomMessage`, `sendFormMessage`, `sendCardMessage` and `sendSchedulerMessage`. A queued message shows a clock and **Not sent yet** until it is sent.
+- Images, video, audio and files that are on the device open from the saved copy.
+- Avatars the user has seen are kept on the device (up to 250 MB), so lists and headers show them offline.
+- After a reconnect, the SDK's catch-up brings in what changed while you were away, including a kick, ban or leave in a group.
+
+**Needs a connection:**
+- The first load of any chat or list that was never opened before.
+- Keyword search with no saved match.
+- Uploading a photo, video, audio file or document picked in the attachment tray (`enableMultipleAttachments`, on by default). The message can be sent once its files have uploaded.
+- Editing or deleting a sent message, and adding or removing a reaction. These aren't queued. When one fails, the UI Kit shows the notice **No Internet Connection. Please try again later.** (or **Something went wrong, please try again.** for any other error) and the message keeps what it had. A failed reaction is rolled back.
+- Message information, call logs, calls and AI streamed replies.
+- Media that has no copy on the device.
+
+## Requirements
+
+| Requirement | Version |
+| --- | --- |
+| CometChat iOS UI Kit (`CometChatUIKitSwift`) | 5.3.0 or later |
+| CometChat iOS Chat SDK (`CometChatSDK`) | 4.2.1 or later |
+| iOS | 15.1 or later |
+| Xcode | 16 or later |
+
+UI Kit 5.3.0, the first version with offline support, needs Chat SDK 4.2.1 or later. The UI Kit links the Chat SDK directly, so this applies to every app on UI Kit 5.3.0 or later, whether or not it turns offline on: the UI Kit is built against `CometChat.initFromSettings(offlineConfig:onSuccess:onError:)` (its own `initFromSettings` uses it), which Chat SDK 4.2.0 doesn't have. (Using the Chat SDK's offline support on its own, without the UI Kit, needs 4.2.0; see [Enable Offline Support](/sdk/ios/offline-enable).)
+
+Install or update the UI Kit with Swift Package Manager:
+
+1. Go to **File → Add Package Dependencies** (or select the existing package to update it).
+2. Enter the repository URL:
+
+```
+https://github.com/cometchat/cometchat-uikit-ios
+```
+
+3. Select **Up to Next Major Version** and enter:
+
+```
+5.3.0
+```
+
+4. Add the **CometChatUIKitSwift** product to your app target.
+
+Swift Package Manager resolves `CometChatSDK` for you. If your project pins `chat-sdk-ios` to an exact version or to **Up to Next Minor Version** on 4.1.x, package resolution fails. Change that rule to **Up to Next Major Version** from 4.2.1.
+
+
+**CocoaPods:** the latest UI Kit on CocoaPods is 5.1.18, and new releases ship through Swift Package Manager only. Offline support isn't available through CocoaPods. Move CocoaPods projects to Swift Package Manager to use it.
+
+
+## Enable offline support
+
+Offline support is **off by default**. Turn it on by passing an `OfflineConfig` to `UIKitSettings.setOfflineConfig(_:)` before you call `build()` and `CometChatUIKit.init`. The UI Kit passes the config straight to the Chat SDK and stores nothing of its own.
+
+```swift lines
+import UIKit
+import CometChatUIKitSwift
+import CometChatSDK
+
+class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+
+ var window: UIWindow?
+
+ func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
+ guard let windowScene = (scene as? UIWindowScene) else { return }
+
+ // Offline support is off unless you set a config with enabled = true.
+ let offlineConfig = OfflineConfig.Builder()
+ .setEnabled(true)
+ .build()
+
+ let uikitSettings = UIKitSettings()
+ .set(appID: "APP_ID") // Replace with your App ID
+ .set(region: "REGION") // Replace with your Region
+ .set(authKey: "AUTH_KEY") // Replace with your Auth Key (dev only)
+ .subscribePresenceForAllUsers()
+ .setOfflineConfig(offlineConfig)
+ .build()
+
+ CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
+ switch result {
+ case .success:
+ // Log in, then show the UI Kit screens as usual.
+ debugPrint("CometChat initialized with offline support")
+ case .failure(let error):
+ debugPrint("Initialization failed: \(error.localizedDescription)")
+ }
+ }
+ }
+}
+```
+
+`OfflineConfig` has more options, such as cache size, retention, the pending-message limit, encryption and media caching. Set only the ones you need. Every option is described in the [Configuration & API Reference](/sdk/ios/offline-reference#offlineconfig-options). You can also create the config with `OfflineConfig(enabled: true)`, as shown in [Enable Offline Support](/sdk/ios/offline-enable).
+
+
+Offline support is active only while a user is logged in. Call `CometChat.isOfflineEnabled()` at the moment you need to know. See [Verify it is active](/sdk/ios/offline-enable).
+
+
+## How the components behave offline
+
+### Lists: Conversations, Users, Groups and Group Members
+
+- Saved rows show first. The server page then loads and updates the list in place.
+- Rows already on screen stay when a load can't reach the server. A failure caused by having no connection shows no error view.
+- With nothing saved and no connection, the list shows an icon and **Connect to load chats** (or users, groups, members). This state has no Retry button. The list loads once by itself when the connection returns.
+- Lists opened with only a filter, such as online users, tags, a scope, banned members or unread chats, behave like a plain list and show **Connect to load …**.
+- Only a server answer of an empty page ends paging.
+
+### Search
+
+A **keyword** search with no saved match while offline shows **Connect to search** with a second line, **Search needs an internet connection.** It doesn't call `onError`. This applies to a non-empty keyword from the search box or from the list's request builder. A list opened with filters alone shows **Connect to load …** instead.
+
+`CometChatSearch` shows **Connect to search** when a keyword search can't connect, or when both the conversation and message requests fail because the device isn't connected. Results already on screen stay. A search showing the offline state runs again once when the connection returns.
+
+### Message list and threads
+
+- Saved history shows at once. Older and newer pages come from the cache first, then from the server.
+- A chat that was never saved, opened offline, shows **Connect to load messages** and calls `onError`. It loads once by itself when the connection returns.
+- When the list reaches the end of the saved messages with no connection, it shows a tappable **Connect to load more** row at that edge: older messages at the top, newer ones at the bottom. Tap it to try again. On reconnect each blocked edge loads once by itself, older first. Scrolling loads older messages again once the connection is back.
+- Jumping to a message, or starting from the first unread message, shows the list around that message first. Paging and live messages don't scroll the list away until it has settled, for at most 6 seconds. If the target isn't saved and the server can't be reached, the chat stays on its newest page.
+- When more messages arrive than one refresh can bridge, a **Jump to latest** pill appears. Your reading position stays until you tap it.
+- Images, video, audio and files show the on-device copy first. With no copy and no connection, the bubble shows a placeholder with the file name, size and **Available when online**. It redraws as the normal bubble when the connection returns. Tapping it while connected asks the SDK to download the file.
+
+### Composer and unsent messages
+
+- A text message or voice note sent while offline appears at once with a clock and **Not sent yet** under the bubble (unless the bubble already has a bottom view). It goes out automatically on reconnect.
+- Photos, videos, audio files and documents picked in the attachment tray are **not** queued. Each file starts uploading as soon as it's picked, and uploading needs a connection, so the message can't be sent until its files have uploaded. A tile whose upload failed shows a retry control: tap it to upload that file again once you're back online. With offline support on, the files staged in a chat's tray are kept on the device for that chat, so they come back when the chat is opened again. Send files from the tray while connected. With `enableMultipleAttachments = false`, a picked photo, video, audio file or document is sent as a single media message instead, and is queued like a voice note.
+- An unsent message (pending, sending or failed) offers only **Retry** and **Delete** in its long-press menu and its VoiceOver actions. It offers no Copy, Reply, React or Edit until it has been sent.
+- A failed message shows **Not sent. Tap to retry** under the bubble. Tapping that line or the status icon retries it, and VoiceOver reads the hint "Retry" on both. Every failed message can be retried, whatever the reason. Tapping the clock of a queued message retries it too; a message the SDK is sending at that moment keeps a plain clock.
+- **Retry** asks the SDK to retry the queued message, so it never creates a duplicate. A message the SDK never queued (for example, refused because the queue was full or the file was too large) is sent again as a new send.
+- **Delete** removes the unsent message. If it was already sent in the meantime, the sent copy is deleted instead.
+- If the SDK no longer holds the unsent message (for example, it was removed after you left the group), Retry and Delete remove it from the list.
+- If the message is being sent at that moment, Retry and Delete change nothing and the list shows **Sending… try again in a moment** for 4 seconds.
+- A full queue shows **Too many messages waiting to send**. A file that is too big for the offline media cache shows **File too large to send offline**. Each notice shows once per message.
+- **Editing** a message needs a connection. If the edit fails, the message keeps its old text, the composer's `onError` fires, and the UI Kit shows **No Internet Connection. Please try again later.** (or **Something went wrong, please try again.**). `CometChatMessageComposer` keeps the edited text and the edit banner so you can try again. `CometChatCompactMessageComposer` leaves edit mode as soon as you tap Send, so the next message you type is a new message, not another edit.
+
+### Presence
+
+While the SDK isn't connected (including while it is still connecting), nobody shows as online: there's no online dot in any list and no "Online" or last-seen subtitle in the message header. Presence shows again once the SDK is connected. The users list and the message header also fetch the user again after reconnecting.
+
+### Pinned, Saved, Reactions and Notifications
+
+`CometChatPinnedMessages`, `CometChatSavedMessages`, the reaction list and `CometChatNotificationFeed` follow the same rules as the other lists. Rows cached on the device show first. With nothing saved and no connection, they show **Connect to load messages**, **Connect to load reactions** or **Connect to load notifications**. The reaction list keeps its tabs visible and shows **Connect to load reactions** below them.
+
+### Logout and user switch
+
+Cached data belongs to the logged-in user. The Chat SDK deletes the user's offline cache on logout and when a different user logs in, and the UI Kit deletes the avatars it saved on the device. On logout or a user switch, the UI Kit also clears every list on screen, search results, the notification feed, the pinned and saved panels and the composer's upload tray before the next user's first frame. Any message still waiting to be sent is answered with `ERROR_OFFLINE_MESSAGE_DISCARDED`. See [Send completions](#send-completions).
+
+## Offline states and texts
+
+Override any of these texts by defining the same key in your app's `Localizable.strings`, as described in [Localize](/ui-kit/ios/localize). Every language the UI Kit ships includes them.
+
+| Text | Key | Where it appears |
+| --- | --- | --- |
+| Connect to load chats | `CONNECT_TO_LOAD_CHATS` | `CometChatConversations` with nothing saved, offline |
+| Connect to load users | `CONNECT_TO_LOAD_USERS` | `CometChatUsers` |
+| Connect to load groups | `CONNECT_TO_LOAD_GROUPS` | `CometChatGroups` |
+| Connect to load members | `CONNECT_TO_LOAD_MEMBERS` | `CometChatGroupMembers` |
+| Connect to load messages | `CONNECT_TO_LOAD_MESSAGES` | `CometChatMessageList`, `CometChatPinnedMessages`, `CometChatSavedMessages` |
+| Connect to load reactions | `CONNECT_TO_LOAD_REACTIONS` | Reaction list |
+| Connect to load notifications | `CONNECT_TO_LOAD_NOTIFICATIONS` | `CometChatNotificationFeed` |
+| Connect to search | `CONNECT_TO_SEARCH` | Keyword search in a list, offline, no saved match |
+| Connect to search | `CONNECT_TO_SEARCH_MESSAGES` | `CometChatSearch` |
+| Search needs an internet connection. | `CONNECT_TO_SEARCH_SUBTITLE` | Second line under "Connect to search" |
+| Connect to load more | `CONNECT_TO_LOAD_MORE` | Message list and threads, at a blocked edge |
+| Not sent yet | `MESSAGE_NOT_SENT_YET` | Under a queued or sending message, and the VoiceOver label of its clock |
+| Not sent. Tap to retry | `MESSAGE_NOT_SENT_TAP_TO_RETRY` | Under a failed message, and the VoiceOver label of its status icon |
+| Sending… try again in a moment | `SEND_IN_FLIGHT` | Retry or Delete on a message being sent |
+| Available when online | `MEDIA_AVAILABLE_WHEN_ONLINE` | Media placeholder |
+| Jump to latest | `JUMP_TO_LATEST` | Message list pill |
+| Too many messages waiting to send | `OFFLINE_QUEUE_FULL` | Notice when the queue is full |
+| File too large to send offline | `OFFLINE_FILE_TOO_LARGE` | Notice when media doesn't fit the cache |
+| 1 unsent message was removed | `UNSENT_MESSAGE_REMOVED` | Notice when the SDK removes a queued message, for example when a full queue drops its oldest message |
+| 1 message wasn't sent / %d messages weren't sent | `MESSAGES_NOT_SENT_ONE` / `MESSAGES_NOT_SENT_OTHER` | Message list notice when offline support turns off during a session while unsent messages are shown. They turn failed and can be retried |
+| 1 unsent message couldn't be recovered / %d unsent messages couldn't be recovered | `UNSENT_MESSAGES_LOST_ONE` / `UNSENT_MESSAGES_LOST_OTHER` | Message list and conversations notice after the SDK resets its cache |
+| Some unsent messages may not have been sent | `UNSENT_MESSAGES_MAYBE_LOST` | Notice after a cache reset with an unknown count |
+
+## Errors and callbacks
+
+### When `onError` fires
+
+With offline support on, every list follows the same rules:
+
+- **Rows on screen, no connection:** the rows stay. No error view, no `onError`.
+- **Rows on screen, any other error:** the rows stay. `onError` fires once if the user or your app started the load: opening the screen, pull to refresh, a new keyword, paging, a jump or Retry. A reload the UI Kit starts itself after a reconnect, sync or cache reset stays quiet.
+- **Nothing on screen, no connection:** the **Connect to load …** state shows, and `onError` fires once.
+- **Nothing on screen, any other error:** the error view with Retry shows, and `onError` fires.
+- **Keyword search offline with nothing saved:** **Connect to search** shows, with no `onError`.
+- **Empty server answer:** the normal empty view.
+
+`CometChatSearch` and the reaction list now also have `set(onError:)`.
+
+### Send completions
+
+`CometChatUIKit.sendFormMessage`, `CometChatUIKit.sendCardMessage` and `CometChatUIKit.sendSchedulerMessage` answer each send once:
+
+- `onSuccess` fires when the server accepts the message.
+- `onError` fires when the SDK reports a failure.
+- A send that is only queued (offline) calls neither while the session lasts.
+- If the user logs out, switches user, or the offline cache is reset before the message was sent, `onError` fires once, quietly, with the error code `ERROR_OFFLINE_MESSAGE_DISCARDED`. The UI Kit shows no error for it: the message row going away is the only visible signal.
+
+```swift lines
+import CometChatUIKitSwift
+import CometChatSDK
+
+func send(_ formMessage: FormMessage) {
+ CometChatUIKit.sendFormMessage(formMessage, onSuccess: { sent in
+ print("Form message sent: \(sent.id)")
+ }, onError: { error in
+ if error?.errorCode == "ERROR_OFFLINE_MESSAGE_DISCARDED" {
+ // Logout, user switch or cache reset before it was sent. Don't show an error.
+ return
+ }
+ print("Send failed: \(error?.errorDescription ?? "")")
+ })
+}
+```
+
+The UI Kit's own senders (the composers, stickers and smart replies) handle this case themselves and show no error.
+
+### Offline events
+
+`CometChatMessageEventListener` has two events for offline support. Both have empty default bodies, so you implement only the ones you need. An app that never turns offline support on never receives them.
+
+| Event | Fires when |
+| --- | --- |
+| `ccMessageSendStateChanged(message:state:reason:)` | An own message moves between `CometChatMessageSendState` values: `.sending`, `.sent`, `.failed` or `.discarded`. `reason` is the SDK's `CometChat.MessageFailureReason`, if any. |
+| `ccOfflineCacheReset(reason:pendingMessagesLost:)` | The Chat SDK reset its on-device cache. `pendingMessagesLost` is `CometChat.offlinePendingCountUnknown` (`-1`) when the SDK can't tell how many unsent messages were lost. |
+
+```swift lines
+import UIKit
+import CometChatUIKitSwift
+import CometChatSDK
+
+class ChatViewController: UIViewController, CometChatMessageEventListener {
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ CometChatMessageEvents.addListener("offline-listener", self)
+ }
+
+ override func viewWillDisappear(_ animated: Bool) {
+ super.viewWillDisappear(animated)
+ CometChatMessageEvents.removeListener("offline-listener")
+ }
+
+ func ccMessageSendStateChanged(message: BaseMessage, state: CometChatMessageSendState, reason: CometChat.MessageFailureReason?) {
+ print("Message \(message.muid) is now \(state)")
+ }
+
+ func ccOfflineCacheReset(reason: CometChat.OfflineCacheResetReason, pendingMessagesLost: Int) {
+ print("Offline cache reset, unsent messages lost: \(pendingMessagesLost)")
+ }
+}
+```
+
+For the SDK's own reasons and error codes, see the [Configuration & API Reference](/sdk/ios/offline-reference#error-codes).
+
+## Customization
+
+### Offline style
+
+`CometChatMessageList.offlineStyle` is a global `CometChatOfflineStyle`. Each property defaults to the theme's existing error or secondary-text tokens, so nothing changes until you set one.
+
+| Property | Type | Default | Applies to |
+| --- | --- | --- | --- |
+| `retryTextColor` | `UIColor` | `CometChatTheme.errorColor` | "Not sent. Tap to retry" |
+| `retryTextFont` | `UIFont` | `CometChatTypography.Caption1.medium` | "Not sent. Tap to retry" |
+| `failedIconTint` | `UIColor?` | `nil` (the receipt style's error tint) | Failed status icon of an unsent message |
+| `notSentYetTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Not sent yet" under a queued or sending message |
+| `notSentYetTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Not sent yet" under a queued or sending message |
+| `mediaPlaceholderTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Available when online" media placeholder |
+| `mediaPlaceholderTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Available when online" media placeholder |
+| `footerTextColor` | `UIColor` | `CometChatTheme.textColorSecondary` | "Connect to load more" rows |
+| `footerTextFont` | `UIFont` | `CometChatTypography.Caption1.regular` | "Connect to load more" rows |
+| `jumpToLatestTextColor` | `UIColor` | `CometChatTheme.white` | "Jump to latest" pill text |
+| `jumpToLatestTextFont` | `UIFont` | `CometChatTypography.Caption1.medium` | "Jump to latest" pill text |
+| `jumpToLatestBackgroundColor` | `UIColor` | `CometChatTheme.primaryColor` | "Jump to latest" pill background |
+
+```swift lines
+import UIKit
+import CometChatUIKitSwift
+
+var offlineStyle = CometChatOfflineStyle()
+offlineStyle.retryTextColor = .systemRed
+offlineStyle.footerTextColor = .systemGray
+offlineStyle.jumpToLatestTextColor = .white
+offlineStyle.jumpToLatestBackgroundColor = .systemIndigo
+offlineStyle.jumpToLatestTextFont = .systemFont(ofSize: 13, weight: .semibold)
+
+CometChatMessageList.offlineStyle = offlineStyle
+```
+
+### Hide offline notices
+
+| Property | Component | Default | Hides |
+| --- | --- | --- | --- |
+| `hideOfflineNotices` | `CometChatMessageList` | `false` | The offline notices (a removed unsent message, a full queue, unsent messages that couldn't be recovered), the "Connect to load more" rows and the "Jump to latest" pill |
+| `hideOfflineNotices` | `CometChatConversations` | `false` | Notices about the whole cache, such as unsent messages that couldn't be recovered |
+
+```swift
+let messageList = CometChatMessageList()
+messageList.hideOfflineNotices = true
+
+let conversations = CometChatConversations()
+conversations.hideOfflineNotices = true
+```
+
+### Your own empty and error views
+
+- If you set a custom error view (`errorStateView` on a list, or `set(errorView:)` on the message list), it shows instead of the UI Kit's **Connect to load …** state.
+- If you set `hideErrorView = true`, no offline state shows.
+- If you set a custom `emptyStateView`, it shows instead of **Connect to search**. `disableEmptyState = true` hides it.
+
+## With offline support turned off
+
+Apps that don't turn on offline support keep today's behaviour, with these exceptions in UI Kit 5.3.0:
+
+- **Higher Chat SDK minimum.** The UI Kit needs Chat SDK 4.2.1 or later, whether or not offline is on. An exact or up-to-next-minor pin on 4.1.x stops package resolution until you update it.
+- **New accessibility identifiers.** `accessibilityIdentifier` is now set on message rows and their menu, notices, list footers, the composer, attachment tray tiles, conversation rows, and the empty and error views. This applies to release builds too. They hold no message text and don't change what VoiceOver reads. A conversation row's identifier includes the user's uid or the group's guid. If your UI tests or view snapshots assert on these identifiers, expect them to change.
+- **Group Members and Notification Feed refresh on reconnect.** Each reconnect now reloads the first page. A list on screen is never blanked.
+- **`MessageListViewModel.add(message:)` replaces a message that is already shown** with the same server id, instead of adding a second row.
+- **A failed reaction is rolled back correctly.** The reaction count, your own reaction and its position return to what they were.
+- **The failed-send event keeps your metadata.** `ccMessageSent` with `.error` now carries the message's `metaData` with `error: true` added, instead of replacing it.
+- **Paging after a jump skips unsent rows.** The older and newer requests use the oldest and newest message that has a server id.
+- **Media links that name a file on the device are used only for your own messages.** A `file://` link or an absolute path in another user's message is no longer opened, shown or shared. Image and file bubbles now keep their downloads in `Documents/cc_media/`, so files saved earlier in the app's Documents folder are downloaded again.
+
+## Limitations and known issues
+
+- If a send acknowledgement is lost, the server can end up with one duplicate of the message.
+- After a quick reconnect, missed messages can take up to about 10 seconds to appear, because the Chat SDK waits at least 10 seconds between two catch-up syncs.
+- After an app restart, the reason a message failed may be unknown. It's still offered Retry.
+- If a send gets no answer while connected, the chat can stop updating until the next reconnect.
+- Keyword search, message information, call logs and AI streamed replies need a connection.
+- Media downloaded for offline use is stored unencrypted on the device. The message cache itself can be encrypted. See [Encrypt the Cache](/sdk/ios/offline-encryption).
+
+## Next steps
+
+
+
+ How the Chat SDK caches and syncs data
+
+
+ Every `OfflineConfig` option, listener and error code
+
+
+ The SDK's queue, retry and discard
+
+
+ Catch-up after reconnect and cache resets
+
+
+ Message list properties and styling
+
+
+ Override the offline texts
+
+
diff --git a/ui-kit/ios/search.mdx b/ui-kit/ios/search.mdx
index abad28b51..73e35ad8e 100644
--- a/ui-kit/ios/search.mdx
+++ b/ui-kit/ios/search.mdx
@@ -31,7 +31,8 @@ The `CometChatSearch` component is a powerful and customizable search interface
"callbacks": {
"onConversationClicked": "(Conversation, IndexPath) -> Void (assignable property)",
"onMessageClicked": "(BaseMessage) -> Void (assignable property)",
- "note": "No onBack / onError / onEmpty. Failures and empty results are VIEWS: set(errorView:), set(emptyView:), plus errorStateTitleText / errorStateSubTitleText."
+ "onError": "(CometChatException) -> Void (set(onError:); called only with offline support on)",
+ "note": "No onBack / onEmpty. Failures and empty results are VIEWS: set(errorView:), set(emptyView:), plus errorStateTitleText / errorStateSubTitleText. With offline support on, set(onError:) is also called once for a failed search."
},
"visibility": {
"hideUserStatus": { "type": "Bool", "default": false },
@@ -169,7 +170,7 @@ import CometChatUIKitSwift
let search = CometChatSearch()
-// CometChatSearch surfaces failures as an error STATE, not an onError callback.
+// With offline support off, CometChatSearch surfaces failures as an error STATE, not an onError callback.
// Supply your own view, or retitle the built-in one.
search.set(errorView: myErrorView)
@@ -179,6 +180,14 @@ search.errorStateSubTitleText = "Check your connection and try again"
+With [offline support](/ui-kit/ios/offline-support#search) on, `set(onError:)` is also called, once per search that fails. A keyword search that can't connect and has no saved match shows **Connect to search** instead, without calling `onError`, and runs again once when the connection returns.
+
+```swift lines
+search.set(onError: { error in
+ print("Search failed: \(error.errorDescription)")
+})
+```
+
---
#### 5. onEmpty
diff --git a/ui-kit/ios/threaded-messages-header.mdx b/ui-kit/ios/threaded-messages-header.mdx
index 7f3ab9520..592a88bea 100644
--- a/ui-kit/ios/threaded-messages-header.mdx
+++ b/ui-kit/ios/threaded-messages-header.mdx
@@ -194,6 +194,8 @@ Below is a list of customizations along with corresponding code snippets:
| enableThreadSubscription | Shows the subscribe/unsubscribe bell on the reply-count bar. | `set(enableThreadSubscription: true)` |
| hideThreadSubscriptionButton | Hides the bell while leaving the feature on, for a screen that draws its own control. | `set(hideThreadSubscriptionButton: true)` |
+With [offline support](/ui-kit/ios/offline-support#message-list-and-threads) on, the reply count includes your own replies that haven't been sent yet, and takes back a reply that is discarded before it is sent.
+
### Thread Subscription
*Available since v5.1.22*