> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Offline Support

> Understand how local caching, the send outbox, and reconnect catch-up keep chat working without a connection with the CometChat JavaScript SDK.

> [accordion] AI Integration Quick Reference
>
> ```javascript theme={null}
> // Offline support is OFF by default. Turn it on at init (SDK 4.3.0 or later).
> const appSetting = new CometChat.AppSettingsBuilder()
>   .setRegion("REGION")
>   .setOfflineConfig({ enabled: true })   // or .offline(true) for defaults
>   .build();
>
> await CometChat.init("APP_ID", appSetting);
>
> // Is offline support active right now for the logged-in user?
> const active = CometChat.isOfflineEnabled();   // boolean
> ```

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](https://www.cometchat.com/docs/sdk/javascript/offline-enable.md)). This page explains the mental model; the other pages show the exact APIs.

> [!NOTE]
>
> 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](https://www.cometchat.com/docs/sdk/javascript/offline-enable.md#supported-runtimes).

## 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](https://www.cometchat.com/docs/sdk/javascript/offline-cached-data.md).

**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](https://www.cometchat.com/docs/sdk/javascript/offline-send.md).

**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](https://www.cometchat.com/docs/sdk/javascript/offline-sync.md).

```mermaid theme={null}
flowchart LR
    A[App read] --> B[(Local cache)]
    B -- cached page first --> A
    B --> C{Online?}
    C -- yes --> D[Server]
    D -- fresh result --> A
    C -- no --> E[onError:\nFAILED_TO_FETCH]
    F[Send while offline] --> G[(Durable outbox)]
    G -- on reconnect --> D
```

## 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](https://www.cometchat.com/docs/sdk/javascript/offline-send.md#queued-not-failed).

## 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](https://www.cometchat.com/docs/sdk/javascript/offline-sync.md) 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](https://www.cometchat.com/docs/sdk/javascript/offline-reference.md).

## Next steps

> [card] [Enable Offline Support](https://www.cometchat.com/docs/sdk/javascript/offline-enable.md)
>
> Turn it on and verify it is active.

> [card] [Show Cached Data](https://www.cometchat.com/docs/sdk/javascript/offline-cached-data.md)
>
> The cached-first, server-next read contract.

> [card] [Send While Offline](https://www.cometchat.com/docs/sdk/javascript/offline-send.md)
>
> The durable outbox and pending messages.

> [card] [Stay in Sync](https://www.cometchat.com/docs/sdk/javascript/offline-sync.md)
>
> Reconnect catch-up, cache resets, logout.

> [card] [Media Caching](https://www.cometchat.com/docs/sdk/javascript/offline-media-caching.md)
>
> Download and cache attachments for offline viewing.

> [card] [Encrypt the Cache](https://www.cometchat.com/docs/sdk/javascript/offline-encryption.md)
>
> Encrypt the local cache at rest.

> [card] [Configuration & API Reference](https://www.cometchat.com/docs/sdk/javascript/offline-reference.md)
>
> Every option, method, listener, enum, and error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.