When you work with data in React Query, keeping your UI up-to-date without overloading your app with unnecessary network requests is essential. Two important configuration options—staleTime and cacheTime—help you control how fresh your data should be and how long it should stay in memory.

The staleTime option defines how long fetched data is considered fresh. During this period, React Query will not automatically refetch the data when components mount or when the window regains focus. Once the staleTime has passed, the data becomes stale, and React Query may refetch it in the background if certain triggers occur, such as a window refocus or a network reconnect.

The cacheTime option controls how long inactive query data remains in the cache after the last observer (component using the query) unsubscribes. If another component requests the same data within the cacheTime, React Query can serve it instantly from cache. If the cacheTime expires, the cached data is garbage-collected, and a fresh fetch will occur the next time the query is used.

Background refetching is a powerful feature of React Query. When data is marked as stale and a trigger occurs, React Query can fetch new data in the background while keeping the stale data visible in the UI until the new data arrives. This approach ensures users see up-to-date information with minimal loading states, improving the perceived performance of your app.

Suppose you want to fetch a list of posts and ensure the data is considered fresh for 60 seconds, but you also want to keep it in cache for 5 minutes after it's no longer used. You can configure the useQuery hook like this:

import { useQuery } from '@tanstack/react-query';

function Posts() {
  const { data, isLoading, isFetching } = useQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    staleTime: 60_000,     // 60 seconds
    cacheTime: 300_000,    // 5 minutes
    refetchOnWindowFocus: true,
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {isFetching && <span>Refreshing...</span>}
      <ul>
        {data.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
}

In this example, after the initial fetch, the posts data is treated as fresh for 60 seconds. If a user navigates away from the page and returns within those 60 seconds, React Query will not refetch the data. After 60 seconds, the data becomes stale, and if the user refocuses the window, React Query will refetch the data in the background, showing the current data until the new data arrives. The cached data will remain available for 5 minutes after the component unmounts, allowing fast reloads if the user returns quickly.