TanStack
diff --git a/‎docs/src/manifests/manifest.json
+5 b/‎docs/src/manifests/manifest.json
+5
diff --git a/‎docs/src/pages/guides/migrating-to-react-query-4.md
+39-4 b/‎docs/src/pages/guides/migrating-to-react-query-4.md
+39-4
diff --git a/‎docs/src/pages/guides/network-mode.md
+46 b/‎docs/src/pages/guides/network-mode.md
+46
diff --git a/‎docs/src/pages/reference/useMutation.md
+8 b/‎docs/src/pages/reference/useMutation.md
+8
diff --git a/‎docs/src/pages/reference/useQuery.md
+16-3 b/‎docs/src/pages/reference/useQuery.md
+16-3
diff --git a/‎src/core/infiniteQueryObserver.ts
+3-2 b/‎src/core/infiniteQueryObserver.ts
+3-2
diff --git a/‎src/core/mutation.ts
+1 b/‎src/core/mutation.ts
+1
diff --git a/‎src/core/queriesObserver.ts
+2-2 b/‎src/core/queriesObserver.ts
+2-2
diff --git a/‎src/core/query.ts
+18-21 b/‎src/core/query.ts
+18-21
@@ -75,6 +75,11 @@
           "path": "/guides/query-functions",
           "editUrl": "/guides/query-functions.md"
         },
