My Next.js 16 Optimistic UI Looked Perfect. Then Someone Clicked It Five Times Fast

Everything worked. I'd wired up useOptimistic on a task list, the checkbox flipped the instant you clicked it, no spinner, no half-second lag, exactly the feeling I was going for. I demoed it to myself a dozen times and moved on.

Then I did the thing you're supposed to do before you actually ship anything: I clicked it stupidly fast, five times in a row, the way an impatient real user actually would.

The checkbox stayed visually fine. The database did not. Five overlapping requests had gone out, each one flipping the same boolean, landing in whatever order the network felt like that day. Nothing crashed. Nothing logged an error. The UI just quietly stopped matching what actually happened on the server, and I had no way of knowing from looking at the screen.

That's the bug that's easy to miss with optimistic UI specifically, because the whole point of optimistic UI is that it looks right immediately. Looking right and being right are not the same claim.

The fix isn't anything specific to useOptimistic

It's the same rule as disabling a submit button while a form is in flight, just applied per row instead of per form. Track which item has a request pending, and disable it until that request settles.

const [pendingId, setPendingId] = useState<string | null>(null);
function handleToggle(id: string) {
  setPendingId(id);
  startTransition(async () => {
    setOptimisticTask(id);
    try {
      await toggleTask(id);
    } finally {
      setPendingId(null);
    }
  });
}

<input
  type="checkbox"
  checked={task.completed}
  disabled={pendingId === task.id}
  onChange={() => handleToggle(task.id)}
/>

One item at a time, scoped per row, not a global lock on the whole list. The second click on the same checkbox now does nothing instead of firing a second request that races the first one to the database, which also means one fewer redundant write your database has to process for a click that never should have gone out in the first place.

Here's what that actually looks like: five rapid clicks, one request.

The rollback question that sent me down a rabbit hole

While I was in there, I went looking for how to properly roll back an optimistic update on failure, since obviously if the toggle fails, the checkbox needs to snap back to whatever it actually was.

Almost every example I found does this:

try {
  setOptimisticTask(id);
  await toggleTask(id);
} catch {
  setOptimisticTask(id); // flip it back again to "undo"
}

It works. It's also solving a problem that, for a plain toggle like this one, doesn't need solving. useOptimistic doesn't give you a second, independent piece of state you own. It gives you a temporary value layered on top of whatever state you passed in, for exactly as long as the transition is pending. The moment that transition settles, success or failure, React drops the temporary layer and renders from the real state again. If the real state never changed, because the request failed and nothing re-fetched, the checkbox reverts on its own. No second dispatch required.

There's one real exception, and it's worth knowing before you assume the automatic revert always has your back. If the optimistic value is something the server hasn't confirmed yet at all, a new comment you added with a placeholder id before the database assigned a real one, there's no prior version of that item sitting in your base state to fall back to. A failed insert doesn't revert a flag, it has to remove something that only ever existed on the client. That's the one case where you keep your own local record of what you added and clear it yourself in the catch block. A toggle doesn't have that problem, since the value it flips already exists on the server either way.

The cache function question I didn't expect to have opinions about

Once the toggle worked, the next question was how to actually invalidate the cache after it. Next.js 16 gives you three ways to do this, and picking the wrong one either shows the user stale data or forces every page on your site to block on a single write.

revalidatePath invalidates one path. revalidateTag invalidates every cache entry sharing a tag, wherever it's used, with stale-while-revalidate behavior. updateTag, Server Actions only, expires a tag immediately so the page the user is currently on reflects their own write right away.

For a checkbox someone is staring at as they click it, updateTag is the right one. If that same task count also fed a sidebar stat somewhere else on the site, one that nobody's watching in real time, revalidateTag on that same tag lets it catch up a beat later instead of forcing every page on the site to block on one write.

One thing worth knowing if you're on a recent Next.js 16 version: revalidateTag now requires a second argument.

revalidateTag("tasks", "max"); // recommended in Next.js 16+

revalidateTag("tasks") alone is deprecated and will throw a TypeScript error.

The error boundary detail that only matters if your error comes from data fetching

Last piece: what happens when the request just fails outright, not a validation error, an actual dropped connection. Next.js docs are clear that an error thrown inside startTransition still bubbles up to the nearest error.tsx, transition or not.

What I didn't know until I went looking: as of Next.js 16.2, error.tsx ships a second recovery prop, unstable_retry, sitting alongside the older reset. They're not interchangeable. reset wipes the error and lets the same children render again exactly as they were, no new fetch involved, so if the underlying data never loaded in the first place, you're just showing the same broken screen a second time. unstable_retry actually goes back to the server and re-renders the segment fresh, which is the one that fixes anything when the failure came from a fetch.

export default function TaskListError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string };
  unstable_retry: () => void;
}) {
  return (
    <div role="alert">
      <p>Something went wrong loading your tasks.</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  );
}

reset still has a place, specifically when you want to clear an error and re-render without touching the network at all. For a segment whose entire job is showing fetched data, that's rarely the case.

Where the rest of this lives

I wrote the full version of this with the complete before/after code, the decision table for all three revalidation functions, and the Suspense boundary pattern for streaming a mutation's result without blocking the rest of the page, over on my site: "I Added Optimistic Updates to a Next.js 16 App. Here's Every Rollback Bug I Hit." It follows directly from the Server Actions bugs I wrote up in an earlier post, if you want the context on useActionState and why redirect can't sit inside a try/catch.

Has anyone else had an optimistic UI look perfect in every demo and then fall apart the moment a real user clicked faster than you did? I'd genuinely like to know if the rapid-click case is as common as it felt once I actually looked for it.

Note: AI used for image editing.