When your application updates data on the server using a mutation, the local cached data in React Query may become outdated. This can cause your UI to display stale information until the next time the query runs. To ensure users always see the freshest data, you need a way to tell React Query that certain cached queries are now invalid and should be refetched from the server. This process is called query invalidation. Invalidating queries is essential after mutations because it keeps your UI in sync with the server, avoids displaying incorrect data, and provides a better user experience.

To trigger a refetch of specific queries after a mutation, you use the queryClient.invalidateQueries method. This method marks the specified queries as invalid, prompting React Query to refetch them the next time they are used or when the component remounts. Here is how you might use it in a mutation's onSuccess callback:

import { useMutation, useQueryClient } from "@tanstack/react-query";

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

  const mutation = useMutation({
    mutationFn: (newData) =>
      fetch("/api/data", {
        method: "POST",
        body: JSON.stringify(newData),
      }),
    onSuccess: () => {
      // Invalidate and refetch the "data" query after mutation succeeds
      queryClient.invalidateQueries({ queryKey: ["data"] });
    },
  });

  // ...UI code
}

In this example, whenever the mutation succeeds, the "data" query is invalidated and will be refetched, ensuring the UI displays the latest information from the server.