Skip to content

vishalvoid/skills.vishalvoid / skill/react-optimistic-updates

react-optimistic-updates

Unverified

TanStack Query v5 pattern for instant UI feedback on any CRUD operation without loading spinners. Apply when building lists, edit forms, or dashboards where user actions should feel instantaneous. Commits the optimistic state immediately, rolls back automatically on server error, and revalidates in the background. Works for creates (with temporary IDs), updates, and deletes.

React Optimistic Updates

Technique: Instant-Commit, Background-Sync

Never make users wait for a loading spinner after clicking a button. Commit the change to the UI immediately, let the server catch up in the background, and roll back silently if something goes wrong.

The Problem

Default mutation flow:

User clicks "Delete" → loading spinner → await DELETE /api/items/:id (200-800ms) → UI updates

This is visually dishonest. The user already decided. Make the UI reflect that decision instantly.

The Pattern

Layer 1 — Optimistic onMutate

Before the request fires, snapshot the current cache, apply the change to the cache, and return the snapshot as rollback context.

Layer 2 — Error Rollback

If the mutation fails, onError receives the snapshot and restores it. The user sees the UI revert with no stale state.

Layer 3 — Background Revalidation

onSettled always invalidates the query so the server's true state eventually wins — whether the mutation succeeded or failed.

Implementation

Core mutation hook (delete example)

// hooks/useDeleteItem.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";

interface Item {
  id: string;
  name: string;
  [key: string]: unknown;
}

export function useDeleteItem() {
  const qc = useQueryClient();

  return useMutation({
    mutationFn: (id: string) =>
      fetch(`/api/items/${id}`, { method: "DELETE" }).then((r) => {
        if (!r.ok) throw new Error("Delete failed");
      }),

    onMutate: async (id) => {
      // Cancel in-flight refetches so they don't overwrite our optimistic state
      await qc.cancelQueries({ queryKey: ["items"] });

      // Snapshot current list
      const previous = qc.getQueryData<Item[]>(["items"]);

      // Apply optimistic delete
      qc.setQueryData<Item[]>(["items"], (old = []) =>
        old.filter((item) => item.id !== id)
      );

      return { previous }; // returned as `context` in onError
    },

    onError: (_err, _id, context) => {
      // Restore snapshot on failure
      if (context?.previous) {
        qc.setQueryData(["items"], context.previous);
      }
    },

    onSettled: () => {
      // Always revalidate to ensure server truth
      qc.invalidateQueries({ queryKey: ["items"] });
    },
  });
}

Optimistic create (with temporary ID)

// hooks/useCreateItem.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";

interface CreateItemInput {
  name: string;
  description?: string;
}

interface Item extends CreateItemInput {
  id: string;
  createdAt: string;
}

export function useCreateItem() {
  const qc = useQueryClient();

  return useMutation({
    mutationFn: (input: CreateItemInput) =>
      fetch("/api/items", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(input),
      }).then((r) => r.json() as Promise<Item>),

    onMutate: async (input) => {
      await qc.cancelQueries({ queryKey: ["items"] });
      const previous = qc.getQueryData<Item[]>(["items"]);

      // Insert optimistic item with temp ID
      const optimisticItem: Item = {
        ...input,
        id: `optimistic-${Date.now()}`,
        createdAt: new Date().toISOString(),
      };

      qc.setQueryData<Item[]>(["items"], (old = []) => [
        optimisticItem,
        ...old,
      ]);

      return { previous };
    },

    onError: (_err, _input, context) => {
      if (context?.previous) {
        qc.setQueryData(["items"], context.previous);
      }
    },

    onSettled: () => {
      // Replaces temp ID with real server ID
      qc.invalidateQueries({ queryKey: ["items"] });
    },
  });
}

Optimistic update (edit)

// hooks/useUpdateItem.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";

interface UpdateItemInput {
  id: string;
  name?: string;
  description?: string;
}

