use-offline-query

A lightweight React hook that makes API calls resilient to network failures. When the network is available, it returns fresh data from your API. When it's not, it falls back to the most recently cached response - or, if there's nothing cached, to hardcoded fallback data you provide. Your app never shows an empty screen.

While offline, the hook retries in the background using exponential backoff and picks up fresh data as soon as the connection is restored.

Install

npm install use-offline-query

Usage

import { useOfflineQuery } from "use-offline-query";
import fallbackPosts from "./fallback-posts.json";

function Posts() {
  const { data, dataSource, isLoading, isStale, error, retry } = useOfflineQuery({
    queryFn: () =>
      fetch("/api/posts").then((res) => {
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        return res.json();
      }),
    cacheKey: "posts",
    fallbackData: fallbackPosts,
  });

  if (isLoading && !data) return <p>Loading...</p>;

  return (
    <div>
      {isStale && <p>You are viewing cached data.</p>}
      {error && <p>Error: {error.message}</p>}
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <button onClick={retry}>Retry</button>
    </div>
  );
}

How it works

1. On mount, any cached data is rendered immediately from localStorage.
2. A fresh API request fires in the background.
3. If the request succeeds, the data is updated and cached.
4. If it fails, the hook keeps showing cached data (or your hardcoded fallback if there's no cache) and retries with exponential backoff (1s, 2s, 4s, 8s... capped at maxBackoff).
5. When the browser fires an online event, a retry is triggered immediately.

API

Options

| Option | Type | Default | Description | | -------------- | ------------------ | ---------- | ----------------------------------------------------------------------------------- | | queryFn | () => Promise<T> | required | Async function that fetches data from your API. | | cacheKey | string | required | Key used to store/retrieve cached data in localStorage. Must be unique per query. | | fallbackData | T | required | Static data to use when both the API and cache are unavailable. | | maxRetries | number | Infinity | Maximum number of retry attempts. | | maxBackoff | number | 30000 | Upper bound (ms) on the backoff delay. |

Return value

| Field | Type | Description | | ------------ | --------------------------------------------- | --------------------------------------------------------------------------- | | data | T \| undefined | The current data - from the API, cache, or fallback. | | dataSource | "api" \| "cache" \| "fallback" \| undefined | Where the current data came from. | | isLoading | boolean | true while an API request is in flight. | | isStale | boolean | true when data is from cache or fallback rather than a live API response. | | error | Error \| null | The most recent fetch error, cleared on success. | | retry | () => void | Manually trigger a fresh API request (resets backoff). |

Multiple instances

Each call to useOfflineQuery is independent. You can use it multiple times in the same app - each instance fetches, caches, and retries on its own. Just make sure each one has a unique cacheKey.

License

MIT