When you perform a mutation—such as adding, updating, or deleting data on the server—your client-side cache can quickly become out-of-date. If your application continues to display cached data after a mutation, users may see stale or incorrect information. To prevent this, you need to invalidate relevant queries after a mutation. Invalidating a query tells TanStack Query that the cached data is no longer fresh and should be refetched from the server. This process is crucial for maintaining UI consistency, ensuring that your users always see the most up-to-date data without needing a full page reload.

Suppose you have a user management page that displays a list of users fetched with a query key like ["users"]. After successfully adding a new user with a mutation, you want the user list to update automatically. To achieve this, you call invalidateQueries in the onSuccess callback of your mutation. This action marks the users query as stale, prompting TanStack Query to refetch the user list and display the latest data, including the newly added user.

const queryClient = useQueryClient();

const addUserMutation = useMutation({
  mutationFn: addUser,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ["users"] });
  },
});

By invalidating the ["users"] query after the mutation, your UI will always reflect the current state of the server's data, keeping the user experience seamless and accurate.

To ensure your application remains robust and responsive, you should always invalidate or refetch queries that might be affected by a mutation. Some best practices for keeping data consistent after mutations include:

• Identify which queries are impacted by the mutation and invalidate only those, rather than all queries;
• Use descriptive query keys to make targeted invalidation easier;
• Leverage mutation callbacks like onSuccess to trigger invalidation, so updates happen only after confirmed server changes;
• Avoid unnecessary refetching to reduce network usage and improve performance;
• Consider edge cases, such as paginated or filtered queries, and invalidate all relevant variations when necessary.