Polling

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:

useQuery({
  queryKey: ['prices'],
  queryFn: fetchPrices,
  refetchInterval: 5_000, // every 5 seconds
})

Polling is independent of staleTime. A query can be fresh and still poll on schedule; see Important Defaults for how staleTime interacts with other refetch behaviors. refetchInterval fires on its own clock regardless of freshness.

Pass 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:

useQuery({
  queryKey: ['job', jobId],
  queryFn: () => fetchJobStatus(jobId),
  refetchInterval: (query) => {
    // Stop polling once the job finishes
    if (query.state.data?.status === 'complete') return false
    return 2_000
  },
})

Returning false clears the interval timer. If the query result changes so the function would return a positive number again, polling resumes automatically.

By 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:

useQuery({
  queryKey: ['portfolio'],
  queryFn: fetchPortfolio,
  refetchInterval: 30_000,
  refetchIntervalInBackground: true,
})

Pass a function to refetchInterval and close over component state to control when polling runs:

useQuery({
  queryKey: ['prices', tokenAddress],
  queryFn: () => fetchPrice(tokenAddress),
  refetchInterval: () => {
    if (!tokenAddress || isPaused) return false
    return 15_000
  },
})

TanStack 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:

useQuery({
  queryKey: ['chainStatus'],
  queryFn: fetchChainStatus,
  refetchInterval: 10_000,
  networkMode: 'always',
})

For more on network modes, see Network Mode.

Each QueryObserver (each component using useQuery with refetchInterval) runs its own timer. Two components subscribed to the same key with refetchInterval: 5000 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.