Open History to see the last commit
1---
2id: polling
3title: Polling
4---
5β
6`refetchInterval` makes a query refetch on a timer. Set it to a number in milliseconds and the query runs every N ms while there's at least one active observer:
7β
8[//]: # 'Example1'
9β
10```tsx
11useQuery({
12 queryKey: ['prices'],
13 queryFn: fetchPrices,
14 refetchInterval: 5 * 1000, // every 5 seconds
15})
16```
17β
18[//]: # 'Example1'
19β
20Polling is independent of `staleTime`. A query can be fresh and still poll on schedule; see [Important Defaults](./important-defaults.md) for how `staleTime` interacts with other refetch behaviors. `refetchInterval` fires on its own clock regardless of freshness.
21β
22## Adapting the interval to query state
23β
24Pass a function instead of a number to compute the interval from the current query. The function receives the `Query` object and should return a number in ms or `false` to stop polling:
25β
26[//]: # 'Example2'
27β
28```tsx
29useQuery({
30 queryKey: ['job', jobId],
31 queryFn: () => fetchJobStatus(jobId),
32 refetchInterval: (query) => {
33 // Stop polling once the job finishes
34 if (query.state.data?.status === 'complete') return false
35 return 2 * 1000
36 },
37})
38```
39β
40[//]: # 'Example2'
41β
42Returning `false` clears the interval timer. If the query result changes so the function would return a positive number again, polling resumes automatically.
43β
44## Background polling
45β
46By default, polling pauses when the browser tab loses focus. For dashboards or any interface where data needs to stay current even while the user is in another tab, disable that behavior:
47β
48[//]: # 'Example3'
49β
50```tsx
51useQuery({
52 queryKey: ['portfolio'],
53 queryFn: fetchPortfolio,
54 refetchInterval: 30 * 1000,
55 refetchIntervalInBackground: true,
56})
57```
58β
59[//]: # 'Example3'
60β
61## Pausing polling
62β
63Pass a function to `refetchInterval` and close over component state to control when polling runs:
64β
65[//]: # 'Example4'
66β
67```tsx
68useQuery({
69 queryKey: ['prices', tokenAddress],
70 queryFn: () => fetchPrice(tokenAddress),
71 refetchInterval: () => {
72 if (!tokenAddress || isPaused) return false
73 return 15 * 1000
74 },
75})
76```
77β
78[//]: # 'Example4'
79β
80## Polling with offline support
81β
82TanStack Query detects connectivity by listening to the browser's `online` and `offline` events. In environments where those events don't fire reliably (Electron, some embedded WebViews), set `networkMode: 'always'` to skip the connectivity check:
83β
84[//]: # 'Example5'
85β
86```tsx
87useQuery({
88 queryKey: ['chainStatus'],
89 queryFn: fetchChainStatus,
90 refetchInterval: 10 * 1000,
91 networkMode: 'always',
92})
93```
94β
95[//]: # 'Example5'
96β
97For more on network modes, see [Network Mode](./network-mode.md).
98β
99## Note on deduplication
100β
101Each `QueryObserver` (each component using `useQuery` with `refetchInterval`) runs its own timer. Two components subscribed to the same key with `refetchInterval: 5 * 1000` each fire their timer every 5 seconds. What gets deduplicated is concurrent in-flight fetches: if two timers fire at the same time, only one network request goes out. The timers are observer-level; the deduplication is query-level.
102β
103[//]: # 'ReRenders'
104β
105## Note on re-renders
106β
107When a polling response contains the same data as before, a component that only reads `data` will not re-render. Structural sharing preserves the `data` reference, and tracked properties prevent re-renders caused by changes to properties the component doesn't use (see [Render Optimizations](./render-optimizations.md)). However, reading a property like `isFetching`, which changes on every polling cycle, will trigger re-renders.
108β
109As a result, values calculated from the current time during render won't update as long as the data remains unchanged. For example, a message that should appear after 30 seconds, such as "This is taking longer than expected," may never appear. Time-dependent UI state should be updated using a separate timer.
110β
111[//]: # 'ReRenders'
112[//]: # 'ReactNative'
113β
114## Non-browser environments
115β
116For non-browser runtimes like React Native, the standard `online`/`offline` and focus events aren't available. The [React Native guide](../react-native.md) covers how to connect `focusManager` and `onlineManager` to native app state APIs.
117β
118[//]: # 'ReactNative'