Important Defaults
Purpose and Scope
TanStack Query ships with defaults that are intentionally active: cached data is treated as stale, stale queries refetch in common user-facing moments, inactive data remains cached for a short period, failed requests retry, and successful responses are structurally shared when possible. The official guide describes these as “aggressive but sane” defaults because they favor fresh server state without requiring every application to define a complete cache policy up front. For new users, the important task is not to disable everything, but to understand which default is responsible when a request, cache entry, retry, or render behaves differently than expected.
Sources: docs/framework/react/guides/important-defaults.md
This page focuses on the React guide because React Query users most often encounter these defaults through useQuery and useInfiniteQuery. The same concepts map to core TanStack Query behavior: query observers mount and unmount, cache entries become inactive when no observer is using them, invalidation can mark data stale, and configuration can be supplied globally or per query. The guide’s defaults are best read as a baseline contract: start with them, then tune only the dimensions where your product’s freshness, network, or rendering requirements differ.
Sources: docs/framework/react/guides/important-defaults.md
Relevant Source Files
docs/framework/react/guides/important-defaults.md— Defines the documented default behavior for stale data,staleTime, automatic background refetch triggers,refetchInterval, inactive query garbage collection, retry behavior, and structural sharing.
Freshness and Staleness Defaults
By default, query instances created with useQuery or useInfiniteQuery consider cached data stale. Stale does not mean unusable or deleted; it means the cached value is eligible for background synchronization. A component can receive cached data immediately and still cause TanStack Query to check the server again. This is one of the most important distinctions in the library: the cache is used for responsiveness, while staleness controls whether the library should verify that the cache still matches the server.
Sources: docs/framework/react/guides/important-defaults.md
The primary control for this behavior is staleTime. When a query has a staleTime, it is considered fresh until that duration has elapsed. For example, a value like 2 * 60 * 1000 means the query can read from cache for two minutes without staleness-driven refetches unless it is manually invalidated. Infinity prevents refetches caused by becoming stale, but still allows manual invalidation to matter. The special value 'static' is stricter: even manual invalidation and "always" refetch settings do not trigger a refetch for that query.
Sources: docs/framework/react/guides/important-defaults.md
Use staleTime as the first tuning knob when an application appears to refetch too often. A product catalog that rarely changes might tolerate minutes of freshness, while a collaboration dashboard may need data to become stale almost immediately. The guide explicitly recommends setting staleTime to avoid excessive refetches before reaching for more specific trigger options. Choose 'static' only for data that cannot change during the current app session, such as boot-time feature flags, login-scoped permissions, or static reference tables.
Sources: docs/framework/react/guides/important-defaults.md
Automatic Refetching and Polling
Stale queries refetch automatically in the background at three important moments: when a new instance of the query mounts, when the window is refocused, and when the network reconnects. These triggers explain many “why did this request run again?” debugging sessions. TanStack Query assumes that returning to a screen, returning to a browser tab, or recovering connectivity are good opportunities to synchronize server state while preserving the existing cached result for the user interface.
Sources: docs/framework/react/guides/important-defaults.md
If those synchronization points are not appropriate, configure refetchOnMount, refetchOnWindowFocus, and refetchOnReconnect. These options control when refetches are attempted, but they should usually be considered after staleTime, because a fresh query avoids the staleness-driven need to refetch in the first place. The guide also separates refetchInterval from staleness: polling can be configured to refetch periodically and is independent of the staleTime setting, which makes it useful for live views that should update on a timer.
Sources: docs/framework/react/guides/important-defaults.md
Cache Retention, Retries, and Structural Sharing
When a query no longer has active useQuery, useInfiniteQuery, or query observer instances, TanStack Query labels it inactive. Inactive data is not immediately removed; it remains in the cache so that a later mount can reuse it. By default, inactive queries are garbage collected after five minutes, represented by 1000 * 60 * 5 milliseconds. Tune gcTime when you need a longer back-navigation cache, a shorter memory footprint, or different retention behavior for large result sets.
Sources: docs/framework/react/guides/important-defaults.md
Failed queries are silently retried three times with exponential backoff before the error is captured and surfaced to the UI. This default absorbs transient failures, such as brief network instability, without making every component implement retry logic. It can also surprise developers when a failing endpoint appears to take longer before showing an error. Use the retry and retryDelay options when an operation should fail fast, when a backend has strict rate limits, or when a custom retry policy is needed.
Sources: docs/framework/react/guides/important-defaults.md
Query results are structurally shared by default. Structural sharing means TanStack Query compares JSON-compatible result values so that unchanged data can keep the same reference. That stability helps React patterns such as useMemo and useCallback because unchanged data does not force new references unnecessarily. The guide notes that most applications should leave this enabled. If responses are very large, or if query results contain non-JSON-compatible values that need custom change detection, configure config.structuralSharing or provide a custom structural sharing function.
Sources: docs/framework/react/guides/important-defaults.md
Compact Defaults Reference
| Behavior | Default | Primary tuning option | Practical effect |
|---|---|---|---|
| Query freshness | Cached query data is stale by default | staleTime | Cached data can render immediately while background refetches remain eligible |
| Fresh window | Fresh until configured time elapses | staleTime | Longer values reduce staleness-driven refetches |
| Never stale by time | Manual invalidation still works | staleTime: Infinity | Use when data should not refetch unless explicitly invalidated |
| Static data | Invalidation and "always" refetch triggers are blocked | staleTime: 'static' | Use only for data that cannot change during the app session |
| Background refetch | On mount, window focus, and reconnect for stale queries | refetchOnMount, refetchOnWindowFocus, refetchOnReconnect | Keeps server state synchronized at common interaction points |
| Polling | Optional and independent of staleTime | refetchInterval | Supports timed refresh workflows |
| Inactive query retention | Garbage collected after five minutes | gcTime | Keeps recently unused data available for later reuse |
| Failed query retry | Three retries with exponential backoff | retry, retryDelay | Hides transient failures before surfacing an error |
| Result references | JSON-compatible structural sharing enabled | config.structuralSharing | Preserves references when data has not actually changed |
Implementation Guidance
When debugging default behavior, identify which phase you are observing. If a request runs after returning to a tab, inspect freshness and focus refetch settings. If data disappears after leaving a screen for several minutes, inspect inactivity and gcTime. If an error appears delayed, inspect retry settings. If a component rerenders less than expected after equivalent data arrives, structural sharing may be preserving references intentionally. Working from the default category to the specific option usually leads to smaller, safer configuration changes.
Sources: docs/framework/react/guides/important-defaults.md
For a first production configuration, define global defaults only where the whole application agrees, then override individual queries for special cases. Many teams set a modest global staleTime, keep retries enabled for idempotent reads, and customize gcTime only for memory-sensitive or navigation-heavy areas. Next, read the pages on cache lifecycle, background refetching, retries and cancellation, and query options so that each default can be tuned in the place where it belongs rather than hidden in unrelated component code.