Understanding invalidateQueries in React Query

Many developers swear by React Query for managing server state in React applications. One thing that makes React Query so powerful is that it can automatically refetch and synchronize data without too much configuration.

One of the most powerful tools is the invalidateQueries function, which lets you manually or automatically invalidate and refetch specific queries. In this post, we'll dive deep into how invalidateQueries works and explore some of the most helpful use cases.

What is invalidateQueries?

invalidateQueries is React Query’s way to manually invalidate and optionally refetch a query. By "invalidating" a query, we mean marking its data as outdated or stale. Once a query is marked as stale, React Query will automatically refetch it the next time that data is required, ensuring your application's data remains up-to-date.

How does it work?

Using invalidateQueries is straightforward. You can call it directly from the React Query's queryClient instance.

import { useQueryClient } from 'react-query';

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

  const handleClick = () => {
    queryClient.invalidateQueries('myQueryKey');
  }

  return (
    <button onClick={handleClick}>Invalidate My Query</button>
  );
}

In the above example, whenever the button is clicked, the query associated with the key 'myQueryKey' will be invalidated. If the staleTime for that query has elapsed or if it's set to 0, the query will be refetched automatically.

Advanced usage

invalidateQueries lets you do more than just invalidate a single query. It has a flexible API that allows developers to target multiple queries, use precise matching, and even control the refetching behavior.

Query key matching

You can invalidate multiple queries based on a shared prefix or an array of keys.

queryClient.invalidateQueries(['posts', { id: 1 }]);

In this case, any queries that begin with the 'posts' prefix and have an object with id: 1 in their query key will be invalidated.

Exact matching

By default, invalidateQueries uses a partial matching strategy. If you want to match a query key precisely, you can use the exact option.

queryClient.invalidateQueries('myQueryKey', { exact: true });

Controlling refetch

While invalidating a query makes it stale, you might sometimes want to refetch it immediately. The refetchActive and refetchInactive options allow you to control this behavior.

queryClient.invalidateQueries('myQueryKey', {
  refetchActive: true,
  refetchInactive: false,
});

In this case, only the active instances of the query will be refetched.

Use cases

Data mutations

One of the most common use cases for invalidateQueries is after a mutation. For example, if you have a list of posts and a user deletes one post, you might want to invalidate the 'posts' query to ensure the list is up-to-date.

Syncing across tabs

If your application is open in multiple tabs, you might want data changes in one tab to be reflected in others. invalidateQueries can be employed after certain events to synchronize data across different instances of your application.

User-triggered data refresh

Sometimes, you might want to give users the power to manually refresh data. A "Refresh" button that calls invalidateQueries provides a simple and effective solution.

Conclusion

React Query's invalidateQueries is a great tool. It gives you precise control over the lifecycle and freshness of data in an application. Whether you're looking to handle data mutations gracefully, give users more control, or manage complex application states across different instances, invalidateQueries covers that.