Optimistic UI

Optimistic UI

Optimistic UI shows the expected result before the server confirms it. It is a promise the UI makes on the server's behalf, so the whole craft is honoring or retracting that promise cleanly when the server disagrees.

Method

1. Apply it only to high-confidence, low-cost actions. Likes, toggles, reorders, adding a comment, checking a box: cheap to reverse, almost always succeed. Do not apply it to payments, irreversible deletes, or anything where a wrong optimistic result misleads a consequential decision. When in doubt about reversibility, show a pending state and wait.
2. Snapshot before you mutate. Capture the previous state before applying the optimistic change so rollback is a restore, not a guess. With TanStack Query, do this in onMutate: cancel in-flight refetches, snapshot the cache, write the optimistic value, and return the snapshot as context.
3. Roll back to the snapshot on error, and tell the user. On failure, restore the snapshot and surface a specific, non-blocking message ("Couldn't save, changes reverted") with a retry. Silent rollback is worse than a spinner: the user saw success, looked away, and the truth changed with no signal. Never leave the optimistic value stranded after a failed request.
4. Reconcile with the server's authoritative response. On success, replace the optimistic value with the server's returned entity (real id, server timestamps, computed fields) rather than trusting your guess. Invalidate or refetch the affected queries in onSettled so the cache converges to truth regardless of success or failure.
5. Handle conflicts, not just failures. If the server returns a newer version or a 409, the optimistic assumption was stale, not wrong-format. Decide the policy: last-write-wins, merge, or prompt the user. Send a version token or updated-at so the server can detect the conflict rather than clobbering a concurrent edit.
6. Signal pending state subtly, without blocking. Keep the optimistic value fully interactive and add a quiet in-flight cue (reduced opacity, a small inline spinner, a disabled duplicate action). Do not overlay a modal spinner that defeats the point. Debounce or queue rapid repeated mutations on the same entity so they do not race.

Boundaries

• Not for irreversible or high-stakes actions; use explicit pending states and server confirmation there.
• Multi-user real-time conflict resolution (CRDTs, OT) is a deeper problem than single-user optimism and out of scope.
• Requires a cache or store that supports snapshot and rollback; ad-hoc local state makes correct rollback hard.