Implementing Bulletproof Optimistic UI with TanStack Query and Rollback Strategies
Make your web applications feel instantaneous. Learn how to update cache state optimistically, handle offline queues, manage temporary UUIDs, build optimistic drag-and-drop Kanban boards, and roll back cleanly on server errors.
The Speed Expectation: Perceived Latency vs Real Latency
When users interact with modern software (toggling a task, starring an item, posting a comment), waiting 400ms for a round-trip network request to show feedback makes an application feel sluggish.
Optimistic UI solves this by updating the user interface instantaneously before the HTTP request even reaches the server. In 99.5% of cases, the server operation succeeds, giving the user a zero-latency tactile experience.
However, naive optimistic UI is dangerous. If the network drops or the server returns a 422 validation error, failing to roll back leaves the user with an inconsistent phantom state. TanStack Query provides a robust transactional framework for optimistic updates and automated rollbacks.
Building robust optimistic mutations requires defensive snapshotting, clean error recovery, and proper synchronization of client-generated IDs.
The 4-Step Optimistic Mutation Lifecycle
TanStack Query's `useMutation` hook orchestrates optimistic updates across four sequential lifecycle phases:
Step 1: `onMutate`. Cancel outgoing refetches to prevent incoming stale data from overwriting your optimistic update. Snapshot previous cache data as context, then manually inject the optimistic record into the query cache using `queryClient.setQueryData`.
Step 2: Server Execution. The mutation function sends the request over the network.
Step 3: `onError`. If the request fails, read the snapshot context and roll the query cache back to its pre-mutation state, accompanied by a user notification toast.
Step 4: `onSettled`. Regardless of success or failure, invalidate the query key so the cache resynchronizes with true server authority.
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { toast } from "sonner";
interface Task {
id: string;
title: string;
completed: boolean;
}
export function useOptimisticToggleTask() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async ({ taskId, completed }: { taskId: string; completed: boolean }) => {
const res = await fetch(`/api/tasks/${taskId}`, {
method: "PATCH",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ completed }),
});
if (!res.ok) throw new Error("Server failed to update task status");
return res.json();
},
onMutate: async ({ taskId, completed }) => {
// 1. Cancel in-flight queries
await queryClient.cancelQueries({ queryKey: ["tasks"] });
// 2. Snapshot current state for rollback
const previousTasks = queryClient.getQueryData<Task[]>(["tasks"]);
// 3. Optimistically update the cache
queryClient.setQueryData<Task[]>(["tasks"], (old = []) =>
old.map((task) => (task.id === taskId ? { ...task, completed } : task))
);
return { previousTasks };
},
onError: (err, variables, context) => {
// 4. Rollback to snapshot on error
if (context?.previousTasks) {
queryClient.setQueryData(["tasks"], context.previousTasks);
}
toast.error("Failed to update task. Changes reverted.");
},
onSettled: () => {
// 5. Always refetch to ensure server parity
queryClient.invalidateQueries({ queryKey: ["tasks"] });
},
});
}Managing Optimistic Identifiers (Temp IDs) in Creation Flows
When optimistically creating new records (such as appending a comment), the server has not yet generated a permanent database UUID. If the user immediately clicks edit or delete on that newly added item, referencing a missing ID triggers runtime errors.
Assign a client-generated temporary UUID (`crypto.randomUUID()`) and flag the item with `isOptimistic: true`. Disable secondary actions (like deletion) on the item until the server responds with the permanent entity.
When the server returns the persistent ID, replace the temporary identifier atomically in the cache.
Optimistic Drag-and-Drop List Reordering with Lexorank
Drag-and-drop interfaces feel unacceptably broken if cards snap back while waiting for server ranking updates.
Store array reorders immediately in local query cache, send fractional index weights (`Lexorank`) to the backend, and silently recover positions if a network error occurs.
Fractional indexing ensures that reordering a single card between position 2 and 3 requires updating only that single record's rank string, rather than re-indexing every item in the entire database table.
import { LexoRank } from "lexorank";
export function calculateNewLexoRank(prevRank?: string, nextRank?: string): string {
if (!prevRank && !nextRank) return LexoRank.middle().toString();
if (!prevRank) return LexoRank.parse(nextRank!).prev().toString();
if (!nextRank) return LexoRank.parse(prevRank).next().toString();
const prev = LexoRank.parse(prevRank);
const next = LexoRank.parse(nextRank);
return prev.between(next).toString();
}
// In the UI onDragEnd:
function handleCardDrop(activeId: string, overIndex: number, items: CardItem[]) {
const prev = items[overIndex - 1]?.rank;
const next = items[overIndex + 1]?.rank;
const newRank = calculateNewLexoRank(prev, next);
// Instantly apply new rank in memory:
updateCardRankOptimistically({ cardId: activeId, newRank });
}Offline-First Persistence with IndexedDB and Background Sync
To survive subway commutes or spotty mobile connections, persist TanStack Query mutations to IndexedDB using experimental persisters.
When internet connectivity drops, queue mutations locally. When the browser triggers the `online` window event, flush queued mutations sequentially with exponential backoff retries.
This architecture ensures that field technicians or mobile users can continue working uninterrupted regardless of fluctuating cellular coverage.
import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";
import { persistQueryClient } from "@tanstack/react-query-persist-client";
import { get, set, del } from "idb-keyval";
const idbStorage = {
getItem: async (key: string) => (await get(key)) ?? null,
setItem: async (key: string, value: string) => set(key, value),
removeItem: async (key: string) => del(key),
};
export function setupOfflinePersistence(queryClient: QueryClient) {
persistQueryClient({
queryClient,
persister: createSyncStoragePersister({ storage: idbStorage as any }),
maxAge: 1000 * 60 * 60 * 24 * 7, // 7 days offline retention
});
}Mutation Key Deduplication and Concurrent Collision Handling
When users rapidly double-click a toggle button or simultaneously trigger conflicting mutations across two open browser tabs, race conditions occur. The earlier request might resolve after the later request, leaving stale state in the database.
TanStack Query provides mutation scopes and mutation keys (`mutationKey: ['tasks', taskId]`). By scoping mutations, you can configure `scope.id` so that rapid successive clicks on the same item are serialized or deduplicated, preventing conflicting database writes.
// Serializes successive mutations on the same task ID
export const taskMutationOptions = (taskId: string) => ({
mutationKey: ["tasks", taskId],
scope: { id: `task-${taskId}` },
networkMode: "always" as const,
retry: 3,
});How do we handle slow 3G network connections with optimistic UI?
Set a mutation timeout. If the server does not respond within 8 seconds, transition the optimistic item to a 'Syncing delayed' state with an inline retry button.
Can multiple optimistic mutations conflict if triggered in rapid succession?
Yes. Use TanStack Query's mutation keys and queueing, or cancel previous queries inside onMutate to ensure sequential cache application.
How do we persist optimistic mutations across offline browser sessions?
Use TanStack Query's experimental createSyncStoragePersister or Dexie.js (IndexedDB) to write pending mutations to disk until network connectivity resumes.
How do we prevent stale server data from overwriting rapid successive optimistic clicks?
Call queryClient.cancelQueries() immediately inside onMutate to abort any in-flight background query fetches before modifying cache entries.