Skip to main content
Offline support keeps the logged-in user’s conversations and messages on the device so your app can show them instantly, lets the user send messages while disconnected, and catches up automatically when the connection returns. It is off by default — nothing changes in your app until you enable it (Enable Offline Support). This page explains the mental model; the other pages show the exact APIs.
Offline support ships in CometChat JavaScript SDK 4.3.0 or later. It runs in the browser (IndexedDB, with OPFS for media) and in Electron (SQLite). See Enable Offline Support.

​
How it works

Three ideas carry the whole feature.
1

Cache first, then server

Reads that you pass a fetch listener go through the local cache first. For list reads the SDK delivers the cached page immediately, even when it is empty. Single-item lookups (getMessageDetails, getConversation) deliver a cached result only when that item is already cached. The SDK then fetches from the server and delivers the fresh result. See Show Cached Data.
2

A durable send outbox

A message sent while offline is saved to a durable outbox and reported as pending instead of failing. It survives page reloads and app restarts and is sent when the connection returns. See Send While Offline.
3

Catch up on reconnect

When the connection returns, the SDK syncs the conversations and messages that changed while it was away and flushes the outbox, so the local cache matches the server again. See Stay in Sync.

​
What changes in your app

With offline support enabled, your fetch callbacks fire twice on the read path and sends gain a pending stage. To receive the cached and pending results you pass the new listener objects — MessageFetchListener, ConversationFetchListener, MessageSentListener, and the others listed on each page — as an optional argument. Every method still returns its usual Promise, so existing code keeps working. A call without a listener receives only the server result, and a send without a listener is never queued. With offline support off, every API behaves exactly as it did before.

​
Queued, not failed

A send made with no connection fires onMessagePending, then one onError with code FAILED_TO_FETCH, and the returned Promise rejects. That is a notice, not a failure: the message stays queued and onMessageSent fires later, on reconnect. See Send While Offline.

​
One cache per user

The SDK keeps a single local cache per app and user.
  • A page reload or app restart with a still-valid session reuses that cache, so the data is there instantly.
  • Logging out, a session expiring, or logging in as a different user deletes the cache, including any unsent messages still in the outbox, which are lost. You never clear it yourself — the SDK does it.
See Stay in Sync for cache resets and logout behaviour.

​
How much is kept

By default the cache holds up to 100 conversations, up to 500 messages per conversation, around 250 MB of cached content, and up to 500 MB of cached media. There is no age limit unless you set cacheDurationDays. Older entries are evicted first as these limits are reached. Every limit is tunable — see the Configuration & API Reference.

​
Next steps

Enable Offline Support

Turn it on and verify it is active.

Show Cached Data

The cached-first, server-next read contract.

Send While Offline

The durable outbox and pending messages.

Stay in Sync

Reconnect catch-up, cache resets, logout.

Media Caching

Download and cache attachments for offline viewing.

Encrypt the Cache

Encrypt the local cache at rest.

Configuration & API Reference

Every option, method, listener, enum, and error.