TanStack · oblador · Mar 5, 2025
diff --git a/docs/framework/react/react-native.md b/docs/framework/react/react-native.md
@@ -95,6 +95,8 @@ In the above code, `refetch` is skipped the first time because `useFocusEffect`
 
 ## Disable queries on out of focus screens
 
+### `subscribed` option
+
 If you don’t want certain queries to remain “live” while a screen is out of focus, you can use the subscribed prop on useQuery. This prop lets you control whether a query stays subscribed to updates. Combined with React Navigation’s useIsFocused, it allows you to seamlessly unsubscribe from queries when a screen isn’t in focus:
 
 Example usage:
@@ -119,3 +121,30 @@ function MyComponent() {
 ```
 
 When subscribed is false, the query unsubscribes from updates and won’t trigger re-renders or fetch new data for that screen. Once it becomes true again (e.g., when the screen regains focus), the query re-subscribes and stays up to date.
+
+### `PauseManagerProvider` option
+
+In case you want to disable updates to _all_ queries in an out of focus screen, one alternative is to control them via `PauseManager`:
+
+```tsx
+import React from 'react'
+import { useIsFocused } from '@react-navigation/native'
+import { PauseManager, PauseManagerProvider } from 'react-native'
+
+function MyScreen() {
+  const isFocused = useIsFocused()
+  const pauseManager = useRef<PauseManager>(null)
+  if (pauseManager.current === null) {
+    pauseManager.current = new PauseManager(!isFocused)
+  }
+  useEffect(() => {
+    pauseManager.current?.setPaused(!isFocused)
+  }, [isFocused])
+
+  return (
+    <PauseManagerProvider pauseManager={pauseManager}>
+      <MyComponent />
+    </PauseManagerProvider>
+  )
+}
+```
diff --git a/docs/framework/react/reference/PauseManagerProvider.md b/docs/framework/react/reference/PauseManagerProvider.md
@@ -0,0 +1,22 @@
+---
+id: PauseManagerProvider
+title: PauseManagerProvider
+---
+
+Use the `PauseManagerProvider` component to connect and provide a `PauseManager` to your application which is used to selectively disable updates:
+
+```tsx
+import { PauseManager, PauseManagerProvider } from '@tanstack/react-query'
+
+const pauseManager = new PauseManager()
+
+function App() {
+  return <PauseManagerProvider client={pauseManager}>...</PauseManagerProvider>
+}
+```
+
+**Options**
+
+- `pauseManager: PauseManager`
+  - **Required**
+  - the PauseManager instance to provide
diff --git a/examples/react/pause/.eslintrc b/examples/react/pause/.eslintrc
@@ -0,0 +1,3 @@
+{
+  "extends": ["plugin:react/jsx-runtime", "plugin:react-hooks/recommended"]
+}
diff --git a/examples/react/pause/.gitignore b/examples/react/pause/.gitignore
@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/examples/react/pause/README.md b/examples/react/pause/README.md
@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`
diff --git a/examples/react/pause/index.html b/examples/react/pause/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+
+    <title>TanStack Query React Pause Example App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
diff --git a/examples/react/pause/package.json b/examples/react/pause/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tanstack/query-example-react-pause",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.67.1",
+    "@tanstack/react-query-devtools": "^5.67.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.3",
+    "typescript": "5.8.2",
+    "vite": "^5.3.5"
+  }
+}
diff --git a/examples/react/pause/public/emblem-light.svg b/examples/react/pause/public/emblem-light.svg
diff --git a/examples/react/pause/src/index.tsx b/examples/react/pause/src/index.tsx
@@ -0,0 +1,70 @@
+import ReactDOM from 'react-dom/client'
+import {
+  PauseManager,
+  PauseManagerProvider,
+  QueryClient,
+  QueryClientProvider,
+  useQuery,
+} from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import { memo, useRef, useSyncExternalStore } from 'react'
+
+const queryClient = new QueryClient()
+const pauseManager = new PauseManager(true)
+
+let counter = 1
+
+const useCounter = () =>
+  useQuery({
+    queryKey: ['counter'],
+    refetchOnMount: false,
+    queryFn: () => counter++,
+  })
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ReactQueryDevtools />
+      <Example />
+    </QueryClientProvider>
+  )
+}
+
+function Example() {
+  const { data, refetch } = useCounter()
+  const isPaused = useSyncExternalStore(
+    (onStoreChange) => pauseManager.subscribe(onStoreChange),
+    () => pauseManager.isPaused(),
+  )
+
+  return (
+    <div>
+      <p>Parent Counter: {data}</p>
+      <div style={{ opacity: isPaused ? 0.5 : 1 }}>
+        <PauseManagerProvider pauseManager={pauseManager}>
+          <MemoisedChild />
+        </PauseManagerProvider>
+      </div>
+      <button onClick={() => refetch()}>Increment</button>
+      <button onClick={() => pauseManager.setPaused(!isPaused)}>
+        {isPaused ? 'Resume' : 'Pause'}
+      </button>
+    </div>
+  )
+}
+
+const MemoisedChild = memo(() => {
+  const { data } = useCounter()
+  const renders = useRef(0)
+  renders.current++
+
+  return (
+    <>
+      <p>Child counter: {data}</p>
+      <p>Child renders: {renders.current}</p>
+    </>
+  )
+})
+
+const rootElement = document.getElementById('root') as HTMLElement
+ReactDOM.createRoot(rootElement).render(<App />)
diff --git a/examples/react/pause/tsconfig.json b/examples/react/pause/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "eslint.config.js"]
+}
diff --git a/examples/react/pause/vite.config.ts b/examples/react/pause/vite.config.ts
@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+})
diff --git a/packages/query-core/src/index.ts b/packages/query-core/src/index.ts
@@ -13,6 +13,7 @@ export { MutationObserver } from './mutationObserver'
 export { notifyManager, defaultScheduler } from './notifyManager'
 export { focusManager } from './focusManager'
 export { onlineManager } from './onlineManager'
