Keeping your application's data up-to-date is crucial for a seamless user experience, and TanStack Query provides robust tools for this purpose. One of the core features is background refetching, which ensures that the data you display is not stale without requiring users to manually refresh or reload. Background refetching occurs when TanStack Query detects that the data in the cache might be outdated and silently fetches the latest data from the server while the user continues to interact with the application. This process is invisible to the user and helps maintain consistency between the UI and the underlying data source.

Background refetching is triggered in several scenarios. By default, TanStack Query will automatically refetch data when the window regains focus, ensuring that users returning to your app always see the most current information. It can also be triggered at regular intervals if you configure the refetchInterval option, which is useful for data that changes frequently, such as real-time dashboards or notifications. Additionally, background refetching may occur when you manually invalidate a query, signaling that the cached data should be considered stale and re-fetched from the server.

Sometimes, you need to force a particular query to become stale and trigger a refetch, such as after a user updates or deletes an item. TanStack Query provides a simple way to do this using the QueryClient. The following example demonstrates how you can manually invalidate a query to ensure your data stays in sync:

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

function InvalidateButton() {
  const queryClient = useQueryClient();

  const handleInvalidate = () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] });
  };

  return (
    <button onClick={handleInvalidate}>
      Invalidate Todos Query
    </button>
  );
}

In this example, clicking the button calls invalidateQueries with the query key ['todos']. This marks the associated query as stale, prompting TanStack Query to refetch the data the next time it is accessed or according to its refetching rules.

Two powerful options for controlling background refetching behavior are refetchOnWindowFocus and refetchInterval. The refetchOnWindowFocus option determines whether a query should refetch when the browser window regains focus. By default, this is set to true, ensuring users always see fresh data when they return to your app. You can disable this by setting it to false if you want to avoid unnecessary network requests.

The refetchInterval option allows you to specify a time interval (in milliseconds) at which the query should automatically refetch in the background. For example, setting refetchInterval: 10000 will cause the query to refetch every 10 seconds. This is particularly useful for data that needs to be kept current in near real-time, such as live feeds or monitoring dashboards. Both options can be set per query, giving you fine-grained control over how and when your data updates.