snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/react/guides/caching.md

@@ -0,0 +1,33 @@
+---
+id: caching
+title: Caching Examples
+---
+
+> Please thoroughly read the [Important Defaults](./important-defaults.md) before reading this guide
+
+## Basic Example
+
+This caching example illustrates the story and lifecycle of:
+
+- Query Instances with and without cache data
+- Background Refetching
+- Inactive Queries
+- Garbage Collection
+
+Let's assume we are using the default `gcTime` of **5 minutes** and the default `staleTime` of `0`.
+
+- A new instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts.
+  - Since no other queries have been made with the `['todos']` query key, this query will show a hard loading state and make a network request to fetch the data.
+  - When the network request has completed, the returned data will be cached under the `['todos']` key.
+  - The data will be marked as stale after the configured `staleTime` (defaults to `0`, or immediately).
+- A second instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts elsewhere.
+  - Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache.
+  - The new instance triggers a new network request using its query function.
+    - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/functions/useQuery.md) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key.
+  - When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data.
+- Both instances of the `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` query are unmounted and no longer in use.
+  - Since there are no more active instances of this query, a garbage collection timeout is set using `gcTime` to delete and garbage collect the query (defaults to **5 minutes**).
+- Before the cache timeout (gcTime) has completed, another instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts. The query immediately returns the available cached data while the `fetchTodos` function is being run in the background. When it completes successfully, it will populate the cache with fresh data.
+- The final instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` unmounts.
+- No more instances of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` appear within **5 minutes**.
+  - The cached data under the `['todos']` key is deleted and garbage collected.