+export { PauseManager } from './pauseManager'
 export {
   hashKey,
   replaceEqualDeep,

diff --git a/packages/query-core/src/pauseManager.ts b/packages/query-core/src/pauseManager.ts
@@ -0,0 +1,31 @@
+import { Subscribable } from './subscribable'
+
+type Listener = (paused: boolean) => void
+
+export class PauseManager extends Subscribable<Listener> {
+  #paused: boolean
+
+  constructor(paused = false) {
+    super()
+    this.#paused = paused
+  }
+
+  #onChange(): void {
+    const isPaused = this.isPaused()
+    this.listeners.forEach((listener) => {
+      listener(isPaused)
+    })
+  }
+
+  setPaused(paused: boolean): void {
+    const changed = this.#paused !== paused
+    if (changed) {
+      this.#paused = paused
+      this.#onChange()
+    }
+  }
+
+  isPaused(): boolean {
+    return this.#paused
+  }
+}
diff --git a/packages/react-query/src/PauseManagerProvider.tsx b/packages/react-query/src/PauseManagerProvider.tsx
@@ -0,0 +1,28 @@
+'use client'
+import * as React from 'react'
+
+import type { PauseManager } from '@tanstack/query-core'
+
+export const PauseManagerContext = React.createContext<
+  PauseManager | undefined
+>(undefined)
+
+export const usePauseManager = () => {
+  return React.useContext(PauseManagerContext)
+}
+
+export type PauseManagerProviderProps = {
+  pauseManager: PauseManager
+  children?: React.ReactNode
+}
+
+export const PauseManagerProvider = ({
+  pauseManager,
+  children,
+}: PauseManagerProviderProps): React.JSX.Element => {
+  return (
+    <PauseManagerContext.Provider value={pauseManager}>
+      {children}
+    </PauseManagerContext.Provider>
+  )
+}
diff --git a/packages/react-query/src/index.ts b/packages/react-query/src/index.ts
@@ -29,6 +29,11 @@ export type {
   UndefinedInitialDataInfiniteOptions,
   UnusedSkipTokenInfiniteOptions,
 } from './infiniteQueryOptions'
+export {
+  PauseManagerContext,
+  PauseManagerProvider,
+  usePauseManager,
+} from './PauseManagerProvider'
 export {
   QueryClientContext,
   QueryClientProvider,

diff --git a/packages/react-query/src/useBaseQuery.ts b/packages/react-query/src/useBaseQuery.ts
@@ -17,6 +17,7 @@ import {
   willFetch,
 } from './suspense'
 import { noop } from './utils'
+import { usePauseManager } from './PauseManagerProvider'
 import type {
   QueryClient,
   QueryKey,
@@ -53,6 +54,7 @@ export function useBaseQuery<
   const client = useQueryClient(queryClient)
   const isRestoring = useIsRestoring()
   const errorResetBoundary = useQueryErrorResetBoundary()
+  const pauseManager = usePauseManager()
   const defaultedOptions = client.defaultQueryOptions(options)
 
   ;(client.getDefaultOptions().queries as any)?._experimental_beforeQuery?.(
@@ -97,17 +99,37 @@ export function useBaseQuery<
   React.useSyncExternalStore(
     React.useCallback(
       (onStoreChange) => {
-        const unsubscribe = shouldSubscribe
-          ? observer.subscribe(notifyManager.batchCalls(onStoreChange))
-          : noop
+        if (!shouldSubscribe) {
+          return noop
+        }
+        const notify = notifyManager.batchCalls(onStoreChange)
+        let isPaused = pauseManager?.isPaused()
+        let hasPendingChanges = false
+        const unsubscribeObserver = observer.subscribe(() => {
+          if (isPaused) {
+            hasPendingChanges = true
+          } else {
+            notify()
+          }
+        })
+        const unsubscribePaused = pauseManager?.subscribe((paused) => {
+          isPaused = paused
+          if (hasPendingChanges && !paused) {
+            hasPendingChanges = false
+            notify()
+          }
+        })
 
         // Update result to make sure we did not miss any query updates
         // between creating the observer and subscribing to it.
         observer.updateResult()
 
-        return unsubscribe
+        return () => {
+          unsubscribeObserver()
+          unsubscribePaused?.()
+        }
       },
-      [observer, shouldSubscribe],
+      [observer, shouldSubscribe, pauseManager],
     ),
     () => observer.getCurrentResult(),
     () => observer.getCurrentResult(),