What useOptimistic Actually Saves You

A checkbox toggle should feel instant. But when that toggle needs to persist to a server, you face a choice: wait for the response and feel sluggish, or update immediately and handle the fallout. The second option — optimistic UI — is better for users, but the manual implementation adds state, flags, and try/catch blocks that pile up fast. For a simple checkbox the difference is small — a few lines. For anything more complex, the gap widens quickly.

👉 Try it in practice: useOptimistic

The manual way: state + pending + rollback

Here's a typical TODO checkbox that optimistically updates the UI before the server responds. No libraries — just React's built-in hooks:

function TodoItem({ todo, onToggle }) {
  const [checked, setChecked] = useState(todo.completed);
  const [pending, setPending] = useState(false);

  async function handleToggle() {
    setChecked((prev) => !prev);
    setPending(true);

    try {
      await onToggle(todo.id, !checked);
    } catch {
      setChecked(checked);
    } finally {
      setPending(false);
    }
  }

  return (
    <label>
      <input
        type="checkbox"
        checked={checked}
        disabled={pending}
        onChange={handleToggle}
      />
      {todo.title}
    </label>
  );
}

26 lines for one checkbox. The try/catch handles a server error, but what if the component unmounts while the request is in flight? What if the parent updates todo.completed from a different source while your toggle is pending — the local checked state and the prop drift apart, and the catch handler restores a stale value. Each edge case adds more state and more branches.

With useOptimistic

Now the same feature with useOptimistic and startTransition:

function TodoItem({ todo, onToggle }) {
  const [optimisticChecked, addOptimistic] = useOptimistic(
    todo.completed,
    (state, next) => next,
  );

  function handleToggle() {
    startTransition(async () => {
      const next = !todo.completed;
      addOptimistic(next);
      await onToggle(todo.id, next);
    });
  }

  return (
    <label>
      <input
        type="checkbox"
        checked={optimisticChecked}
        onChange={handleToggle}
      />
      {todo.title}
    </label>
  );
}

23 lines. Not a dramatic difference in raw line count. The savings aren't in how many lines you type — they're in what you no longer have to think about.

Here's why: startTransition wraps the async work in a React Transition. When the transition ends (on success or error), React re-renders the component. At that point, useOptimistic simply renders whatever todo.completed is. If the parent updated it — success, the checkbox stays checked. If the parent didn't update it — failure, the checkbox goes back to how it was. The rollback isn't "built-in error handling." It's just a consequence of the passthrough prop not changing.

The manual version needs try/catch for a different reason: it has a separate pending flag and a separate checked state. If onToggle throws, both are stuck in the wrong value unless you manually reset them. With useOptimistic, there's nothing to reset — the prop is the only source of truth.

For a checkbox, it's a few lines. For anything more complex — adding to a list, toggling related fields, or managing multiple optimistic values — the manual approach balloons while the useOptimistic version barely grows. That's where the real savings live.

This doesn't mean you can skip error handling entirely. The UI reverts on its own, but you still want to show an error toast, log the failure, or offer a retry — all of which happen outside the optimistic state logic. useOptimistic handles what the checkbox shows; you still handle what the user should know.

Keep complexity at the edge

There's a pattern here that goes beyond this checkbox.

Any time your code has to deal with something external — a server response, a user action, an API call — you have two options. You can let that uncertainty spread through your functions and components, or you can contain it at the boundary where it enters.

The Zod rule validate at system boundaries does exactly this for server-side data. Validate the request body at the endpoint, and every function downstream receives clean, typed data. No more checking "is this field a string?" ten layers deep.

useOptimistic does the same thing for UI state. The user clicks, and instead of spraying pending and error flags across your component, you declare the optimistic change right where the user acted — inside startTransition. The hook keeps the UI in sync with the prop. Everything downstream just renders.

One boundary, one place to think about it, one thing to debug.

👉 Try it in practice: useOptimistic