Fixed-interval polling
A dashboard needs periodically refreshed prices, metrics, or status data.
TanStack · Pipe
refetchInterval
refetchInterval makes a query poll on a timer. Use milliseconds for a fixed schedule or a callback for state-dependent polling that can stop by returning false.
How it works
Set refetchInterval to a millisecond number for continuous polling, or provide a function that receives the current Query and returns a millisecond interval. Returning false stops and clears the timer; polling operates independently of staleTime while an active observer exists.
Syntax
refetchInterval: number | false | ((query: Query) => number | false)Parameters
| Name | Type | Description |
|---|---|---|
refetchInterval | number | false | ((query: Query) => number | false) | Polling period in milliseconds, false, or a function receiving Query and returning milliseconds or false. |
Key points
- refetchInterval enables timer-driven query refetching.
- A numeric setting defines the period in milliseconds and operates while at least one observer is active.
- A callback can calculate a dynamic period from Query state or disable polling by returning false.
- Polling can restart automatically when the callback once again produces a positive interval.
- Separate timers still share deduplication for concurrent in-flight requests.
Common mistakes
- A fresh query can still refetch on its polling schedule; staleTime does not disable refetchInterval.
- Multiple components observing the same key create separate polling timers, even though simultaneous in-flight requests are deduplicated.
- Return false when polling should stop; a later positive result resumes polling automatically if the query result changes.
Example: Stop polling when a job completes
import { useQuery } from '@tanstack/react-query'
type Job = { status: 'running' | 'complete' }
async function fetchJob(): Promise<Job> {
const response = await fetch('/api/job')
if (!response.ok) throw new Error('Request failed')
return response.json()
}
export function JobStatus() {
const query = useQuery({
queryKey: ['job'],
queryFn: fetchJob,
refetchInterval: (query) =>
query.state.data?.status === 'complete' ? false : 2_000,
})
return <p>{query.data?.status ?? 'Loading...'}</p>
}Polls the job every two seconds until the returned status is complete, then stops the timer.
When to use it
Conditional job polling
A background job exposes a status endpoint until it reaches a terminal state.
State-controlled polling
Polling should pause while a component lacks required input or is explicitly paused.
Interview questions
QWhat forms can refetchInterval take?
A numeric value is interpreted as a polling period in milliseconds, so the query refetches repeatedly at that frequency while it has an active observer. A function is evaluated with the current Query and must return either a millisecond period or false.
Follow-up: How would you stop polling after a terminal response? Return false from the callback when query.state.data indicates completion; this clears the timer.
QHow does refetchInterval interact with staleTime?
Polling uses its own schedule and is not governed by staleTime. Therefore, a query may remain fresh while refetchInterval still triggers network requests.
Follow-up: What should be changed if the requirement is freshness-based refetching rather than timed polling? Configure staleTime and the relevant refetch-on-event behavior instead of relying on refetchInterval.
QHow can polling be made conditional?
The callback receives the Query object, allowing the interval to depend on current query state. It can return false to pause polling or a positive millisecond value to continue it.
Follow-up: Can polling resume after stopping? Yes. If a later query result makes the callback return a positive interval again, polling resumes automatically.
Related
refetchIntervalInBackgroundstaleTimeuseQueryQueryObserver