export function useUpdateItem() {
  const qc = useQueryClient();

  return useMutation({
    mutationFn: ({ id, ...patch }: UpdateItemInput) =>
      fetch(`/api/items/${id}`, {
        method: "PATCH",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(patch),
      }).then((r) => r.json()),

    onMutate: async ({ id, ...patch }) => {
      await qc.cancelQueries({ queryKey: ["items"] });
      await qc.cancelQueries({ queryKey: ["items", id] });

      const previousList = qc.getQueryData<Item[]>(["items"]);
      const previousItem = qc.getQueryData<Item>(["items", id]);

      // Optimistically update list
      qc.setQueryData<Item[]>(["items"], (old = []) =>
        old.map((item) => (item.id === id ? { ...item, ...patch } : item))
      );

      // Optimistically update detail cache
      qc.setQueryData<Item>(["items", id], (old) =>
        old ? { ...old, ...patch } : old
      );

      return { previousList, previousItem };
    },

    onError: (_err, { id }, context) => {
      if (context?.previousList) {
        qc.setQueryData(["items"], context.previousList);
      }
      if (context?.previousItem) {
        qc.setQueryData(["items", id], context.previousItem);
      }
    },

    onSettled: (_data, _err, { id }) => {
      qc.invalidateQueries({ queryKey: ["items"] });
      qc.invalidateQueries({ queryKey: ["items", id] });
    },
  });
}

Consuming in a component

// components/ItemList.tsx
"use client";

import { useQuery } from "@tanstack/react-query";
import { useDeleteItem } from "@/hooks/useDeleteItem";
import { useCreateItem } from "@/hooks/useCreateItem";

export function ItemList() {
  const { data: items = [] } = useQuery({
    queryKey: ["items"],
    queryFn: () => fetch("/api/items").then((r) => r.json()),
  });

  const deleteItem = useDeleteItem();
  const createItem = useCreateItem();

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>
          {item.id.startsWith("optimistic-") ? (
            <span className="opacity-50">{item.name}</span> // visual hint for pending items
          ) : (
            <span>{item.name}</span>
          )}
          <button
            onClick={() => deleteItem.mutate(item.id)}
            disabled={deleteItem.isPending}
          >
            Delete
          </button>
        </li>
      ))}
      <button
        onClick={() => createItem.mutate({ name: "New Item" })}
        disabled={createItem.isPending}
      >
        Add
      </button>
    </ul>
  );
}

TanStack Query Provider setup

// app/providers.tsx
"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000, // 1 min default
          },
        },
      })
  );

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

Implementation Checklist

  • Cancel in-flight queries with cancelQueries before mutating cache in onMutate
  • Always return snapshot from onMutate as context
  • Use onError to restore snapshot from context
  • Use onSettled (not onSuccess) to invalidate — fires on both success and error
  • Assign temporary IDs prefixed with optimistic- for creates so you can visually dim them
  • Never use setQueriesData + invalidateQueries together on the same key — invalidation triggers a refetch that overwrites your optimistic state before it resolves

staleTime Reference

Data typeRecommended staleTime
User's own CRUD data2–5 minutes
Shared / collaborative30s – 1 minute
Static config / lookups10–30 minutes
Real-time data0–10 seconds

Common Mistakes

  1. invalidateQueries in onSuccess instead of onSettled — if the mutation throws, the cache stays in the optimistic state permanently. Always use onSettled.

  2. Forgetting cancelQueries — an in-flight refetch can arrive after your setQueryData and overwrite the optimistic state with stale server data.

  3. Mutating the snapshot — context.previous is a reference. If you mutate it accidentally, rollback breaks. Always spread: [...old], { ...old }.

  4. Using isPending to disable the whole list — disable only the specific item's button, not the entire UI. Multiple concurrent mutations are fine with optimistic updates.

  5. Not handling the optimistic item visually — temp IDs like optimistic-{timestamp} should be visually dimmed (opacity-50, italic, or a spinner) so users know the item is pending.

When to Apply

  • Delete buttons in lists (most common, highest impact)
  • Toggle states (completed, starred, archived)
  • Inline editing / field updates
  • Drag-and-drop reordering
  • Like / upvote / reaction buttons
  • Multi-step forms where intermediate steps can be cached

When NOT to Apply

  • Payment or booking flows where stale state is dangerous
  • Operations requiring server-generated values displayed immediately (e.g., formatted invoice number)
  • Real-time collaborative editing where conflicts must be resolved server-side
  • Operations on data the user doesn't already have in cache
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexUnverifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall