Optimistic Patterns with React Query and Zustand

React Query's useMutation hook provides built-in infrastructure for optimistic updates through three lifecycle callbacks: onMutate (fires before the mutation, return a context object), onError (fires on failure, receives the context), and onSettled (fires on success or failure). This structure is designed specifically for optimistic patterns.

In onMutate, you perform three steps: first, cancel any in-flight queries for the affected data (await queryClient.cancelQueries({ queryKey })), then snapshot the current cache (queryClient.getQueryData(queryKey)), and finally apply the optimistic update to the cache (queryClient.setQueryData(queryKey, updater)). Return the snapshot as context.

The onError callback receives the error, the mutation variables, and the context returned from onMutate. Use the context to rollback: queryClient.setQueryData(queryKey, context.previousData). The context is the bridge between the snapshot taken in onMutate and the rollback in onError.

The onSettled callback fires regardless of success or failure. Use it to refetch the query and sync with server state: queryClient.invalidateQueries({ queryKey }). This ensures that after any mutation — whether it succeeded (the server may have transformed data) or failed (rollback complete) — you eventually converge on server truth.

A practical example: toggling a todo's completed state. In onMutate, snapshot the todos list, then update the specific todo in cache. In onError, restore the snapshot from context. In onSettled, invalidate the todos query to refetch. The user sees the toggle instantly; the server syncs in the background.

In a Zustand store, optimistic updates are straightforward: create an action updateItem(id, changes) that immediately updates the item in the store, then calls the API. If the API fails, call another action revertItem(id, previousState). Zustand's synchronous state updates make the optimistic step instant.

When optimistically updating deeply nested Zustand state, use immer's produce for clean mutations: set(produce(state => { state.items[id] = { ...state.items[id], ...changes } })). Immer handles immutable updates with mutable syntax, making complex nested state changes readable and safe.

React 19 introduced useOptimistic(state, updateFn) as a built-in hook for optimistic updates within Server Actions. const [optimisticState, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]). Calling addOptimistic(newItem) immediately updates the UI while the server action runs asynchronously.

useOptimistic handles rollback automatically. When the Server Action completes (successfully or with an error), React reverts the optimistic state and applies the real state from the server. You do not need to write manual rollback logic — React manages the lifecycle of the optimistic update during the action's Suspense boundary.

Manual optimistic updates give full control but require boilerplate. React Query onMutate/onError/onSettled integrates with the query cache for automatic sync. useOptimistic is the simplest for Server Actions but requires React 19 and a server-action architecture. Choose based on your data layer: manual for simple local state, React Query for REST APIs, useOptimistic for RSC/Server Actions.

Consider your architecture when choosing an optimistic pattern. If you use React Query throughout your app, its onMutate pattern is consistent and cache-aware. If you use Zustand for global state, the action-based pattern fits naturally. If you are on React 19 with Server Actions, useOptimistic is the idiomatic choice. Mixing patterns within one app is common and acceptable.

What should the onMutate callback return in React Query to enable rollback in onError?

React Query useMutation uses onMutate (cancel queries, snapshot, apply optimistic update, return context), onError (restore snapshot from context), and onSettled (invalidate to refetch). Zustand optimistic updates call the state action immediately then the API, reverting on failure. React 19 useOptimistic provides automatic rollback within Server Actions. Choose the pattern that fits your data layer architecture.