Chapter 14: Network Mode

Core Idea

networkMode controls how a query/mutation behaves without a network connection: 'online' (default) pauses instead of failing, 'always' ignores connectivity entirely, and 'offlineFirst' tries once (letting a service worker/HTTP cache answer) then behaves like 'online' on a real miss.

Key Concepts

• online (default): fetches only pause (fetchStatus: 'paused') when offline rather than erroring; retries also pause and resume on reconnect (a "continue," not a "refetch" — independent of refetchOnReconnect, and skipped if the query was cancelled meanwhile).
• always: ignores connectivity completely — appropriate when the queryFn doesn't need a real network connection at all (reading AsyncStorage, a Promise.resolve stub). Retries don't pause either; failures go straight to error. refetchOnReconnect defaults to false here since "back online" isn't a meaningful signal for data that never depended on the network.
• offlineFirst: middle ground for offline-first PWAs or HTTP Cache-Control-backed requests — the first attempt runs (may be answered from cache/service worker), and only a genuine cache-miss failure falls back to online-style paused retries.
• Devtools mock: the devtools panel has an "mock offline behavior" toggle that flips the OnlineManager's state without touching real network connectivity — useful for testing without disconnecting Wi-Fi.
• Config surface: set globally via query/mutation defaults, or per-query/mutation via the networkMode option.

Reference Tables

networkMode	Fetch when offline	Retries when offline	refetchOnReconnect default	Use for
online (default)	Paused	Paused	true	Normal server-data fetching
always	Runs regardless	Never pauses, goes to error	false	Local/AsyncStorage/non-network sources
offlineFirst	Runs once (may hit cache/SW)	Paused after a real miss	true	Offline-first PWAs, HTTP-cache-backed requests

Key Takeaways

1. Default to online for anything actually hitting a server — it's the mode that treats "no connection" as a pause, not a failure, and resumes cleanly on reconnect.
2. Use always for queries whose queryFn never touches the network — otherwise they'll incorrectly sit paused while offline for no reason.
3. isPending alone can mislead you about loading state: a first-mount query with no connection is pending + paused, not pending + fetching — check fetchStatus/isPaused if the distinction matters to your UI.

Connects To

• Queries: the fetchStatus field this chapter's pause/fetching/idle states extend.
• OnlineManager: the underlying connectivity source the devtools mock toggle manipulates.