TanStack Query — optimistic updates with rollback on error

After a mutation the UI waits for the server response before reflecting changes. For fast actions (like toggling a like button), this creates noticeable lag. Optimistic updates apply the change immediately and roll back if the server rejects it.

Use onMutate to apply optimistic state, onError to roll back, and onSettled to refetch:

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

function LikeButton({ postId }: { postId: number }) {
const queryClient = useQueryClient();

const likeMutation = useMutation({
mutationFn: (id: number) =>
fetch(/api/posts/${id}/like, { method: 'POST' }).then((r) => r.json()),

onMutate: async (id) => {
// Cancel in-flight queries for this post
await queryClient.cancelQueries({ queryKey: ['posts', id] });

// Snapshot the previous value
const previous = queryClient.getQueryData<Post>(['posts', id]);

// Optimistically update
queryClient.setQueryData<Post>(['posts', id], (old) =>
old ? { ...old, likes: old.likes + 1 } : old
);

return { previous };
},

onError: (_err, id, context) => {
// Roll back to the snapshot
if (context?.previous) {
queryClient.setQueryData(['posts', id], context.previous);
}
},

onSettled: (_data, _err, id) => {
// Always refetch to sync with server truth
queryClient.invalidateQueries({ queryKey: ['posts', id] });
},
});

return <button onClick={() => likeMutation.mutate(postId)}>Like</button>;
}

cancelQueries prevents an in-flight GET from overwriting the optimistic update. The context object returned from onMutate is passed to onError and onSettled, enabling rollback with the snapshotted value.