Open History to see the last commit
1---
2id: important-defaults
3title: Important Defaults
4---
5β
6Out of the box, TanStack Query is configured with **aggressive but sane** defaults. **Sometimes these defaults can catch new users off guard or make learning/debugging difficult if they are unknown by the user.** Keep them in mind as you continue to learn and use TanStack Query:
7β
8- Query instances via `useQuery` or `useInfiniteQuery` by default **consider cached data as stale**.
9β
10> To change this behavior, you can configure your queries both globally and per-query using the `staleTime` option. Specifying a longer `staleTime` means queries will not refetch their data as often
11β
12- A Query that has a `staleTime` set is considered **fresh** until that `staleTime` has elapsed.
13 - set `staleTime` to e.g. `2 * 60 * 1000` to make sure data is read from the cache, without triggering any kinds of refetches, for 2 minutes, or until the Query is [invalidated manually](./query-invalidation.md).
14 - set `staleTime` to `Infinity` to never trigger a refetch until the Query is [invalidated manually](./query-invalidation.md).
15 - set `staleTime` to `'static'` to **never** trigger a refetch, even if the Query is [invalidated manually](./query-invalidation.md).
16β
17> `'static'` and `Infinity` both prevent staleness-based refetches, but `'static'` is stricter: `queryClient.invalidateQueries()` can invalidate a query with `staleTime: Infinity`, but has no effect on `staleTime: 'static'`. `refetchOnMount`, `refetchOnWindowFocus`, and `refetchOnReconnect` set to `"always"` are also blocked by `'static'`. Use `'static'` for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use `Infinity` when you still want manual invalidation to work.
18β
19- Stale queries are refetched automatically in the background when:
20 - New instances of the query mount
21 - The window is refocused
22 - The network is reconnected
23β
24> Setting `staleTime` is the recommended way to avoid excessive refetches, but you can also customize the points in time for refetches by setting options like `refetchOnMount`, `refetchOnWindowFocus` and `refetchOnReconnect`.
25β
26- Queries can optionally be configured with a `refetchInterval` to trigger refetches periodically, which is independent of the `staleTime` setting. See [Polling](./polling.md) for details.
27β
28- Query results that have no more active instances of `useQuery`, `useInfiniteQuery` or query observers are labeled as "inactive" and remain in the cache in case they are used again at a later time.
29- By default, "inactive" queries are garbage collected after **5 minutes**.
30β
31 > To change this, you can alter the default `gcTime` for queries to something other than `5 * 60 * 1000` milliseconds.
32β
33- Queries that fail are **silently retried 3 times, with exponential backoff delay** before capturing and displaying an error to the UI.
34β
35 > To change this, you can alter the default `retry` and `retryDelay` options for queries to something other than `3` and the default exponential backoff function.
36β
37[//]: # 'StructuralSharing'
38β
39- Query results by default are **structurally shared to detect if data has actually changed** and if not, **the data reference remains unchanged** to better help with value stabilization with regards to useMemo and useCallback. If this concept sounds foreign, then don't worry about it! 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
40β
41[//]: # 'StructuralSharing'
42β
43> Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the `config.structuralSharing` flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can provide your own custom function as `config.structuralSharing` to compute a value from the old and new responses, retaining references as required.
44β
45[//]: # 'Materials'
46β
47## Further Reading
48β
49Have a look at the following articles from our [Community Resources](../../../community-resources) for further explanations of the defaults:
50β
51- [Practical React Query](https://tkdodo.eu/blog/practical-react-query)
52- [React Query as a State Manager](https://tkdodo.eu/blog/react-query-as-a-state-manager)
53- [Thinking in React Query](https://tkdodo.eu/blog/thinking-in-react-query)
54β
55[//]: # 'Materials'