network-mode

15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Queries and mutations default to paused when offline

In v4, queries and mutations are paused by default if there is no network connection. This provides proper offline support. To revert to v3 behavior where queries and mutations would fire regardless of connection, globally set networkMode: 'offlineFirst' in defaultOptions for both queries and mutations when creating the QueryClient.

Network mode: online overview

In online mode, Queries and Mutations will not fire unless you have a network connection. This is the default network mode. When offline, the query stays in its current state (pending, error, or success) while the fetchStatus becomes 'paused'.

Online mode fetchStatus values

In online mode, the fetchStatus can be 'fetching' (queryFn is executing with a request in-flight), 'paused' (query is not executing and waiting for connection), or 'idle' (query is not fetching and not paused). The flags isFetching and isPaused are derived from fetchStatus.

Online mode pause during offline fetch

If a query runs while online but you go offline while the fetch is still happening, TanStack Query pauses the retry mechanism. Paused queries continue once network connection is regained. This is independent of refetchOnReconnect (which defaults to true in online mode) because it is a continuation, not a refetch. If the query was cancelled meanwhile, it will not continue.

Pitfall: pending state does not indicate loading in online mode

Queries can be in state: 'pending' but fetchStatus: 'paused' if they are mounting for the first time and there is no network connection. Checking only pending state may not be enough to show a loading spinner.

Network mode: always overview

In always mode, TanStack Query always fetches and ignores the online/offline state. Queries will never be paused due to lack of network connection. Retries will not pause. This mode is suitable for environments where network connection is not required, such as reading from AsyncStorage or returning Promise.resolve(5) from queryFn.

Always mode refetchOnReconnect default

In always mode, refetchOnReconnect defaults to false because reconnecting to the network is not a good indicator that stale queries should be refetched. It can still be turned on manually if desired.

Network mode: offlineFirst overview

In offlineFirst mode, TanStack Query runs the queryFn once, then pauses retries. This mode is suitable for offline-first PWAs with service workers that intercept requests for caching, or when using HTTP caching via Cache-Control header. If the first fetch succeeds from offline storage/cache, it returns cached data. If there is a cache miss and the network request fails, the mode behaves like online mode, pausing retries.

Network mode configuration signature

The networkMode parameter accepts 'online' | 'always' | 'offlineFirst', is optional, and defaults to 'online'. It can be set for each Query/Mutation individually or globally via query/mutation defaults.

networkMode option for polling without connectivity detection

TanStack Query detects connectivity by listening to browser online and offline events. In environments where those events don't fire reliably (such as Electron or embedded WebViews), set networkMode: 'always' to skip the connectivity check and continue polling.

Polling example with networkMode for offline support

Example of polling with networkMode: 'always' to skip connectivity checks: ```tsx useQuery({ queryKey: ['chainStatus'], queryFn: fetchChainStatus, refetchInterval: 10_000, networkMode: 'always', }) ```

Set up online status management in React Native with onlineManager

To add auto-refetch on reconnect behavior in React Native, use React Query's onlineManager.setEventListener() method. This is necessary because auto-refetch on reconnect only works automatically in web browsers. Two approaches are shown: using @react-native-community/netinfo or using expo-network.

Online status setup with @react-native-community/netinfo

Example code for setting up online status management using NetInfo: import NetInfo from '@react-native-community/netinfo'; import { onlineManager } from '@tanstack/react-query'; onlineManager.setEventListener((setOnline) => { return NetInfo.addEventListener((state) => { setOnline(!!state.isConnected) }) })

Online status setup with expo-network

Example code for setting up online status management using expo-network: import { onlineManager } from '@tanstack/react-query'; import * as Network from 'expo-network'; onlineManager.setEventListener((setOnline) => { let initialised = false; const eventSubscription = Network.addNetworkStateListener((state) => { initialised = true; setOnline(!!state.isConnected) }); Network.getNetworkStateAsync().then((state) => { if (!initialised) { setOnline(!!state.isConnected) } }).catch(() => {}); return eventSubscription.remove })

networkMode parameter values

The networkMode parameter accepts three values: 'online', 'always', or 'offlineFirst'. It defaults to 'online'.

Give your agent this brain