Skip to content

Commit cf66d0d

Browse files
obladoroblador
committed
feat(react-query): add pause provider
1 parent 8b1eff1 commit cf66d0d

File tree

18 files changed

+384
-10
lines changed

18 files changed

+384
-10
lines changed

‎docs/framework/react/react-native.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,8 @@ In the above code, `refetch` is skipped the first time because `useFocusEffect`
9595

9696
## Disable queries on out of focus screens
9797

98+
### `subscribed` option
99+
98100
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:
99101

100102
Example usage:
@@ -119,3 +121,30 @@ function MyComponent() {
119121
```
120122

121123
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.
124+
125+
### `PauseManagerProvider` option
126+
127+
In case you want to disable updates to _all_ queries in an out of focus screen, one alternative is to control them via `PauseManager`:
128+
129+
```tsx
130+
import React from 'react'
131+
import { useIsFocused } from '@react-navigation/native'
132+
import { PauseManager, PauseManagerProvider } from 'react-native'
133+
134+
function MyScreen() {
135+
const isFocused = useIsFocused()
136+
const pauseManager = useRef<PauseManager>(null)
137+
if (pauseManager.current === null) {
138+
pauseManager.current = new PauseManager(!isFocused)
139+
}
140+
useEffect(() => {
141+
pauseManager.current?.setPaused(!isFocused)
142+
}, [isFocused])
143+
144+
return (
145+
<PauseManagerProvider pauseManager={pauseManager}>
146+
<MyComponent />
147+
</PauseManagerProvider>
148+
)
149+
}
150+
```

‎docs/framework/react/reference/PauseManagerProvider.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
id: PauseManagerProvider
3+
title: PauseManagerProvider
4+
---
5+
6+
Use the `PauseManagerProvider` component to connect and provide a `PauseManager` to your application which is used to selectively disable updates:
7+
8+
```tsx
9+
import { PauseManager, PauseManagerProvider } from '@tanstack/react-query'
10+
11+
const pauseManager = new PauseManager()
12+
13+
function App() {
14+
return <PauseManagerProvider client={pauseManager}>...</PauseManagerProvider>
15+
}
16+
```
17+
18+
**Options**
19+
20+
- `pauseManager: PauseManager`
21+
- **Required**
22+
- the PauseManager instance to provide

‎examples/react/pause/.eslintrc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"extends": ["plugin:react/jsx-runtime", "plugin:react-hooks/recommended"]
3+
}

‎examples/react/pause/.gitignore‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.js
7+
8+
# testing
9+
/coverage
10+
11+
# production
12+
/build
13+
14+
pnpm-lock.yaml
15+
yarn.lock
16+
package-lock.json
17+
18+
# misc
19+
.DS_Store
20+
.env.local
21+
.env.development.local
22+
.env.test.local
23+
.env.production.local
24+
25+
npm-debug.log*
26+
yarn-debug.log*
27+
yarn-error.log*

‎examples/react/pause/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Example
2+
3+
To run this example:
4+
5+
- `npm install`
6+
- `npm run dev`

‎examples/react/pause/index.html‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1" />
7+
<meta name="theme-color" content="#000000" />
8+
9+
<title>TanStack Query React Pause Example App</title>
10+
</head>
11+
<body>
12+
<noscript>You need to enable JavaScript to run this app.</noscript>
13+
<div id="root"></div>
14+
<script type="module" src="/src/index.tsx"></script>
15+
</body>
16+
</html>

‎examples/react/pause/package.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "@tanstack/query-example-react-pause",
3+
"private": true,
4+
"type": "module",
5+
"scripts": {
6+
"dev": "vite",
7+
"build": "vite build",
8+
"preview": "vite preview"
9+
},
10+
"dependencies": {
11+
"@tanstack/react-query": "^5.67.1",
12+
"@tanstack/react-query-devtools": "^5.67.1",
13+
"react": "^19.0.0",
14+
"react-dom": "^19.0.0"
15+
},
16+
"devDependencies": {
17+
"@vitejs/plugin-react": "^4.3.3",
18+
"typescript": "5.8.2",
19+
"vite": "^5.3.5"
20+
}
21+
}

‎examples/react/pause/public/emblem-light.svg‎

Lines changed: 13 additions & 0 deletions
Loading

‎examples/react/pause/src/index.tsx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
import ReactDOM from 'react-dom/client'
2+
import {
3+
PauseManager,
4+
PauseManagerProvider,
5+
QueryClient,
6+
QueryClientProvider,
7+
useQuery,
8+
} from '@tanstack/react-query'
9+
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
10+
import { memo, useRef, useSyncExternalStore } from 'react'
11+
12+
const queryClient = new QueryClient()
13+
const pauseManager = new PauseManager(true)
14+
15+
let counter = 1
16+
17+
const useCounter = () =>
18+
useQuery({
19+
queryKey: ['counter'],
20+
refetchOnMount: false,
21+
queryFn: () => counter++,
22+
})
23+
24+
export default function App() {
25+
return (
26+
<QueryClientProvider client={queryClient}>
27+
<ReactQueryDevtools />
28+
<Example />
29+
</QueryClientProvider>
30+
)
31+
}
32+
33+
function Example() {
34+
const { data, refetch } = useCounter()
35+
const isPaused = useSyncExternalStore(
36+
(onStoreChange) => pauseManager.subscribe(onStoreChange),
37+
() => pauseManager.isPaused(),
38+
)
39+
40+
return (
41+
<div>
42+
<p>Parent Counter: {data}</p>
43+
<div style={{ opacity: isPaused ? 0.5 : 1 }}>
44+
<PauseManagerProvider pauseManager={pauseManager}>
45+
<MemoisedChild />
46+
</PauseManagerProvider>
47+
</div>
48+
<button onClick={() => refetch()}>Increment</button>
49+
<button onClick={() => pauseManager.setPaused(!isPaused)}>
50+
{isPaused ? 'Resume' : 'Pause'}
51+
</button>
52+
</div>
53+
)
54+
}
55+
56+
const MemoisedChild = memo(() => {
57+
const { data } = useCounter()
58+
const renders = useRef(0)
59+
renders.current++
60+
61+
return (
62+
<>
63+
<p>Child counter: {data}</p>
64+
<p>Child renders: {renders.current}</p>
65+
</>
66+
)
67+
})
68+
69+
const rootElement = document.getElementById('root') as HTMLElement
70+
ReactDOM.createRoot(rootElement).render(<App />)

‎examples/react/pause/tsconfig.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"compilerOptions": {
3+
"target": "ES2020",
4+
"useDefineForClassFields": true,
5+
"lib": ["ES2020", "DOM", "DOM.Iterable"],
6+
"module": "ESNext",
7+
"skipLibCheck": true,
8+
9+
/* Bundler mode */
10+
"moduleResolution": "Bundler",
11+
"allowImportingTsExtensions": true,
12+
"resolveJsonModule": true,
13+
"isolatedModules": true,
14+
"noEmit": true,
15+
"jsx": "react-jsx",
16+
17+
/* Linting */
18+
"strict": true,
19+
"noUnusedLocals": true,
20+
"noUnusedParameters": true,
21+
"noFallthroughCasesInSwitch": true
22+
},
23+
"include": ["src", "eslint.config.js"]
24+
}

0 commit comments

Comments
 (0)