TanStack Query: Optimistic Updates

TanStack Query: Optimistic Updates

Update the UI immediately on mutation and roll back automatically if the server request fails

When to Use

• Building UIs where server latency would make interactions feel sluggish (toggle, like, reorder)
• Implementing instant feedback for mutations like checkbox toggles, list reordering, or quantity adjustments
• Ensuring UI consistency when a mutation must succeed (e.g., adding to a local-only list)
• Rolling back UI changes when a network request fails rather than leaving the UI in an inconsistent state

Instructions

1. Use the onMutate callback to snapshot the current cache value and apply the optimistic update before the request fires.
2. Cancel any in-flight queries for the affected key in onMutate with queryClient.cancelQueries() to prevent race conditions.
3. Return the snapshot from onMutate — TanStack Query passes it to onError as context.
4. In onError, use the context (the snapshot) to restore the cache to its pre-mutation state with queryClient.setQueryData().
5. In onSettled, call queryClient.invalidateQueries() to sync the cache with the actual server state regardless of success or failure.
6. Use queryClient.setQueryData() with an updater function (not a value) to apply the optimistic change atomically.

// mutations/toggle-todo.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { todoKeys } from '@/queries/todos';

interface Todo {
  id: string;
  completed: boolean;
  title: string;
}

export function useToggleTodo() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, completed }: { id: string; completed: boolean }) =>
      fetch(`/api/todos/${id}`, {
        method: 'PATCH',
        body: JSON.stringify({ completed }),
      }).then((r) => r.json()),

    onMutate: async ({ id, completed }) => {
      // 1. Cancel in-flight refetches to avoid overwriting optimistic update
      await queryClient.cancelQueries({ queryKey: todoKeys.lists() });

      // 2. Snapshot the current value
      const previousTodos = queryClient.getQueryData<Todo[]>(todoKeys.list({}));

      // 3. Apply optimistic update
      queryClient.setQueryData<Todo[]>(
        todoKeys.list({}),
        (old) => old?.map((todo) => (todo.id === id ? { ...todo, completed } : todo)) ?? []
      );

      // 4. Return snapshot as context for rollback
      return { previousTodos };
    },

    onError: (_error, _variables, context) => {
      // Roll back to snapshot
      if (context?.previousTodos) {
        queryClient.setQueryData(todoKeys.list({}), context.previousTodos);
      }
    },

    onSettled: () => {
      // Sync with server regardless of success/failure
      queryClient.invalidateQueries({ queryKey: todoKeys.lists() });
    },
  });
}

Details

Optimistic updates are a UX pattern where the UI assumes a mutation will succeed and updates immediately, then corrects itself if the server disagrees. The key implementation detail is maintaining the ability to roll back.

Race condition prevention: Without cancelQueries, an in-flight background refetch could overwrite your optimistic update with stale server data while the mutation is in-flight. Cancelling in-flight queries for the affected key prevents this.

onMutate return value: Whatever onMutate returns becomes the context parameter in onError and onSettled. This is the standard channel for passing the snapshot to the rollback handler.

onSettled for final sync: Always call invalidateQueries in onSettled (not just onSuccess). Even on success, the server may have applied additional business logic that the optimistic update did not account for. onSettled fires on both success and error, ensuring the cache always reflects reality after the operation completes.

Updater functions: queryClient.setQueryData(key, updater) where updater is a function receives the current cached value and returns the new value. This is atomic — use it instead of reading and writing separately to avoid stale closure issues.

When NOT to use: For mutations where the user should wait for server confirmation before seeing UI changes (payments, irreversible actions), use pessimistic updates instead — update the cache only in onSuccess after the server confirms.

Source

https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.