If you’re using TanStack Query (formerly known as React Query) to manage server state in your frontend application, you’ve probably come across two important settings: staleTime and gcTime.
At first glance, both deal with caching and data retention — but they serve very different purposes.
I want to break them down in plain language based on my own hands-on experience, because once I truly understood the distinction, my API efficiency improved significantly, and I avoided unnecessary network traffic.
TL;DR
staleTime: How long fetched data is considered “fresh” (i.e., it prevents automatic re-fetching).gcTime: How long unused data stays in memory before being garbage collected.
Now let’s explore both with real-world examples.
What is staleTime?
In TanStack Query, every piece of data fetched is assumed to become stale immediately by default. This means that if a query is triggered again (e.g., when a component mounts), it will refetch the data from the server — unless you configure a staleTime.
✅ Example Use Case:
You fetch a user profile when a dashboard mounts. If you set staleTime to 5 minutes, the data will be treated as fresh for those 5 minutes. During that time:
- Any re-renders or remounts using the same query key will not trigger a new network request.
- The cached data will be reused instantly.
- After 5 minutes, if the component remounts or a background refetch is triggered, it will now fetch new data from the server.
This is incredibly helpful when your data doesn’t change frequently and you want to avoid over-fetching.
🧠 Default Value: staleTime is 0 by default, meaning data is stale immediately after fetching.
What is gcTime?
gcTime, or garbage collection time, defines how long cached data remains in memory after no components are using it.
In other words, after all components that use a certain query are unmounted, TanStack Query will wait for gcTime before deleting that cached data.
✅ Example Use Case:
You have a blog list component that fetches articles. Once the user navigates away from that component, TanStack Query starts a timer. If gcTime is set to 10 minutes, the query data stays in memory for 10 minutes:
- If the user returns to the page within those 10 minutes, the old cache is reused.
- After 10 minutes, if the data hasn’t been used again, it is garbage collected (deleted from memory).
This makes gcTime great for memory management — especially when building SPAs where users frequently navigate between pages.
🧠 Default Value: gcTime is set to 5 minutes by default.
Real-World Analogy
Think of staleTime as the expiration date on milk:
- It’s still considered good (fresh) for a few days after you open it.
- But after that, you’ll need a new one.
gcTime, on the other hand, is like how long you keep milk in the fridge after you’ve decided to stop drinking it.
Even if it’s still in the fridge (memory), you’ll eventually throw it out.
Practical Tips from Experience
As a frontend developer who has used TanStack Query extensively in production apps, here are some lessons learned:
- Set
staleTimegenerously if your data doesn’t change often (e.g., user profile, metadata). - Use short
staleTime(or keep it at 0) if your data changes frequently (e.g., stock prices, chat messages). - Adjust
gcTimebased on how likely the user is to return to a page quickly. For high-traffic components, a longergcTimecan improve perceived speed.
Conclusion
Both staleTime and gcTime are powerful tools that help you balance performance, freshness, and memory efficiency in your frontend app.
To summarize:
staleTimecontrols when a refetch happens.gcTimecontrols when the data is cleared from memory.
Understanding these two properly is the key to building efficient, smooth, and scalable React applications using TanStack Query.