+        {
+          "title": "Network Mode",
+          "path": "/guides/network-mode",
+          "editUrl": "/guides/network-mode.md"
+        },
         {
           "title": "Parallel Queries",
           "path": "/guides/parallel-queries",
 
@@ -20,7 +20,7 @@ To streamline all apis, we've decided to make all keys Arrays only:
 
 ### Separate hydration exports have been removed
 
-With version [3.22.0](https://github.com/tannerlinsley/react-query/releases/tag/v3.22.0), hydration utilities moved into the react-query core. With v3, you could still use the old exports from `react-query/hydration`, but these exports have been removed with v4.
+With version [3.22.0](https://github.com/tannerlinsley/react-query/releases/tag/v3.22.0), hydration utilities moved into the React Query core. With v3, you could still use the old exports from `react-query/hydration`, but these exports have been removed with v4.
 
 ```diff
 - import { dehydrate, hydrate, useHydrate, Hydrate } from 'react-query/hydration'
@@ -29,7 +29,7 @@ With version [3.22.0](https://github.com/tannerlinsley/react-query/releases/tag/
 
 ### `notifyOnChangeProps` property no longer accepts `"tracked"` as a value
 
-The `notifyOnChangeProps` option no longer accepts a `"tracked"` value. Instead, `useQuery` defaults to tracking properties. All queries using `notifyOnChangeProps: "tracked"` should be updated by removing this option. 
+The `notifyOnChangeProps` option no longer accepts a `"tracked"` value. Instead, `useQuery` defaults to tracking properties. All queries using `notifyOnChangeProps: "tracked"` should be updated by removing this option.
 
 If you would like to bypass this in any queries to emulate the v3 default behavior of re-rendering whenever a query changes, `notifyOnChangeProps` now accepts an `"all"` value to opt-out of the default smart tracking optimization.
 
@@ -140,7 +140,7 @@ The `MutationCacheNotifyEvent` uses the same types as the `QueryCacheNotifyEvent
 
 ### The `src/react` directory was renamed to `src/reactjs`
 
-Previously, react-query had a directory named `react` which imported from the `react` module. This could cause problems with some Jest configurations, resulting in errors when running tests like:
+Previously, React Query had a directory named `react` which imported from the `react` module. This could cause problems with some Jest configurations, resulting in errors when running tests like:
 
 ```
 TypeError: Cannot read property 'createContext' of undefined
@@ -161,7 +161,7 @@ This was confusing to many and also created infinite loops if `setQueryData` was
 
 Similar to `onError` and `onSettled`, the `onSuccess` callback is now tied to a request being made. No request -> no callback.
 
-If you want to listen to changes of the `data` field, you can best do this with a `useEffect`, where `data` is part of the dependency Array. Since react-query ensures stable data through structural sharing, the effect will not execute with every background refetch, but only if something within data has changed:
+If you want to listen to changes of the `data` field, you can best do this with a `useEffect`, where `data` is part of the dependency Array. Since React Query ensures stable data through structural sharing, the effect will not execute with every background refetch, but only if something within data has changed:
 
 ```
 const { data } = useQuery({ queryKey, queryFn })
@@ -188,8 +188,43 @@ Since these plugins are no longer experimental, their import paths have also bee
 
 The [old `cancel` method](../guides/query-cancellation#old-cancel-function) that allowed you to define a `cancel` function on promises, which was then used by the library to support query cancellation, has been removed. We recommend to use the [newer API](../guides/query-cancellation) (introduced with v3.30.0) for query cancellation that uses the [`AbortController` API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) internally and provides you with an [`AbortSignal` instance](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for your query function to support query cancellation.
 
+### Queries and mutations, per default, need network connection to run
+
+Please read the [New Features announcement](#proper-offline-support) about online / offline support, and also the dedicated page about [Network mode](../guides/network-mode)
+
+Even though React Query is an Async State Manager that can be used for anything that produces a Promise, it is most often used for data fetching in combination with data fetching libraries. That is why, per default, queries and mutations will be `paused` if there is no network connection. If you want to opt-in to the previous behavior, you can globally set `networkMode: offlineFirst` for both queries and mutations:
+
+```js
+new QueryClient({
+  defaultOptions: {
+    queries: {
+      networkMode: 'offlineFirst'
+    },
+    mutations: {
+      networkmode: 'offlineFirst'
+    }
+  }
+})
+
+```
+
 ## New Features 🚀
 
+### Proper offline support
+
+In v3, React Query has always fired off queries and mutations, but then taken the assumption that if you want to retry it, you need to be connected to the internet. This has led to several confusing situations:
+
+- You are offline and mount a query - it goes to loading state, the request fails, and it stays in loading state until you go online again, even though it is not really fetching.
+- Similarly, if you are offline and have retries turned off, your query will just fire and fail, and the query goes to error state.
+- You are offline and want to fire off a query that doesn't necessarily need network connection (because you _can_ use React Query for something other than data fetching), but it fails for some other reason. That query will now be paused until you go online again.
+- Window focus refetching didn't do anything at all if you were offline.
+
+With v4, React Query introduces a new `networkMode` to tackle all these issues. Please read the dedicated page about the new [Network mode](../guides/network-mode) for more information.
+
 ### Mutation Cache Garbage Collection
 
 Mutations can now also be garbage collected automatically, just like queries. The default `cacheTime` for mutations is also set to 5 minutes.
+
+### Tracked Queries per default
+
+React Query defaults to "tracking" query properties, which should give you a nice boost in render optimization. The feature has existed since [v3.6.0](https://github.com/tannerlinsley/react-query/releases/tag/v3.6.0) and has now become the default behavior with v4.
@@ -0,0 +1,46 @@
+---
+id: network-mode
+title: Network Mode
+---
+
+React Query provides three different network modes to distinguish how [Queries](./queries) and [Mutations](./mutations) should behave if you have no network connection. This mode can be set for each Query / Mutation individually, or globally via the query / mutation defaults.
+
+Since React Query is most often used for data fetching in combination with data fetching libraries, the default network mode is [online](#network-mode-online).
+
+## Network Mode: online
+
+In this mode, Queries and Mutations will not fire unless you have network connection. This is the default mode. If a fetch is initiated for a query, it will always stay in the `state` (`loading`, `idle`, `error`, `success`) it is in if the fetch cannot be made because there is no network connection. However, a `fetchStatus` is exposed additionally. This can be either:
+
+- `fetching`: The `queryFn` is really executing - a request is in-flight.
+- `paused`: The query is not executing - it is `paused` until you have connection again
+- `idle`: The query is not fetching and not paused
+
+The flags `isFetching` and `isPaused` are derived from this state and exposed for convenience.
+
+> Keep in mind that it might not be enough to check for `loading` state to show a loading spinner. Queries can be in `state: 'loading'`, but `fetchStatus: 'paused'` if they are mounting for the first time, and you have no network connection.
+
+If a query runs because you are online, but you go offline while the fetch is still happening, React Query will also pause the retry mechanism. Paused queries will then continue to run once you re-gain network connection. This is independent of `refetchOnReconnect` (which also defaults to `true` in this mode), because it is not a `refetch`, but rather a `continue`. If the query has been [cancelled](./query-cancellation) in the meantime, it will not continue.
+
+## Network Mode: always
+
+In this mode, React Query will always fetch and ignore the online / offline state. This is likely the mode you want to choose if you use React Query in an environment where you don't need an active network connection for your Queries to work - e.g. if you just read from `AsyncStorage`, or if you just want to return `Promise.resolve(5)` from your `queryFn`.
+
+- Queries will never be `paused` because you have no network connection.
+- Retries will also not pause - your Query will go to `error` state if it fails.
+- `refetchOnReconnect` defaults to `false` in this mode, because reconnecting to the network is not a good indicator anymore that stale queries should be refetched. You can still turn it on if you want.
+
+## Network Mode: offlineFirst
+
+This mode is the middle ground between the first two options, where React Query will run the `queryFn` once, but then pause retries. This is very handy if you have a serviceWorker that intercepts a request for caching like in an [offline-first PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Offline_Service_workers), or if you use HTTP caching via the [Cache-Control header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#the_cache-control_header).
+
+In those situations, the first fetch might succeed because it comes from an offline storage / cache. However, if there is a cache miss, the network request will go out and fail, in which case this mode behaves like an `online` query - pausing retries.
+
+## Devtools
+
+The [React Query Devtools](../devtools) will show Queries in a `paused` state if they would be fetching, but there is no network connection. There is also a toggle button to _Mock offline behavior_. Please note that this button will _not_ actually mess with your network connection (you can do that in the browser devtools), but it will set the [OnlineManager](../reference/onlineManager) in an offline state.
+
+## Signature
+
+- `networkMode: 'online' | 'always' | 'offlineFirst`
+  - optional
+  - defaults to `'online'`
@@ -19,6 +19,7 @@ const {
 } = useMutation(mutationFn, {
   cacheTime,
   mutationKey,
+  networkMode,
   onError,
   onMutate,
   onSettled,
@@ -46,6 +47,10 @@ mutate(variables, {
 - `mutationKey: string`
   - Optional
   - A mutation key can be set to inherit defaults set with `queryClient.setMutationDefaults` or to identify the mutation in the devtools.
+- `networkMode: 'online' | 'always' | 'offlineFirst`
+  - optional
+  - defaults to `'online'`
+  - see [Network Mode](../guides/network-mode) for more information.
 - `onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void`
   - Optional
   - This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
@@ -98,6 +103,9 @@ mutate(variables, {
     - `error` if the last mutation attempt resulted in an error.
     - `success` if the last mutation attempt was successful.
 - `isIdle`, `isLoading`, `isSuccess`, `isError`: boolean variables derived from `status`
+- `isPaused: boolean`
+  - will be `true` if the mutation has been `paused`
+  - see [Network Mode](../guides/network-mode) for more information.
 - `data: undefined | unknown`
   - Defaults to `undefined`
   - The last successfully resolved data for the query.
 
@@ -14,6 +14,7 @@ const {
   isFetched,
   isFetchedAfterMount,
   isFetching,
+  isPaused,
   isIdle,
   isLoading,
   isLoadingError,
@@ -26,11 +27,13 @@ const {
   refetch,
   remove,
   status,
+  fetchStatus,
 } = useQuery(queryKey, queryFn?, {
   cacheTime,
   enabled,
+  networkMode,
   initialData,
-  initialDataUpdatedAt
+  initialDataUpdatedAt,
   isDataEqual,
   keepPreviousData,
   meta,
@@ -78,6 +81,10 @@ const result = useQuery({
 - `enabled: boolean`
   - Set this to `false` to disable this query from automatically running.
   - Can be used for [Dependent Queries](../guides/dependent-queries).
+- `networkMode: 'online' | 'always' | 'offlineFirst`
+  - optional
+  - defaults to `'online'`
+  - see [Network Mode](../guides/network-mode) for more information.
 - `retry: boolean | number | (failureCount: number, error: TError) => boolean`
   - If `false`, failed queries will not retry by default.
   - If `true`, failed queries will retry infinitely.
@@ -218,9 +225,15 @@ const result = useQuery({
 - `isFetchedAfterMount: boolean`
   - Will be `true` if the query has been fetched after the component mounted.
   - This property can be used to not show any previously cached data.
+- `fetchStatus: FetchStatus`
+  - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `loading` as well as background refetches.
+  - `paused`: The query wanted to fetch, but has been `paused`
+  - `idle`: The query is not fetching
+  - see [Network Mode](../guides/network-mode) for more information.
 - `isFetching: boolean`
-  - Is `true` whenever a request is in-flight, which includes initial `loading` as well as background refetches.
-  - Will be `true` if the query is currently fetching, including background fetching.
+  - A derived boolean from the `fetchStatus` variable above, provided for convenience.
+- `isPaused: boolean`
+  - A derived boolean from the `fetchStatus` variable above, provided for convenience.
 - `isRefetching: boolean`
   - Is `true` whenever a background refetch is in-flight, which _does not_ include initial `loading`
   - Is the same as `isFetching && !isLoading`
 
@@ -133,9 +133,10 @@ export class InfiniteQueryObserver<
       hasNextPage: hasNextPage(options, state.data?.pages),
       hasPreviousPage: hasPreviousPage(options, state.data?.pages),
       isFetchingNextPage:
-        state.isFetching && state.fetchMeta?.fetchMore?.direction === 'forward',
+        state.fetchStatus === 'fetching' &&
+        state.fetchMeta?.fetchMore?.direction === 'forward',
       isFetchingPreviousPage:
-        state.isFetching &&
+        state.fetchStatus === 'fetching' &&
         state.fetchMeta?.fetchMore?.direction === 'backward',
     }
   }
 
@@ -277,6 +277,7 @@ export class Mutation<
       },
       retry: this.options.retry ?? 0,
       retryDelay: this.options.retryDelay,
+      networkMode: this.options.networkMode,
     })
 
     return this.retryer.promise
 
@@ -74,7 +74,7 @@ export class QueriesObserver extends Subscribable<QueriesObserverListener> {
   ): QueryObserverMatch[] {
     const prevObservers = this.observers
     const defaultedQueryOptions = queries.map(options =>
-      this.client.defaultQueryObserverOptions(options)
+      this.client.defaultQueryOptions(options)
     )
 
     const matchingObservers: QueryObserverMatch[] = defaultedQueryOptions.flatMap(
@@ -125,7 +125,7 @@ export class QueriesObserver extends Subscribable<QueriesObserverListener> {
   }
 
   private getObserver(options: QueryObserverOptions): QueryObserver {
-    const defaultedOptions = this.client.defaultQueryObserverOptions(options)
+    const defaultedOptions = this.client.defaultQueryOptions(options)
     const currentObserver = this.observersMap[defaultedOptions.queryHash!]
     return currentObserver ?? new QueryObserver(this.client, defaultedOptions)
   }
 
@@ -15,12 +15,13 @@ import type {
   QueryMeta,
   CancelOptions,
   SetDataOptions,
+  FetchStatus,
 } from './types'
 import type { QueryCache } from './queryCache'
 import type { QueryObserver } from './queryObserver'
 import { notifyManager } from './notifyManager'
 import { getLogger } from './logger'
-import { Retryer, isCancelledError } from './retryer'
+import { Retryer, isCancelledError, canFetch } from './retryer'
 import { Removable } from './removable'
 
 // TYPES
@@ -49,10 +50,9 @@ export interface QueryState<TData = unknown, TError = unknown> {
   errorUpdatedAt: number
   fetchFailureCount: number
   fetchMeta: any
-  isFetching: boolean
   isInvalidated: boolean
-  isPaused: boolean
   status: QueryStatus
+  fetchStatus: FetchStatus
 }
 
 export interface FetchContext<
@@ -198,12 +198,10 @@ export class Query<
 
   protected optionalRemove() {
     if (!this.observers.length) {
-      if (this.state.isFetching) {
-        if (this.hadObservers) {
-          this.scheduleGc()
-        }
-      } else {
+      if (this.state.fetchStatus === 'idle') {
         this.cache.remove(this)
+      } else if (this.hadObservers) {
+        this.scheduleGc()
       }
     }
   }
@@ -265,7 +263,7 @@ export class Query<
   }
 
   isFetching(): boolean {
-    return this.state.isFetching
+    return this.state.fetchStatus === 'fetching'
   }
 
   isStale(): boolean {
@@ -358,7 +356,7 @@ export class Query<
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     fetchOptions?: FetchOptions
   ): Promise<TData> {
-    if (this.state.isFetching) {
+    if (this.state.fetchStatus !== 'idle') {
       if (this.state.dataUpdatedAt && fetchOptions?.cancelRefetch) {
         // Silently cancel current fetch if the user wants to cancel refetches
         this.cancel({ silent: true })
@@ -441,7 +439,7 @@ export class Query<
 
     // Set to fetching state if not already in it
     if (
-      !this.state.isFetching ||
+      this.state.fetchStatus === 'idle' ||
       this.state.fetchMeta !== context.fetchOptions?.meta
     ) {
       this.dispatch({ type: 'fetch', meta: context.fetchOptions?.meta })
@@ -495,6 +493,7 @@ export class Query<
       },
       retry: context.options.retry,
       retryDelay: context.options.retryDelay,
+      networkMode: context.options.networkMode,
     })
 
     this.promise = this.retryer.promise
@@ -541,10 +540,9 @@ export class Query<
       errorUpdatedAt: 0,
       fetchFailureCount: 0,
       fetchMeta: null,
-      isFetching: false,
       isInvalidated: false,
-      isPaused: false,
       status: hasData ? 'success' : 'idle',
+      fetchStatus: 'idle',
     }
   }
 
@@ -561,20 +559,21 @@ export class Query<
       case 'pause':
         return {
           ...state,
-          isPaused: true,
+          fetchStatus: 'paused',
         }
       case 'continue':
         return {
           ...state,
-          isPaused: false,
+          fetchStatus: 'fetching',
         }
       case 'fetch':
         return {
           ...state,
           fetchFailureCount: 0,
           fetchMeta: action.meta ?? null,
-          isFetching: true,
-          isPaused: false,
+          fetchStatus: canFetch(this.options.networkMode)
+            ? 'fetching'
+            : 'paused',
           status: !state.dataUpdatedAt ? 'loading' : state.status,
         }
       case 'success':
@@ -585,9 +584,8 @@ export class Query<
           dataUpdatedAt: action.dataUpdatedAt ?? Date.now(),
           error: null,
           fetchFailureCount: 0,
-          isFetching: false,
           isInvalidated: false,
-          isPaused: false,
+          fetchStatus: 'idle',
           status: 'success',
         }
       case 'error':
@@ -603,8 +601,7 @@ export class Query<
           errorUpdateCount: state.errorUpdateCount + 1,
           errorUpdatedAt: Date.now(),
           fetchFailureCount: state.fetchFailureCount + 1,
-          isFetching: false,
-          isPaused: false,
+          fetchStatus: 'idle',
           status: 'error',
         }
       case 'invalidate':
Original file line number	Diff line number	Diff line change
`@@ -133,9 +133,10 @@ export class InfiniteQueryObserver<`
`133`	`133`	`hasNextPage: hasNextPage(options, state.data?.pages),`
`134`	`134`	`hasPreviousPage: hasPreviousPage(options, state.data?.pages),`
`135`	`135`	`isFetchingNextPage:`
`136`		`- state.isFetching && state.fetchMeta?.fetchMore?.direction === 'forward',`
	`136`	`+ state.fetchStatus === 'fetching' &&`
	`137`	`+ state.fetchMeta?.fetchMore?.direction === 'forward',`
`137`	`138`	`isFetchingPreviousPage:`
`138`		`- state.isFetching &&`
	`139`	`+ state.fetchStatus === 'fetching' &&`
`139`	`140`	`state.fetchMeta?.fetchMore?.direction === 'backward',`
`140`	`141`	`}`
`141`	`142`	`}`
Original file line number	Diff line number	Diff line change
`@@ -74,7 +74,7 @@ export class QueriesObserver extends Subscribable<QueriesObserverListener> {`
`74`	`74`	`): QueryObserverMatch[] {`
`75`	`75`	`const prevObservers = this.observers`
`76`	`76`	`const defaultedQueryOptions = queries.map(options =>`
`77`		`- this.client.defaultQueryObserverOptions(options)`
	`77`	`+ this.client.defaultQueryOptions(options)`
`78`	`78`	`)`
`79`	`79`
`80`	`80`	`const matchingObservers: QueryObserverMatch[] = defaultedQueryOptions.flatMap(`
`@@ -125,7 +125,7 @@ export class QueriesObserver extends Subscribable<QueriesObserverListener> {`
`125`	`125`	`}`
`126`	`126`
`127`	`127`	`private getObserver(options: QueryObserverOptions): QueryObserver {`
`128`		`- const defaultedOptions = this.client.defaultQueryObserverOptions(options)`
	`128`	`+ const defaultedOptions = this.client.defaultQueryOptions(options)`
`129`	`129`	`const currentObserver = this.observersMap[defaultedOptions.queryHash!]`
`130`	`130`	`return currentObserver ?? new QueryObserver(this.client, defaultedOptions)`
`131`	`131`	`}`