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 requires CometChat React Native Chat SDK 4.2.0 or later.

​
How it works

Three ideas carry the whole feature.
1

Cache first, then server

Every read that you pass a listener to goes 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. Your UI renders what is on the device without waiting for the network, then updates when the server responds. See Show Cached Data.
2

A durable send outbox

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

Catch up on reconnect

When the device reconnects, 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, the read and send methods you already call keep working, and gain two things. Reads still return a Promise that settles on the server result; if you also pass a listener, it receives the cached page first and then the server page. Sends still return a Promise; if you also pass a MessageSentListener, it is told when the message is queued (onMessagePending) and when it is finally sent. To receive the cached and pending stages you must pass these listeners — the Promise-only forms are unchanged. A send without a listener is never queued: it goes straight to the server and fails if there is no connection. With offline support off, every API behaves exactly as it did before.

​
One cache per user

The SDK keeps a single local cache for the user who is logged in, per app.
  • The cache survives app restarts while the same user stays logged in, so the data is there instantly on next launch.
  • Logging out, a session expiring, or logging in as a different user wipes 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 is bounded by size, not age: it holds up to 100 conversations, up to 500 messages per conversation, around 250 MB of data, and up to 500 MB of cached media. 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 database at rest.

Configuration & API Reference

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