Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Caching and Staleness

Stale Time and Garbage Collection Time

The two timers that drive TanStack Query caching: staleTime decides when data needs a refresh, gcTime when unused data is deleted. Learn the lifecycle and how to tune both.

Two numbers decide nearly everything about how TanStack Query behaves over time: staleTime and gcTime. They sound similar and are often confused, but they answer different questions. staleTime asks, "for how long do I trust this data without asking the server again?" gcTime asks, "for how long do I keep data in memory after nobody is using it?" Understanding the difference removes the mystery from most "why did it refetch?" and "why is it still showing old data?" questions.

The life of a cache entry

flowchart LR
  A["Fetched: fresh"] -->|"staleTime passes"| B["Stale"]
  B -->|"last component unmounts"| C["Inactive"]
  A -->|"last component unmounts"| C
  C -->|"gcTime passes"| D["Garbage collected"]
  C -->|"component mounts again"| B

A cache entry moves from fresh to stale with time, becomes inactive when nobody observes it, and is deleted after gcTime.

  • Fresh: the data was fetched less than staleTime ago. Query serves it from the cache and will not refetch it automatically.
  • Stale: older than staleTime. Query still shows it instantly, but refetches in the background when a trigger occurs (a new component mounts, the window regains focus, the network reconnects).
  • Inactive: no component observes the entry right now. The data stays in memory.
  • Garbage collected: an inactive entry older than gcTime is deleted. The next use will show a loading state again.

The two clocks are independent. staleTime counts from the time of the last successful fetch. gcTime counts from the moment the entry became inactive.

Defaults

Option Default Meaning
staleTime 0 Data is stale immediately
gcTime 5 * 60 * 1000 (5 minutes) Unused data is kept five minutes

A default staleTime of zero is deliberately cautious: any trigger refetches. That keeps data correct, but it can mean more requests than you need. Most real apps raise staleTime for data that changes slowly.

staleTime in action

Here the same query is mounted and unmounted. Choose a stale time, then hide and show the value. The number of requests tells you whether the cache was trusted.

Changing staleTime

(The counter is read during render, so it refreshes the next time the component re-renders; press Hide and Show to see it advance.)

Choosing a staleTime

There is no universal value. Ask how wrong the data is allowed to be, and for how long.

Kind of data Reasonable staleTime
A stock ticker, chat messages 0 (always refetch) or use polling
A product list, a feed 30 seconds to a few minutes
User profile, settings 5 to 30 minutes
Country lists, feature flags, static config Infinity

staleTime: Infinity means "never refetch automatically"; you refresh by invalidation. Many apps set a sensible default in the QueryClient (for example one minute) and override it where it matters. The staleTime option can also be a function of the query, (query) => number, for rules that depend on the data.

gcTime in action

gcTime only matters for inactive data. While a component observes an entry, it will not be collected. When the last observer unmounts, the countdown starts, and if a component mounts again before it expires, the countdown is cancelled and the data is reused.

Garbage collection with a short gcTime

Use a short gcTime for large payloads you do not want sitting in memory. Use a long one when you want back-navigation to feel instant. gcTime: Infinity disables collection. Setting it to 0 removes data the moment it is unused, which is also how tests avoid state leaking between cases.

gcTime should not be shorter than the time the user may spend away from a page if you want instant back-navigation. When you persist the cache (for example to local storage), gcTime also has to be at least as long as the time restored data should stay valid, otherwise it is deleted right after restoring.

They work together

A typical setup for a content app is staleTime: 60_000 and the default gcTime. Navigating to a page you visited 20 seconds ago shows the cached data at once and makes no request. Visiting one 90 seconds later shows the same cached data and refreshes it quietly in the background. Visiting one after 10 minutes of absence shows a normal loading state, because the entry was collected.

Next you will see exactly which events cause a stale query to refetch in Refetch Triggers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does staleTime control?

    While data is fresh, Query serves it from the cache without a background refetch.
  2. 2. What does gcTime control?

    The gcTime countdown starts when the last observer unmounts.
  3. 3. Defaults for staleTime and gcTime are...

    Data is stale immediately (0), and unused data lives five minutes.
  4. 4. Which setting suits a list of countries that practically never changes?

    Infinity means the data is never refetched automatically, which fits static reference data.

Summary

  • staleTime (default 0) decides how long data is fresh; gcTime (default 5 minutes) decides how long inactive data stays in memory.
  • Stale data is still shown immediately and refetched in the background when a trigger occurs.
  • A cache entry is garbage collected only when it is inactive for gcTime.
  • Pick staleTime by how quickly the data changes; use Infinity for static data.
  • Set sensible defaults on the QueryClient and override them per query.

Next: Refetch Triggers