Tune inactive-cache retention
Retain query results for a controlled period after a component unmounts.
TanStack · Pipe
gcTime
gcTime specifies how long unused or inactive TanStack Query cache data stays in memory before garbage collection. It defaults to five minutes, is Infinity during SSR, and can be set to Infinity to disable collection.
- Since
- 5.0.0
How it works
gcTime controls how long inactive query data remains in memory after the query has no subscribers. Once that period expires, TanStack Query garbage-collects the data; it does not limit retention while the query is actively used. The longest configured duration applies, Infinity disables collection, and SSR defaults to Infinity.
Syntax
gcTime?: numberParameters
| Name | Type | Description |
|---|---|---|
gcTime | number | undefined | Retention duration, in milliseconds, for unused or inactive query cache data. |
Key points
- Set gcTime as a duration in milliseconds for retaining inactive query data.
- The countdown starts when the query becomes unused or inactive, not while it has active observers.
- Use Infinity when inactive cached data should not be automatically collected.
- The standard default is five minutes, while server-side rendering uses Infinity.
Common mistakes
- A shorter gcTime does not override a longer duration configured elsewhere.
- Very large durations exceed the normal JavaScript timer limit unless a custom timeout provider is used.
Example: Configure unused-query retention
import { QueryClient, useQuery } from '@tanstack/react-query'
const queryClient = new QueryClient({
defaultOptions: {
queries: { gcTime: 1000 * 60 * 60 * 24 },
},
})
export function Todos() {
const query = useQuery({
queryKey: ['todos'],
queryFn: () => fetch('/api/todos').then((r) => r.json()),
gcTime: 1000 * 60 * 5,
})
return <pre>{JSON.stringify(query.data)}</pre>
}This query keeps unused data for five minutes, while the client default retains other query data for one day.
When to use it
Coordinate persistence and garbage collection
Keep hydrated or persisted data available long enough for the persistence policy.
Disable collection
Prevent automatic removal of inactive data in a long-lived client.
Interview questions
QWhat does gcTime control?
gcTime is the retention period for unused or inactive query data. It begins to matter only after a query is no longer in use; expiration then allows the cached data to be garbage-collected.
Follow-up: How does it interact with multiple configurations? The longest specified garbage-collection duration is used.
QWhat are the defaults, and how can garbage collection be disabled?
The default is five minutes in normal operation and Infinity during SSR. Setting gcTime to Infinity disables garbage collection, so inactive data is not automatically removed.
Follow-up: What value should be used with persisted queries? Set gcTime to the same value or higher than the persistence maxAge.
QHow does gcTime differ from staleTime?
gcTime is distinct from staleTime. staleTime determines when data becomes stale, whereas gcTime determines how long unused data remains in memory before collection.
Follow-up: What limits unusually long gcTime values? The ordinary timer implementation supports roughly 24 days; timeoutManager.setTimeoutProvider can provide a workaround.
Related
staleTimeQueryClientdefaultOptions.queriespersistQueryClienttimeoutManager.setTimeoutProvider