Reduce redundant refetches
Data changes occasionally and short-term cached reads are acceptable.
TanStack · Pipe
staleTime
staleTime defines how long cached query data stays fresh. Increasing it reduces stale-driven refetches; Infinity waits for manual invalidation, while 'static' prevents even that from triggering a refetch.
How it works
staleTime controls how long query data remains fresh after it is received. During that window, the cache can satisfy reads without stale-driven refetches; once it expires, normal background refetch triggers can apply. Infinity prevents staleness until manual invalidation, while 'static' also prevents manual invalidation from triggering a refetch.
Syntax
staleTime: number | "static" | ((query: Query<TQueryFnData, TError, TQueryData, TQueryKey>) => number | "static")Parameters
| Name | Type | Description |
|---|---|---|
staleTime | number | "static" | ((query) => number | "static") | Freshness duration in milliseconds, or the special value 'static'. A function form can compute the value from the query. |
Key points
- Configure staleTime either in global query defaults or on an individual query.
- Longer freshness windows generally reduce stale-driven refetch frequency.
- Data remains fresh until the configured duration passes.
- A two-minute staleTime lets reads use cached data without stale-driven refetches during that period.
- After becoming stale, a query may refetch in the background when a new instance mounts.
- Window refocus is another automatic background-refetch trigger for stale queries.
- Network reconnection can also trigger a background refetch once the query is stale.
Common mistakes
- Do not choose 'static' when manual invalidation must still work; use Infinity instead.
- staleTime does not disable a separately configured refetchInterval.
Example: Configure a global staleTime
import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query'
const queryClient = new QueryClient({
defaultOptions: {
queries: { staleTime: 2 * 60 * 1000 },
},
})
function Todos() {
const { data } = useQuery({
queryKey: ['todos'],
queryFn: () => fetch('/api/todos').then((r) => r.json()),
})
return <pre>{JSON.stringify(data, null, 2)}</pre>
}
export function App() {
return <QueryClientProvider client={queryClient}><Todos /></QueryClientProvider>
}Sets a two-minute freshness window globally, so cached todo data is reused during that period without stale-driven refetches.
When to use it
Protect static reference data
Data is immutable for the lifetime of the running application.
Coordinate manual refreshes
Data should remain fresh until an explicit application event invalidates it.
Interview questions
QWhat does staleTime control?
staleTime is the duration, in milliseconds, for which fetched data is treated as fresh. A longer value reduces stale-driven refetches, while the default behavior treats cached data as stale.
Follow-up: How would you keep boot-time reference data from refetching? Use 'static' when it cannot change during the app session; use Infinity if manual invalidation should remain effective.
QWhat is the difference between Infinity and 'static'?
A query with staleTime: Infinity does not become stale automatically, so it avoids refetches caused by staleness. Manual invalidation can still invalidate it and allow a refetch.
Follow-up: What is the stricter alternative? staleTime: 'static', which remains non-refetching even after manual invalidation.
QDoes staleTime prevent every refetch?
staleTime is separate from refetchInterval. An interval can periodically refetch a query regardless of whether staleTime has elapsed.
Follow-up: Which other events can refetch stale queries? New mounts, window refocus, and network reconnection, unless their refetch options are customized.
Related
QueryClientQueryObserverOptionsrefetchIntervalrefetchOnMountrefetchOnWindowFocusrefetchOnReconnectinvalidateQueries