useOptimistic

1The Problem It Solves

When a user sends a chat message or likes a post, waiting for the server round-trip before showing the change makes the UI feel sluggish — the "correct" data is often extremely predictable, so showing it immediately (and quietly correcting course if the server disagrees) feels far more responsive:

// Without useOptimistic: the new message only appears once the network
// request resolves — a visible delay between clicking "Send" and seeing it
function ChatThread({ messages, sendMessage }: { messages: Message[]; sendMessage: (text: string) => Promise<void> }) {
  const [pending, setPending] = useState(false);

  async function handleSend(text: string) {
    setPending(true);
    await sendMessage(text); // messages only updates after this resolves
    setPending(false);
  }
  // ... the sent message is invisible until the round-trip completes
}

useOptimistic lets the UI display a predicted state immediately, while the real update is still in flight, and automatically reverts to the real data once the actual update lands (or fails).

2The Basic API

import { useOptimistic } from "react";

interface Message {
  id: string;
  text: string;
  sending?: boolean;
}

function ChatThread({ messages, sendMessage }: { messages: Message[]; sendMessage: (text: string) => Promise<void> }) {
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (currentMessages, newText: string) => [
      ...currentMessages,
      { id: `temp-${Date.now()}`, text: newText, sending: true },
    ]
  );

  async function handleSend(formData: FormData) {
    const text = formData.get("text") as string;
    addOptimisticMessage(text); // shows immediately, before the network call
    await sendMessage(text);    // once this resolves, `messages` (the real
                                  // prop) updates and optimisticMessages
                                  // reverts to reflecting it
  }

  return (
    <form action={handleSend}>
      {optimisticMessages.map((m) => (
        <p key={m.id} style={{ opacity: m.sending ? 0.5 : 1 }}>{m.text}</p>
      ))}
      <input name="text" />
    </form>
  );
}

useOptimistic(actualState, updateFn) returns [optimisticState, addOptimistic]:

• actualState — the real, confirmed state (usually a prop derived from server data).
• updateFn(currentState, optimisticValue) => newState — a pure function describing how to merge an optimistic guess into the current (possibly already-optimistic) state.
• optimisticState — what to render; equals actualState when nothing is pending, or the predicted merge while a transition is in flight.
• addOptimistic(value) — call this (inside a transition — typically inside a form action or another transition-wrapped handler) to apply the optimistic update immediately.

3It Automatically Reverts

The optimistic value is never stored as its own independent state that a developer must remember to clear — it's derived fresh every render from actualState and whatever optimistic values are still pending:

// If sendMessage fails, don't manually "undo" the optimistic message —
// simply don't update `messages` with it. Once the pending transition
// settles, useOptimistic re-derives optimisticState from the real
// `messages` prop, and the temporary optimistic entry disappears on its own.
async function handleSend(formData: FormData) {
  const text = formData.get("text") as string;
  addOptimisticMessage(text);
  try {
    await sendMessage(text); // on success, caller re-fetches/updates `messages`
  } catch {
    showErrorToast("Message failed to send"); // no manual optimistic-state cleanup needed
  }
}

This is the core mental model: optimisticState is always a function of actualState plus in-flight guesses, never a separate mutable store — so there's nothing to "roll back" by hand.

4Must Be Called Inside a Transition

addOptimistic(value) only has an effect when called during a transition — inside a useActionState/form action, inside startTransition, or inside another hook that's already part of one. Calling it in a plain event handler outside any transition does nothing useful, because React needs a transition to know it should render the optimistic value first, then keep that render around while the real update resolves:

// CORRECT: inside a form action (which useActionState/form actions
// automatically wrap in a transition)
<form action={async (formData) => {
  addOptimisticMessage(formData.get("text") as string); // works — inside the action
  await sendMessage(formData.get("text") as string);
}}>

// Also correct: explicitly wrapped
function handleClick() {
  startTransition(() => {
    addOptimisticLike();
  });
}

5Composed With useActionState

The two are frequently paired: useActionState manages the actual async submission and its result, while useOptimistic predicts what that result will look like before it arrives:

async function likePostAction(previousState: number, _formData: FormData) {
  await new Promise((r) => setTimeout(r, 800)); // network latency
  return previousState + 1; // the server-confirmed like count
}

function LikeButton({ initialLikes }: { initialLikes: number }) {
  const [likes, formAction] = useActionState(likePostAction, initialLikes);
  const [optimisticLikes, addOptimisticLike] = useOptimistic(likes, (current) => current + 1);

  return (
    <form action={async (formData) => {
      addOptimisticLike(undefined); // instantly shows likes + 1
      await formAction(formData);   // real update lands in `likes` once resolved
    }}>
      <button>{optimisticLikes} likes</button>
    </form>
  );
}

⚠️ Common Pitfalls

1. Calling addOptimistic outside a transition (a plain click handler with no startTransition, no form action) — the optimistic update has no transition to attach to and won't behave as expected.
2. Treating optimisticState as separately mutable state — it's derived from actualState every render; there's no "setOptimisticState" to call directly outside updateFn's merge logic.
3. Forgetting to eventually update actualState — if the real async operation never updates the underlying state/prop, the optimistic value has nothing to revert to or reconcile against once the transition settles, leaving the UI showing a stale prediction indefinitely.
4. Writing an impure or side-effecting updateFn — like a reducer, it should be a pure function from (currentState, optimisticValue) to a new state, called potentially multiple times as renders occur.
5. Using useOptimistic for updates where an incorrect guess would be confusing or costly to show (e.g., a payment total) — it's best suited to low-stakes, highly predictable updates (likes, sent messages, toggles) where a brief incorrect flash is an acceptable trade for responsiveness.

📋 Quick Reference

const [optimisticState, addOptimistic] = useOptimistic(actualState, updateFn)

updateFn: (currentState, optimisticValue) => newState   → pure, like a reducer

addOptimistic(value)  → call INSIDE a transition (form action / startTransition)
optimisticState        → actualState merged with any pending optimistic guess
                          → automatically reverts once actualState updates for real

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: react_useoptimistic_theory.md · generated by tools/build_lessons.py