DEV Community: Shubhra Pokhariya

React 19 useFormStatus Returning False? I Built a SubmitButton That Fixes It

Shubhra Pokhariya — Tue, 29 Sep 2026 08:13:20 +0000

A few weeks back I wrote about the useFormStatus bug that got me the hardest, the one where pending sits at false forever because the hook was called in the wrong component. If you haven't read that one, the short version is this: the hook only reports on a parent form, never one rendered by the same component calling it, and nothing warns you when you get it wrong. No error, no console message, the button just quietly never enters a pending state.

That post explained the bug. This one is about what I actually built once I got tired of re-explaining the same fix to myself on every new project, and about a second version of that exact same silent failure I didn't notice until I'd already shipped the first fix.

One scope note before the code: this fixes the placement mistake. If pending is false because the form submits through a plain onSubmit handler that only calls preventDefault(), or through a URL string action, moving the hook won't change anything, because there is no Action for it to track.

What the first post didn't cover

Moving the hook fixes the placement bug, but I ran into two more problems as soon as I used it in real forms.

The first is disabled={pending} on the button itself. It works, and it's also the wrong choice if you care about keyboard users. A disabled element drops focus the instant it becomes disabled. Someone tabs to your submit button, hits Enter, and focus jumps away mid submission, sometimes landing nowhere useful at all. The fix is aria-disabled instead of disabled, with the click blocked manually so repeat submissions still get ignored.

function SubmitButton({ children, pendingText, intent }) {
  const { pending } = useFormStatus();

  function handleClick(e) {
    if (pending) e.preventDefault();
  }

  return (
    <button
      type="submit"
      name={intent ? "intent" : undefined}
      value={intent}
      aria-disabled={pending || undefined}
      aria-busy={pending || undefined}
      data-pending={pending ? "" : undefined}
      onClick={handleClick}
    >
      {pending ? pendingText : children}
    </button>
  );
}

Focus stays exactly where it was. Style the pending state off aria-disabled or data-pending, not :disabled, since the native attribute is never actually set here.

The second problem shows up once a form has two submit buttons. pending belongs to the whole form, not to whichever button was clicked, so a Save Draft and a Publish button next to each other both light up for one click. The browser already knows which button submitted. Its name and value are in the FormData, so you read them back out and compare.

function useFormStatusForIntent(intent) {
  const status = useFormStatus();
  const submittedIntent = status.data?.get("intent");
  const isThisIntentPending =
    status.pending &&
    (intent === undefined || submittedIntent == null || submittedIntent === intent);
  return { ...status, isThisIntentPending };
}

<form action={savePost}>
  <textarea name="body" />
  <SubmitButton intent="draft" pendingText="Saving draft...">Save Draft</SubmitButton>
  <SubmitButton intent="publish" pendingText="Publishing...">Publish</SubmitButton>
</form>

The button shown earlier is simplified to keep the focus on aria-disabled. In the full file, SubmitButton calls this hook, so only the button someone actually pressed shows pending. One gotcha before you wire this up: pressing Enter in a text field submits through whichever button comes first in the markup. That's the HTML spec's definition of the default button, not something React decides. Put your safest action first.

Locking the rest of the form while it submits

Next you'll probably want the rest of the form locked while the request is in flight, so nobody edits a field mid submit. A native <fieldset> does this in one line instead of one disabled prop per input.

function PendingFieldset({ children, unstyled }) {
  const { pending } = useFormStatus();
  return (
    <fieldset
      disabled={pending}
      style={unstyled ? undefined : { border: 0, margin: 0, padding: 0 }}
    >
      {children}
    </fieldset>
  );
}

The unstyled flag is for CSP. The inline reset removes the fieldset's default border, but a CSP that blocks inline styles ignores it on server-rendered HTML and the border comes back. If that's you, pass unstyled and style it with a class.

One trade-off: a focused input loses focus when the fieldset disables it, the same thing that happens to a disabled button. Use it where blocking edits matters more than keeping focus.

For a screen reader announcement, aria-busy alone isn't read out loud. You need an actual live region for that.

function FormStatusText({ pendingText, idleText = null }) {
  const { pending } = useFormStatus();
  return (
    <span role="status" aria-live="polite" aria-atomic="true">
      {pending ? pendingText : idleText}
    </span>
  );
}

The bug I didn't catch until the second pass

Here's the part that made me go back and touch the file again after I thought it was already done.

SubmitButton had a dev-only check from the start. Render it outside a form and you get a console error in development explaining why it won't work.

PendingFieldset and FormStatusText had the identical requirement, "must be rendered inside the form", written right there in their own comments, but neither one actually had the check. Misplace either one and it fails as silently as the original bug: the fieldset never disables, the status message never appears, and nothing warns you.

It's an easy mistake to make, since these two feel less important than the submit button and tend to get dropped in wherever is convenient.

Both now run the same placement check the button already had, with the same escape hatch for anyone using a portal on purpose:

<PendingFieldset unsafeSkipFormCheck>
  {/* rendered through a portal: outside the form in the DOM, inside it in the React tree */}
</PendingFieldset>

The check has a limit. It only looks at the DOM, but useFormStatus follows the React tree. A component rendered through a portal can track the form correctly and still trigger the warning, because in the DOM it isn't inside the form. That's what unsafeSkipFormCheck is for.

Where this landed

The full file has the button, the fieldset, the live region, the intent hook, and the placement check on all three components. One file, no dependencies beyond react and react-dom.

Known limits: intent doesn't work with a per-button formAction, form.requestSubmit() skips the click guard, and two synchronous clicks in the same task both get through before React re-renders. I've only tested in Chromium and Firefox so far. Safari and screen readers are still untested.

If you want the whole thing: useFormStatus SubmitButton. Free, single file.

If you're catching this one first and want the full explanation of why the original bug happens, that's the earlier post.

React 19's useTransition Looked Simple. Then I Found a Second Bug Hiding Inside the First One

Shubhra Pokhariya — Mon, 21 Sep 2026 15:32:13 +0000

Every hook in this series so far has been a passenger. useActionState rides inside a Transition and reports back the result. useOptimistic rides inside one and shows you a preview before the real answer lands. useFormStatus doesn't even ride, it just reads a status from whoever else is driving. useTransition is the only one of the four that sits in the driver's seat by itself, no form required, no other hook required.

That's also why it's the easiest one to get partially right. You wrap a click handler in startTransition, you get an isPending flag, everything looks fine in your browser tab, and you ship it. Then someone double-clicks fast, or your function throws, or you try to hook it up to a text input, and the parts nobody mentioned start showing up.

This is a standalone guide. If you're new to this series, everything below works on its own. If you've read Part 4, you already saw useTransition make a brief appearance there through a wishlist button.

I tested every example below against React 19.2.8. I also re-ran the race condition, error boundary, and overlapping Transition checks on React 19.3.0, which shipped on September 9.

What useTransition Actually Gives You

Call it at the top of a component and you get back exactly two things, always in this order.

import { useTransition } from "react";

function ProductFilters() {
  const [isPending, startTransition] = useTransition();
  // ...
}

isPending is a boolean. It becomes true at the first call to startTransition, and stays true until every Action in that Transition, including anything you awaited, has completed and the resulting state is shown. startTransition is a function that takes one argument, a function of your own, and runs it right away. Nothing about startTransition is delayed or scheduled for later. What changes is how React treats any set call that happens while your function is running, those updates get marked as low priority and interruptible instead of urgent.

That's the entire contract. No result value, no built-in error state, no queue. Compare that to useActionState from Part 1, which hands you back whatever your function returns as state. useTransition doesn't do that. If your function returns something, that return value is simply gone unless you store it yourself. This is the tradeoff for using useTransition directly: less structure, but nothing standing between you and the raw mechanism.

A Search Filter That Doesn't Freeze the List

Forms and buttons aren't the only place a Transition earns its keep. Filtering a long list as someone types is a case useActionState was never built for, there's no side effect to run, no single result to track, just a rendered list that needs to stay responsive while it re-renders on every keystroke.

One precision point before the code: startTransition does not make a computation run in the background. The function you pass to it runs immediately and synchronously, right when you call it. What gets marked as low priority and interruptible is the state update, and the render that follows from it, not whatever JavaScript happens to run inside the callback before that update fires. That distinction is the whole point of this example, so the two state variables below are split around it deliberately.

import { useState, useTransition } from "react";

function ProductSearch({ products }) {
  const [query, setQuery] = useState("");
  const [filterQuery, setFilterQuery] = useState("");
  const [isPending, startTransition] = useTransition();

  function handleChange(e) {
    const value = e.target.value;
    setQuery(value);

    startTransition(() => {
      setFilterQuery(value);
    });
  }

  const filtered = products.filter((p) =>
    p.name.toLowerCase().includes(filterQuery.toLowerCase()),
  );

  return (
    <div>
      <input
        value={query}
        onChange={handleChange}
        placeholder="Search products"
      />
      <ul style={{ opacity: isPending ? 0.6 : 1 }}>
        {filtered.map((p) => (
          <li key={p.id}>{p.name}</li>
        ))}
      </ul>
    </div>
  );
}

query drives the input and updates synchronously, so typing never lags. filterQuery is the one wrapped in startTransition, it "lags behind" query on purpose. filtered isn't stored in state at all, it's a plain expression computed fresh on every render from filterQuery. The key point: the products.filter() call itself still runs as an ordinary, uninterrupted piece of JavaScript, exactly like it would outside a Transition. What changed is when that render happens and whether a more urgent update, another keystroke, is allowed to cut in front of it. React isn't chunking your array iteration, it's deciding whether the render containing that iteration gets to proceed right now or gets pushed behind something more urgent.

This is also where the input-in-a-Transition limitation becomes concrete instead of abstract. You cannot wrap query itself in startTransition, only filterQuery can go there. A controlled input's value has to update synchronously with every keystroke to feel correct, and React's own troubleshooting docs name this exact two-state split as one of two fixes, the other being useDeferredValue on a single state variable.

When to reach for useDeferredValue instead. The rule of thumb is about who owns the set function. Here, the component owns setFilterQuery directly, so useTransition is the right tool. If ProductSearch instead received its query as a prop from a parent, or read it from some other hook you don't control the setter for, there'd be no set call of your own to wrap in startTransition. That's exactly the case useDeferredValue exists for, you hand it the value, const deferredQuery = useDeferredValue(query), and it produces its own lagging copy without needing access to whoever's setting the original. Same lagging behavior, different entry point depending on whether you're driving the update or just receiving the value.

The await Rule, and Why It Actually Happens

Part 4 showed the pattern for handling state updates after an await inside a Transition, wrap them in a second startTransition call. What it didn't get into is why React needs that second call at all, and that's worth understanding once instead of memorizing as a rule.

function handleSave() {
  startTransition(async () => {
    const saved = await saveDraft(draft);
    // this update is NOT part of the Transition
    setStatus("saved");
  });
}

React marks a set call as part of a Transition by checking a flag while your function is running synchronously. The moment your function hits await, execution yields back to the JavaScript engine, and that flag is gone by the time the code after await resumes. React has no way to know that resumed code is a continuation of the same Transition rather than something unrelated. This is a JavaScript limitation, not a bug React chose not to fix, the language doesn't yet give React a way to track "this async continuation belongs to that earlier synchronous scope." A TC39 proposal called AsyncContext would close this gap, but it isn't part of the language yet.

The fix is the same nested call every time.

function handleSave() {
  startTransition(async () => {
    const saved = await saveDraft(draft);
    // ✅ back inside a synchronous startTransition scope
    startTransition(() => {
      setStatus("saved");
    });
  });
}

After every await, state updates that need to remain part of the Transition must be wrapped in another startTransition, as the useTransition docs describe. Two sequential awaits in one Action means two separate re-entries into startTransition for the updates that follow each one.

Pending UI With No Form in Sight

Every pending indicator earlier in this series read isPending from useActionState or pending from useFormStatus. useFormStatus reads from a parent form, and useActionState is built around the Actions you dispatch through it. useTransition's isPending is the one you get when you start the Action yourself, with no form involved. It's just a boolean tied to whatever you wrapped, which means it works for things that were never going to be a form to begin with: a favorite toggle, a sort order change, a modal that loads data before it opens.

function SortButton({ label, sortKey, onSort }) {
  const [isPending, startTransition] = useTransition();

  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => onSort(sortKey))}
    >
      {label}
      {isPending && <span className="spinner" aria-hidden="true" />}
    </button>
  );
}

The button that triggered the change is the one that shows its own pending state, without a global loading flag and without prop drilling a status down from somewhere else. That's the same locality useFormStatus gave you in Part 3, just reached through a different door, one that doesn't require a <form> to walk through.

Errors in a Bare Transition

This is the gap Part 4 didn't touch, and it's a real one. useActionState gives you a place to catch expected errors as returned state. A bare useTransition call gives you nothing like that. If the function you pass to startTransition throws, there's no result state to inspect, the throw propagates up to the nearest error boundary instead.

import { useTransition } from "react";
import { ErrorBoundary } from "react-error-boundary";

function AddToCartButton({ productId }) {
  const [isPending, startTransition] = useTransition();

  function handleClick() {
    startTransition(async () => {
      const result = await addToCart(productId);
      if (!result.ok) {
        throw new Error("Could not add item to cart");
      }
    });
  }

  return (
    <button disabled={isPending} onClick={handleClick}>
      Add to Cart
    </button>
  );
}

export function CartButtonWithBoundary(props) {
  return (
    <ErrorBoundary fallback={<p>Something went wrong adding this item.</p>}>
      <AddToCartButton {...props} />
    </ErrorBoundary>
  );
}

Worth being clear about what's actually happening here: useTransition doesn't give you a custom error state or a new API surface for errors, that part is true. But it's not accurate to call this identical to any ordinary render-time error either. React specifically added Error Boundary support for Actions, so a throw inside startTransition gets caught the way a throw in a plain event handler normally wouldn't, event handler errors have never been something a boundary catches on their own.

Two things trip people up here. First, the error boundary has to wrap the component calling useTransition, not just the button markup, an error boundary placed below the hook call won't catch anything. Second, this is an all-or-nothing tool: a thrown error takes down whatever the boundary wraps until the user or your code resets it. If you want a recoverable, inline error message instead of the whole section replaced by a fallback, don't throw, return an error value from the function and store it in state yourself. useActionState gives you that pattern for free, since its return value becomes state automatically. Plain useTransition doesn't, you'd be rebuilding a small piece of what useActionState already does.

The Race Condition Nobody's First Draft Handles

Here's the scenario Part 4 flagged and left open. A user clicks something that triggers an async Transition, changes their mind, and clicks again before the first request resolves. Both requests are now in flight. The response that arrives last is the one the component keeps, even if it belongs to the earlier click.

import { useState, useTransition } from "react";

function QuantityStepper({ itemId, initialQty }) {
  const [qty, setQty] = useState(initialQty);
  const [isPending, startTransition] = useTransition();

  function updateQty(next) {
    startTransition(async () => {
      const saved = await updateCartQuantity(itemId, next);
      startTransition(() => {
        setQty(saved);
        // if a slower, earlier request resolves after this one,
        // its setQty runs last and the stale value wins
      });
    });
  }

  return (
    <div>
      <button onClick={() => updateQty(qty - 1)}>-</button>
      <span>{qty}</span>
      <button onClick={() => updateQty(qty + 1)}>+</button>
    </div>
  );
}

React's own reference material for this exact scenario says it plainly: Actions inside a Transition don't guarantee execution order once you await something, because the async boundary loses that ordering context the same way it loses the Transition flag. useActionState sidesteps this for its own dispatcher by queuing calls and running them one at a time, but a raw useTransition call gets no such protection.

There's actually a second problem hiding in this code, and it's easy to miss because it looks like the same bug. updateQty(qty - 1) reads qty from the render that produced this particular click handler, and setQty only fires once the network request resolves. Click + twice within that window, before the first request's response has actually come back and updated qty, and both clicks compute their next value from the same starting number, sending the same result twice instead of incrementing twice. This isn't a same-tick React batching quirk, clicks are handled as separate events and React doesn't merge them. It's simpler and more common than that: the state genuinely hasn't changed yet, because the only thing that changes it is still sitting on the wire. Fixing the request race doesn't fix this one, they need separate solutions.

import { useState, useTransition, useRef } from "react";

function QuantityStepper({ itemId, initialQty }) {
  const [qty, setQty] = useState(initialQty);
  const [isPending, startTransition] = useTransition();
  const requestedQty = useRef(initialQty);
  const latestRequestId = useRef(0);

  function updateQty(delta) {
    // authoritative next value, independent of what's currently rendered
    requestedQty.current += delta;
    const next = requestedQty.current;
    const requestId = ++latestRequestId.current;

    startTransition(async () => {
      const saved = await updateCartQuantity(itemId, next);

      startTransition(() => {
        // only apply this result if nothing newer has been fired since
        if (requestId === latestRequestId.current) {
          setQty(saved);
        }
      });
    });
  }

  return (
    <div>
      <button onClick={() => updateQty(-1)}>-</button>
      <span>{qty}</span>
      <button onClick={() => updateQty(1)}>+</button>
    </div>
  );
}

Two separate fixes doing two separate jobs. requestedQty is a ref that tracks the next value to send independently of the rendered qty, so it keeps accumulating correctly across rapid clicks no matter how far behind the actual render is. latestRequestId is the token that solves the original problem, a stale response checks whether it's still the most recent request before it's allowed to apply. A ref is the right tool for both because neither one needs to trigger a render on its own, they just need to survive across renders and stay current. This isn't the only way to solve the ordering half, an AbortController tied to each request works too if your fetch layer supports cancellation, though aborting only stops the client from waiting, and the server may already be processing that mutation. The token check needs nothing from your API beyond what you probably already have.

Two limits worth knowing. requestedQty advances at click time, so it assumes the server accepts the requested value as sent. If the server clamps or normalizes that value, the ref and qty can drift apart. The request token only decides which response can update the UI. It doesn't cancel the earlier request or guarantee that the server applies the updates in the order they were sent.

When to Reach for useTransition and When Not To

Reach for it when you need pending tracking for something that isn't a form submission and doesn't need a tracked result value: filtering, sorting, tab switches, toggles, navigation.

Don't reach for it for a controlled input's own value, that has to stay synchronous or typing will visibly lag. Don't reach for it when you need the function's return value as state, that's what useActionState captures automatically and useTransition doesn't. Don't reach for it assuming request ordering is handled, it isn't, not without the token pattern above or an equivalent.

Keep in mind that the useTransition reference still lists a limitation: if multiple Transitions are ongoing, React currently batches them together. React 19.3 changed something nearby. According to the React 19.3 release post, a Transition with a slow render no longer holds up unrelated ones. So don't assume several pending indicators settle independently.

Where This Leaves the Series

You need to...	Reach for
Own a form's result and pending state in one place	`useActionState`
Show finished UI before a server response confirms it	`useOptimistic`
Read a form's pending state from a component that isn't managing it	`useFormStatus`
Run pending-tracked work outside a form, with full control yourself	`useTransition`

Part 4 called these four answers to four different questions sharing one mechanism. Having now used the fourth one without any of the other three in the room, that framing holds up. useTransition isn't the beginner-friendly entry point of the group, it's the one with the fewest guardrails, which is exactly why it's also the one that can do things the form-shaped hooks were never built for.

I went through the out-of-order version of this bug in a plain search box in I Throttled My App to Slow 3G. Here's What My Tests Never Caught.

So which one have you already shipped without knowing it, a response landing out of order or two fast clicks reading the same stale value? Drop it below.

The Code I Couldn't Leave Alone

Shubhra Pokhariya — Thu, 17 Sep 2026 12:20:21 +0000

The bug report was simple enough. On the reports dashboard, if you changed the date range while a filter was already active, the page number didn't reset. So a user could end up on page 4 of a report that now only had one page of results, staring at an empty table with no idea why.

I found it fast. The pagination state and the filter state were living in two different places, useState in the table component and useSearchParams for the filters, and nothing was watching one to reset the other. I added a useEffect that reset the page to 1 whenever the search params changed. It was the smallest change that unbroke the dashboard, and I wasn't about to restructure the component tree for a twenty minute fix. Tested it locally, clicked through a few filter combinations, watched the empty table problem disappear. Twenty minutes, maybe less.

I didn't open the pull request yet. I told myself I wanted to read through the diff once more before pushing.

That's when I actually looked at ReportFilters.tsx for the first time in a while, and I didn't love what I saw. The filter state existed in two places at once. Some of it lived in the URL through useSearchParams, which is what actually drove the API call, and some of it lived in local component state that only existed to control what the dropdowns displayed. Most of the time they matched. Occasionally, if you clicked fast enough, they didn't, and you'd see a dropdown showing one filter while the table quietly fetched with another. Nobody had filed a bug for that. I don't think anyone had ever managed to click fast enough to notice.

But I'd noticed it now, and once you've seen a bug like that, it's hard to unsee it. It reminded me of a race condition I once tracked down in a checkbox that looked right on screen while the requests behind it quietly disagreed, the same kind of mismatch between what the UI shows and what actually happened. Different bug, same shape.

So I pulled the local state out entirely and made the URL params the single source of truth, reading everything through useSearchParams and writing through router.replace. That's a real fix. Two sources of truth for the same data is exactly the kind of thing that eventually causes a much worse bug than the one I'd started with. I felt good about that change, and I still do.

While I was in there, I noticed the filter logic itself, the actual function that turned the search params into a query object, was duplicated. It existed once in the component to build the fetch request, and again inside app/api/reports/route.ts to validate incoming params on the server. Same logic, written twice, slightly out of sync, because someone had updated one copy when a new filter type was added and forgotten the other. I pulled it into a shared lib/filters.ts and imported it in both places. That's not a nice to have. That's the kind of drift that can quietly turn into a production bug.

At this point I'd fixed the original bug, removed a genuine duplicate source of truth, and closed a real gap between client and server validation. If I'd stopped there, this would just be a normal Tuesday. I didn't stop there.

Once the filter logic was centralized, I looked at the route handler again and thought, well, since I'm already reading through this, the report data itself doesn't actually need to be client fetched at all. It's not interactive in any way that requires it. It could be a server component, fetched directly with the filters coming from searchParams in the page props, no client-side fetch, no loading spinner, no waterfall. In my head it looked roughly like this.

export default async function ReportsPage({
  searchParams,
}: {
  searchParams: Promise<{ range?: string; status?: string }>;
}) {
  const { range, status } = await searchParams;
  const reports = await getReports({ range, status });
  return <ReportsTable data={reports} />;
}

That's a bigger change than a bug fix. It touches the page structure, it means rethinking how the table gets its data, it means the loading state disappears entirely because the server just renders with the data already there.

I started doing it anyway.

I got about halfway through converting the table to a server component before I stopped, not because it was going badly, but because I glanced at the git diff panel in my editor and the file count had gone from one changed file to seven. Seven files, for a bug that was, structurally, a missing line inside a useEffect.

I sat there for a second looking at that number, and the question that actually stopped me wasn't "is this too much work." It was smaller and quieter than that. I asked myself whether the server component conversion was something the product needed right now, or whether it was something I wanted to do because I could see exactly how to do it and it bothered me to leave it undone once I'd seen it.

I didn't have a clean answer immediately, which is honestly what made me pay attention. The filter state fix and the duplicated logic fix, I could justify those in one sentence each, to myself or to a reviewer. The server component rewrite took a full paragraph to justify, and most of that paragraph was about how satisfying the final version would be, not about what was currently broken for anyone using the dashboard.

That's usually the tell, I think. Not the size of the change. Plenty of small changes are indulgent and plenty of large ones are necessary. It's how long the justification takes, and who the justification is actually for.

So I split it. I finished the bug fix and the shared filter logic, wrote a focused pull request that a reviewer could read in five minutes and understand completely, merged it the same day. The server component rewrite went into its own branch with its own description, explaining what it would remove, what it would simplify, and why it was worth doing on its own terms instead of riding in quietly behind a one-line bug fix. It's a good change. I still believe that. It just needed to stand on its own, reviewed and evaluated as what it actually was, instead of hiding inside something smaller.

What stays with me isn't that I almost shipped too much. It's how reasonable every single step felt while I was inside it. Nobody would have blinked at any individual commit. The dropdown desync fix, obviously worth doing. The shared filter util, obviously worth doing. Even the server component conversion, on its own merits, was obviously worth doing. Stacked together in one sitting, driven by one bug report, they stopped being a response to a problem and became a response to my own discomfort with leaving the file the way I found it.

I don't think that discomfort is something to train out of myself. It's most of why I'm good at this. Being able to see the second problem while you're fixing the first one is a real skill, and I'd rather have it than not. But seeing a change and shipping a change used to be the same motion for me, and somewhere in that two hour stretch I finally felt the gap between them instead of just hearing about it in theory.

I closed the laptop that evening having shipped exactly one thing, a twenty minute bug fix with a real structural improvement folded honestly into it. The bigger rewrite is sitting in review on its own branch, where it belongs, where someone can actually look at it and ask whether it's worth the seven files, instead of me deciding that alone at ten at night because I couldn't stand leaving a route handler half server, half client, one more day.

I Throttled My App to Slow 3G. Here's What My Tests Never Caught

Shubhra Pokhariya — Tue, 15 Sep 2026 05:41:21 +0000

I wasn't looking for a performance problem. I wanted to see what happened when the network got slow enough that assumptions I normally never notice had time to surface. So I opened DevTools, set the throttle to 3G (Chrome's network throttling reference dropped the separate "Slow 3G" preset a while back and just calls it "3G" now, sitting between Slow 4G and Offline), and started clicking around an app that had never once misbehaved on my normal wifi.

Two things broke. Both were correctness bugs, not "feels slow" complaints, and both were sitting in code that had passed every test I'd written for it.

Bug one: a race condition, search results arriving in the wrong order

The app has a search box. Type a query, it fetches results, it shows them. Nothing fancy:

async function search(query) {
  const res = await fetch(`/api/search?q=${query}`);
  const data = await res.json();
  setResults(data.results);
}

This is a race condition, and on fast wifi you'll rarely notice it, because request and response times are close enough together that ordering rarely flips. That's not a guarantee, it's just what low, consistent latency looks like most of the time. Slow the connection down and that stops holding. If you type "apple", pause, then quickly change it to "banana", the "apple" request and the "banana" request are both in flight at once. Whichever one happens to take longer, maybe it hit a slower part of the network, maybe the server did more work for it, can land after the other one. When it does, its response overwrites the screen with results for a query you're not even looking at anymore.

If this sounds familiar, I went through a close cousin of this bug in The Optimistic UI Race Condition That Only Showed Up on the Fifth Click, stale results from out-of-order requests aren't unique to search boxes, they show up anywhere a component fires more than one async request over its lifetime.

The 3G throttle on its own makes this easier to hit, since it throttles every request in the session regardless of which path it takes. But it doesn't guarantee a flip on any given run, so to make it reproducible for this post I forced it deterministically: I gave the two queries different artificial delays on the server, apple takes 3 seconds, banana takes 200 milliseconds. That's a server-side delay, not the network throttle. For the logs and timings below, I ran the test with throttling off so the numbers are clean and come from the server delay alone. With throttling on, the same race still happens, but the network adds less predictable latency on top, which makes the timing harder to read in a screenshot.

Click apple, then banana right after.

sent request for "apple"
sent request for "banana"
got response for "banana" after 210ms
got response for "apple" after 3001ms

The screen ends up showing apple's results, because that's whichever response arrived last, not whichever request the user cared about last.

The fix is to stop trusting arrival order and start tracking which request is actually the latest one:

let latestQueryId = 0;

async function search(query) {
  const thisId = ++latestQueryId;
  const res = await fetch(`/api/search?q=${query}`);
  const data = await res.json();
  if (thisId !== latestQueryId) return; // a newer request has already been sent
  setResults(data.results);
}

Same two requests, same order of arrival, one result on screen:

sent request for "apple" (id 1)
sent request for "banana" (id 2)
got response for "banana" (id 2) after 210ms
got response for "apple" (id 1) after 3001ms
   IGNORED: a newer request has been sent since this one fired

Another option is AbortController, which can abort the previous fetch when a new query starts. That's a different tradeoff from request IDs, not the same mechanism wearing a different name. Aborting stops the client-side fetch from continuing to wait on that response. It doesn't necessarily stop the server from finishing the work it already started. Tracking request IDs instead lets the old request finish, then explicitly ignores its response if it's gone stale. I went with request IDs here because the search endpoint is cheap and I didn't need to cancel anything server-side, just make sure a late response can't win.

Bug two: the autosave that saves twice, or drops your last edit

This one comes from a client-side timeout that assumed a round trip would always be fast.

The autosave gave up and retried if it hadn't heard back within 1.2 seconds, a reasonable number if saves normally take a few hundred milliseconds. On a throttled connection a save can genuinely take two or three seconds without anything actually being wrong. The client can't tell "slow" apart from "failed." It just knows the timer ran out, assumes the worst, and fires a second save while the first one is still in flight and about to succeed on its own.

save #1 sent
save #1 client-side timeout, treating as failed and retrying
save #2 sent
save #1 confirmed (arrived after the retry already fired)
save #2 confirmed

Two saves for one edit. If the save endpoint isn't strictly idempotent, that's two writes that can produce different results depending on what changed in between, not just a harmless duplicate.

My first fix was a simple in-flight guard: skip firing a new save while one is already out. That stops the duplicate, but it introduces a different bug. If you edit again while a save is in flight, that edit gets silently dropped instead of ever being sent:

user types "hello", save #1 starts
user types "hello world" while save #1 is still in flight
   skipped (save in flight), edit "hello world" is dropped
save #1 confirmed: "hello"

For this autosave behavior, the version you want doesn't skip the newer edit, it queues it and sends it right after the current save finishes:

let saveInFlight = false;
let pendingContent = null;

async function save(content) {
  if (saveInFlight) {
    pendingContent = content;
    return;
  }
  saveInFlight = true;
  try {
    await postSave(content);
  } finally {
    saveInFlight = false;
  }
  if (pendingContent !== null) {
    const next = pendingContent;
    pendingContent = null;
    await save(next);
  }
}

The try/finally matters here, not just style. Without it, if postSave ever rejects, saveInFlight stays true forever and every future edit gets silently queued and never sent. That's a worse bug than the one you started with, because it fails quietly.

save #1 sent: "hello"
skipped (save in flight), queued latest: "hello world"
save #1 confirmed: "hello"
save #2 sent: "hello world"
save #2 confirmed: "hello world"

No duplicate requests, and the latest edit still gets saved. (If you edit again while that queued save is itself in flight, it just replaces pendingContent again, that's the coalescing working as intended, only ever the most recent edit waits in line.) This is the simple version of the queueing strategy, worth saying plainly: a production autosave also needs an explicit policy for what happens when a save actually fails, not just when it's slow. This code handles slow, not failed.

The actual lesson here isn't "guard against duplicate saves", it's that a client-side timeout only tells you a response hasn't arrived yet. It doesn't tell you what happened on the server, and if the operation has side effects, retrying it needs an explicit strategy for what happens to work that's already in flight.

What both actually have in common

I didn't go looking for two bugs about ordering and timing specifically. I went looking for whatever would show up if I stopped assuming my network was representative of anyone else's. Both of these surfaced because each one was built around an assumption that happened to hold on my machine and broke somewhere else. Responses usually arrive in the order you send them, until they don't. A couple seconds is usually enough time for a save to complete, until it isn't.

Neither of my test suites caught either of these, because neither ran on a slow connection. They ran on the same fast, forgiving network I was developing on, which is exactly the network that hides both of these bugs. Same pattern I ran into with a completely different upgrade in Next.js 16 Broke My App in 4 Places and None of Them Threw an Error, none of these bugs throw, none of them fail loud, they just quietly do the wrong thing until you go looking under the exact condition that triggers them.

If your code assumes responses arrive in request order, or treats a client timeout as proof of failure, you likely have a version of one of these sitting in code you already trust, whether or not you've seen it misbehave yet.

I Tested generateStaticParams in Next.js Cache Components. My Layout Broke Twice

Shubhra Pokhariya — Wed, 09 Sep 2026 12:22:33 +0000

The last post here got picked apart in the comments in the best possible way. @nazar-boyko asked the sharpest version of the question I'd skipped entirely: if the ids are known at build time, does the page go fully static, or does Cache Components still want a stream, cache, or block answer regardless. @mudassirworks flagged the nested-component wrinkle, two server components independently awaiting params, and where the Suspense boundary actually has to sit. @suraj09, @glenallen, and @merbayerp circled the same architecture question from different angles, what happens once a layout and the page underneath it both depend on the same runtime data. @alexshev pushed on something none of us had done, turning a one-off fix into something that survives after the post is forgotten. None of it had a real answer from me at the time, so I built a fresh project and went and got one.

So I built a fresh test project, four routes this time instead of one, and ran every one of these to an actual answer.

Does generateStaticParams make a route static?

Short version: no. I gave a route three known ids up front and left the data access unguarded, same as the original test.

export async function generateStaticParams() {
  return [{ id: "1" }, { id: "2" }, { id: "3" }];
}

export default async function ProductStaticPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);
  // ...
}

Build fails, and it names id 1 specifically, one of the exact three I told it about ahead of time. Knowing the id at build time and being allowed to skip the stream, cache, or block decision are two different things.

That part's a clean answer, but not the interesting one. The interesting part is what happens once you actually pick a fix, because the two fixes I tried don't produce the same result.

Wrap the data access in Suspense, and the build passes, but all three known ids come out marked as Partial Prerender. The data stays deferred behind the static shell, the same as it does for an id the route has never seen. Swap that for caching the data function instead, one word changed, "use cache" instead of a Suspense wrapper, and those same three ids flip to fully static, baked into the build output.

That's the real answer to Nazar's question. generateStaticParams decides which paths get attempted. Whether they end up static depends on the work the route performs for those params and how that work gets handled, not on the ids being known ahead of time by itself.

One more dead end worth flagging before you go looking for it yourself: I tried pairing generateStaticParams with the old dynamicParams = false option, expecting a 404 for anything outside the known set. dynamicParams still exists as a route segment config in Next.js generally, but it's disabled specifically once cacheComponents is on, so the build rejects it instead of applying it. In this Cache Components setup, unlisted ids are handled at request time instead.

The bug that took three attempts

This is the one I'd read even if you skip everything else, because it's the part that answers Suraj, Glen, and Mustafa's question, and it's the part that actually surprised me.

Setup: a layout and a page sharing a route segment, both reading the same id, both calling the same two data functions. Both unguarded. Build fails, expected.

My first move was the obvious one: fix the page, leave the layout alone, since I'd already handled the page's own component.

Still failed. Fixing the page did nothing for an unguarded params access in the layout above it. A Suspense boundary in the page can't reach back and cover work that already happened in the parent before the page even rendered.

So I fixed the layout too, wrapped the component reading the data in its own Suspense, the same move that had worked everywhere else so far.

Still failed. Same error. This is where I stopped guessing and ran next build --debug-prerender to get an actual trace instead of a route name.

It pointed at const { id } = await params;, sitting in the layout, above the Suspense boundary I'd just added. Not the data fetch inside the wrapped component. The line that produced the id in the first place.

I'd wrapped the component that used the id. I hadn't wrapped the line that produced it.

The real fix passes the whole params promise down and resolves it inside the wrapped child, instead of resolving it in the parent and handing over a plain value:

async function WorkspaceHeader({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const workspace = await getWorkspace(id);
  return <header>{workspace.name}</header>;
}

export default function WorkspaceLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ id: string }>;
}) {
  return (
    <div>
      <Suspense fallback={<header>Loading...</header>}>
        <WorkspaceHeader params={params} />
      </Suspense>
      <div className="p-8">{children}</div>
    </div>
  );
}

That builds clean. Same principle applied to the page underneath it.

One negative result worth keeping, since it's the mistake I'd expect someone to reach for first on a real app: I also tried leaving both layers completely unguarded and just caching the two shared data functions instead, assuming that would cover both callers at once. It didn't touch the failure at all. The unguarded operation was never the data fetch, it was await params itself, sitting outside any boundary in both places. Caching a function a broken access calls doesn't fix the access that calls it.

Mudassir's nested-sibling case turned out to follow the same underlying rule, just one layer shallower: two independent components both reading params, and wrapping only one of them left the other exposed. The fix isn't a specific boundary shape, it's making sure nothing reading runtime data sits outside every boundary, whether that's one shared wrapper or several separate ones.

What I'd actually check on a real app

Audit layouts before pages. A layout's unguarded access fails on its own terms, independent of anything you've already fixed below it, and it's the thing most likely to get missed because layouts don't feel like "the route" the way a page does.

When a fix doesn't work and the error still points at something you've technically wrapped, check where the await itself happens, not just where the result gets used. Resolving a promise above a boundary and passing the plain value into a wrapped child still counts as an unguarded access.

Alex, on the regression test question, here's what I landed on: a small script that rebuilds, then hits each fixed route including the unlisted-id case, since a plain build won't catch that on its own. Worth being honest that an HTTP check only proves the route responds, not which rendering mode it's using. That classification only ever comes from the build output itself.

I put the full four-route walkthrough, all the build screenshots, the exact debug trace, and the regression script in the full Next.js generateStaticParams and nested-layout walkthrough if you want the whole thing end to end rather than the condensed version here.

Has anyone hit this layout-versus-page split in a real production route tree yet? I'm curious whether the same params boundary issue shows up once several layouts start sharing data.

React 19 Actions: I Explained 3 Hooks Without Ever Explaining What an Action Is

Shubhra Pokhariya — Tue, 01 Sep 2026 07:30:35 +0000

Three parts into this series, and if you'd asked me to define the word sitting underneath every single hook I'd taught you, I'm not sure I could have done it cleanly. That's not false modesty. Go back and read Parts 1 through 3. I used the word "Action" constantly. I never once stopped to say what one actually is.

Part 1 opened with three state variables I'd hand-rolled for years, a result, a pending flag, an error, and showed how useActionState collapses all three into one call. Part 2 took a comment box and made it feel instant before the server had even replied. Part 3 let a submit button three components away read a form's pending state with zero props passed down. Three different problems, three different hooks, and every single one of them was quietly leaning on the same mechanism without me ever naming it out loud.

That's the gap this post closes. Not a new bug this time. The concept the last three bugs were all symptoms of.

The word I kept using and never defined

Here's the actual definition, straight from React's own docs, not a paraphrase I'm softening for effect. A function called inside startTransition is an Action. That's it. That's the whole qualifying test.

async function submitFeedback(previousState, formData) {
  const message = formData.get("message");
  await saveFeedback(message);
  return { sent: true };
}

That function above could sit in your codebase forever and never once behave like an Action. What flips the switch has nothing to do with anything written inside it. It's entirely about the doorway it walks through. Four doorways do this: a direct startTransition call, useTransition's version of the same call, a form's action prop taking a function instead of a string, or useActionState. Walk a function through any of them and it stops being a plain async function you're tracking by hand. What React takes over automatically is the Transition itself, the pending tracking underneath it. What it does not universally hand you is the function's return value. useTransition gives you isPending and nothing else, a raw startTransition call doesn't return anything at all. useActionState is the one doorway built specifically to catch that return value and hold onto it as state, which is exactly why isPending and a real result showed up together back in Part 1 and nowhere else in this series. More on the ordering side of this once useTransition shows up properly below.

Once that clicked for me, Parts 1 through 3 stopped looking like three separate hooks and started looking like three different windows onto the same room. useFormStatus reads the pending status of the nearest parent form, and now you know why, that pending status only exists in the first place because something wrapped the submission in a Transition. useOptimistic is the odd one out. It isn't a door into becoming an Action at all. It's a setter you call from inside one that's already running. Call it outside a Transition and it just won't behave the way Part 2 showed you.

Why any of this needed inventing

Part 1's opening line still holds up: every form needed the same three pieces of state, wired by hand, every time. That pattern wasn't unique to forms either. A delete button, a follow toggle, a checkout step, all needed the identical scaffolding rebuilt from scratch. React 19 added the ability to use async functions inside transitions in the first place, which is the foundation everything else in this series stands on. What you build on that foundation, whether you get a tracked result back or just a pending flag, depends on which of the four doorways you actually walk through. useActionState is the one that goes furthest, catching the return value as state. The others give you less by design.

`<form action={fn}>`, and the three things nobody tells you change

Before Actions existed, a form's only real path to running code was onSubmit, and that path came with requirements you had to remember every time. Call preventDefault, manually construct FormData from the event target, manage loading and error state by hand.

function OldForm() {
  function handleSubmit(e) {
    e.preventDefault();
    const formData = new FormData(e.target);
    // run the request, manage loading and error state yourself
  }
  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}

Swap onSubmit for a function passed straight to action and the mental model shifts more than the syntax suggests. Nothing calls preventDefault, not because you forgot it, but because React already knows this is an Action before the form ever fires, so the browser's default full-page reload was never going to happen in the first place. The function also stops receiving an event. It receives FormData directly, already built from every named field on the page, which is one less step you used to write by hand every time. And the request method itself stops being something you configure at all. A function passed to action always submits as POST, whatever you write in a method attribute sitting right next to it. That last one is the exact fact Part 3 ran into from the useFormStatus side, back when method kept coming back 'post' no matter what I expected walking in. It was never reading an attribute. It was reading the Action underneath it.

onSubmit still earns its keep for one job specifically. Anything that has to stop a submission before it starts, checking two password fields match, belongs there. By the time code inside the Action itself runs, the submission has already begun, so nothing in there can be the thing that prevents it.

Sync Actions exist. They're just not interesting

An Action doesn't have to be async. A plain synchronous function handed to the same four doors still counts, React still manages its lifecycle, but the pending window is usually too short to build UI around.

function resetSearch(previousState, formData) {
  return { query: "" };
}

The instant await shows up inside that function, everything from Parts 1 through 3 becomes worth having. React 18 required startTransition's callback to be synchronous. React 19 dropped that restriction, and that single change is what let useActionState, <form action={fn}>, and useTransition all accept async functions directly instead of you managing the async boundary by hand.

Client Actions and Server Functions are not the same word twice

Everything in this series so far has been a client Action, code that runs in the browser whether or not it talks to a server underneath. That version works identically in any React 19 setup, no framework required.

Server Functions are a related but genuinely separate idea, and they only exist in frameworks with Server Component support, Next.js being the obvious one. React's own docs are specific about the relationship here, and it's worth getting right instead of using the two terms interchangeably like I nearly did drafting this: a Server Function only becomes a Server Action once it's passed to an action prop or called from inside an Action. Not every Server Function is a Server Action. Every Server Action used this way is a Server Function.

"use server";

export async function submitFeedback(formData) {
  const message = formData.get("message");
  await db.feedback.create({ message });
}

That single formData argument is the shape a Server Function receives when it's handed directly to a form's action prop. It's worth flagging because it's not interchangeable with useActionState as-is, which always calls its function with (previousState, formData), the two-argument shape Part 1 introduced. Reusing server logic through useActionState means writing for that shape from the start, not dropping in a single-argument version and hoping React adapts it for you. It won't.

The fourth door: useTransition

useTransition hasn't come up by name once in this series, and the mechanism it exposes has been running underneath every single example anyway. Calling it gives you exactly two things back, an isPending flag and a startTransition function.

Every checkout example so far ran inside a <form>, which wraps its Action in a Transition automatically. useTransition is for when there's no form to lean on. Picture a wishlist heart icon sitting on a product card, no form anywhere near it, just a click handler that needs to hit the server and report whether it's pending.

import { useTransition, useState } from "react";

function WishlistButton({ productId, isSaved, toggleWishlist }) {
  const [isPending, startTransition] = useTransition();
  const [saved, setSaved] = useState(isSaved);

  function handleClick() {
    startTransition(async () => {
      setSaved(!saved);
      const result = await toggleWishlist(productId);
      startTransition(() => {
        setSaved(result.saved);
      });
    });
  }

  return (
    <button onClick={handleClick} disabled={isPending} aria-pressed={saved}>
      {saved ? "♥ Saved" : "♡ Save"}
    </button>
  );
}

Notice that second, nested startTransition wrapping setSaved after the await. If that looks familiar, it should, it's the exact same shape as onConfirmed getting wrapped in its own startTransition back in Part 2's comment box. That's not two separate patterns you happened to see twice. React only automatically tracks synchronous work as part of a Transition. Anything after an await needs its own startTransition call to still count, whether you're inside a comment form or a heart icon with no form in sight.

Notice too that the wishlist button above reaches for plain useState, not useOptimistic. That's not an oversight. This example exists to isolate what useTransition gives you entirely on its own, before any of the other three hooks get involved. In a real app you'd almost certainly reach for useOptimistic here instead, the exact instant-feedback job it was built for back in Part 2. Showing it with bare useState first is the only way to actually see what useTransition alone is doing.

Here's the part that's easy to miss and expensive to find out the hard way. Click that heart, unclick it, click it again fast, and a raw useTransition call gives you no guarantee about which result lands last. React says so directly: Actions inside a Transition don't guarantee execution order on their own. What's easy to assume, and what I nearly wrote into this section before checking, is that <form action={fn}> is just as exposed to that same problem as a bare useTransition call. It isn't. React's own docs group <form> actions together with useActionState as the two built-in ways that already handle ordering for you. It's raw useTransition, used on its own with nothing else wrapping it, that gets no such guarantee, the wishlist button above included. If you've been assuming that guarantee comes from Actions in general, it doesn't. It's specifically what useActionState and <form> actions add on top of the raw mechanism.

Where the four actually sit next to each other

You need to...	Reach for
Own a form's result and pending state in one place	`useActionState`
Show the finished UI before the server has confirmed it	`useOptimistic`
Read a form's pending state from a component that isn't managing it	`useFormStatus`
Run an Action outside a form and track its pending state	`useTransition`

They were never four competing answers to "which hook should I learn." They're four answers to four different questions that happen to share one mechanism underneath. The checkout form from Part 3 already proved it by combining two of them across four separate components, useActionState owning the submission, useFormStatus letting PlaceOrderButton read pending state with nothing passed down. Here's that same order form with a third hook layered on, a promo code that discounts the total the moment the form is submitted with it, before the server has confirmed anything.

import { useActionState, useOptimistic } from "react";
import { useFormStatus } from "react-dom";

async function placeOrder(previousState, formData) {
  const result = await submitOrder(formData);
  return { orderId: result.id, error: null };
}

function PlaceOrderButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Placing order..." : "Place order"}
    </button>
  );
}

function OrderForm({ cartTotal }) {
  const [state, formAction] = useActionState(placeOrder, {
    orderId: null,
    error: null,
  });

  const [displayTotal, applyDiscount] = useOptimistic(
    cartTotal,
    (current, discount) => current - discount,
  );

  function handleSubmit(formData) {
    if (formData.get("promoCode") === "SAVE10") {
      applyDiscount(10);
    }
    formAction(formData);
  }

  return (
    <form action={handleSubmit}>
      <p>Total: ${displayTotal.toFixed(2)}</p>
      <input name="promoCode" placeholder="Promo code" />
      <PaymentFields />
      <PlaceOrderButton />
    </form>
  );
}

useActionState still owns the real submission the same way it did in Part 3. useOptimistic shows the discounted total the moment the form submits with SAVE10 in the field, no waiting on submitOrder to confirm anything first, and it falls back on its own to whatever cartTotal currently is once the Transition settles. That fallback detail matters more than it looks. This trimmed-down version never actually updates cartTotal after submitOrder resolves, so the discount would vanish the instant the Action finishes, same trap Part 2 walked through with onConfirmed. A real version needs the parent to fold the confirmed, discounted total back into cartTotal once the order actually goes through, or the optimistic value has nothing real to settle into. useFormStatus still lets PlaceOrderButton disable itself with nothing passed down from OrderForm. Three hooks, one form, none of them stepping on the other's job.

The mistake I nearly baked into this whole series

Here's the trap I think this series set without meaning to. Teach one hook per post, three posts in a row, and a careful reader could walk away thinking the real task was picking a favorite, useActionState or useOptimistic or useFormStatus, as if only one of them belongs in a given form. That was never true. Composition was always the point. A real form rarely reaches for exactly one of these. It reaches for whichever two or three actually solve the piece of the problem sitting in front of it, and none of them are competing for the same job.

I built this series backwards on purpose, honestly, three concrete bugs before the concept underneath them, because I think a concept sticks harder once you've already felt the shape of the problem it solves. But it only works if the concept actually shows up eventually. This is that part.

If you want the deeper cut, sync versus async Actions in more detail, the full Server Functions section, and a proper FAQ, I wrote the complete version on my site: React 19 Actions Explained.

If you'd rather test what actually stuck first, I also built a 15-question quiz covering the same four APIs: React 19 Actions Quiz.

So here's the real question, the one I'd genuinely like an answer to. Which of these four have you already been using without knowing you were touching an Action? A <form action={fn}> you wired up because it looked simpler than onSubmit, a startTransition call you copied from somewhere without reading what it does, a button that felt laggy until you wrapped it in useTransition and never asked why that fixed it. Drop it below. I'm curious how many of us have been using this mechanism for months without a name for it.

I Turned On Cache Components in Next.js 16.3. It Refused to Build My Simplest Page.

Shubhra Pokhariya — Wed, 19 Aug 2026 13:58:25 +0000

I didn't want to write another "what's new in Next.js 16.3" post. Enough of those exist. I wanted to know what actually happens when you flip the flags on a real project, so I scaffolded a fresh app, turned on cacheComponents and partialPrefetching, and tried to build the simplest possible dynamic page.

It didn't build.

The setup

Nothing fancy. Fresh create-next-app, Next.js 16.3.1, two flags in next.config.ts:

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
};

Then a product page. No database, no external API, not even a real fetch, just a fake delay and the route's own params:

async function getProduct(id: string) {
  await new Promise((resolve) => setTimeout(resolve, 300));
  return { id, name: `Product ${id}`, price: 42 };
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold">{product.name}</h1>
      <p>${product.price}</p>
    </main>
  );
}

That's about as plain as a dynamic route gets. I expected next build to shrug and move on.

What actually happened

Error: Route "/products/[id]": Next.js encountered uncached or runtime data during prerendering.

`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)
  - [block] Set `export const instant = false` to allow a blocking route

Full build failure. Exit code 1. For a page whose only "dynamic" behavior is reading a param that's obviously going to be there.

My first reaction was that this felt aggressive. My second reaction, after rereading it, was that this is the whole point of the release and I'd missed it by only skimming the changelog. Cache Components in 16.3 doesn't treat an unguarded dynamic access as a warning. It treats it as a decision you have to make, explicitly, before it'll ship your build. Stream it, cache it, or mark it blocking on purpose. No silent fourth option where it just works and you find out it was never instant three months from now.

The fix, and what it actually buys you

I took the option the error suggested first: wrap the part that awaits params in <Suspense>.

import { Suspense } from "react";

async function getProduct(id: string) {
  await new Promise((resolve) => setTimeout(resolve, 300));
  return { id, name: `Product ${id}`, price: 42 };
}

async function ProductDetails({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);
  return (
    <>
      <h1 className="text-2xl font-bold">{product.name}</h1>
      <p>${product.price}</p>
    </>
  );
}

export default function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  return (
    <main className="p-8">
      <Suspense fallback={<p>Loading product...</p>}>
        <ProductDetails params={params} />
      </Suspense>
    </main>
  );
}

Ran the build again:

Route (app)
┌ ○ /
├ ○ /_not-found
└   /products/[id]
  └ ◐ /products/[id]

○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

That ◐ next to my product route is the actual feature. Next.js pulled out everything around the Suspense boundary, the shell, and prerendered it. The part that actually depends on which product you clicked streams in behind it. That's Cache Components' Partial Prerendering doing exactly what it's supposed to, a real route in a real build output, not a description from the release notes. It's also the same shell mechanism that Partial Prefetching, the client-side navigation feature 16.3 adds on top of this, depends on existing in the first place.

What this told me that the changelog didn't

Reading about Partial Prefetching, "a reusable shell per route, cached on the client," sounds like a nice-to-have you'd adopt when you get around to it. Hitting the build error told me something different: on a 16.3 app with Cache Components on, there's no version of "get around to it." Every uncached or runtime access Next.js finds during prerendering needs an answer, stream, cache, or block, the moment you turn the flag on. It's not gradual. It's a build gate.

That's a bigger adoption cost than "add two lines to your config" makes it sound, and I think that's exactly why Next.js ships next-cache-components-adoption as a first-party agent Skill now instead of leaving you to hunt down every unguarded params and cookies() call by hand across a real app. On a five-file test project this took me two minutes. On a real production route tree, I wouldn't want to do it without that tool, or without a very good sense of where every Suspense boundary in the app already is.

Where I'd actually start

If you're evaluating this for a real app: don't turn the flag on for the whole project and see what catches fire. Pick one route, ideally your simplest dynamic one, and watch what the build tells you it needs. It will tell you exactly what to do next. That part, at least, the error message gets right.

I wrote a longer breakdown of the full 16.3 release, what upgrades automatically with zero config changes, what Instant Navigations and Partial Prefetching actually change, and what shipped for AI agents, on my website if you want the whole picture before you decide whether to flip these flags on something real.

Has anyone else run the migration on an actual production route tree yet? I'd like to know what the first pass looks like on a real app.

React 19's useFormStatus Fixed My Prop Drilling. Then It Sat There Returning False

Shubhra Pokhariya — Wed, 12 Aug 2026 12:04:31 +0000

Part 1 was about waiting well. Part 2 was about not waiting at all. This one is about a value I needed in a component that never created it, and about the ten minutes I lost putting the hook in the one place it can't work.

If you've read Part 1 on useActionState and Part 2 on useOptimistic, both of those hooks answer a question from inside the component that called them. That was never a problem for a two-field newsletter form. It became one the day I split an order form into separate pieces, payment details in one file, the place-order button in another, and both of them needed to know the same thing: is this thing submitting right now.

The setup that made prop drilling look reasonable

Here's roughly what the form looked like before I touched useFormStatus at all.

import { useActionState } from "react";

function PaymentFields({ disabled }) {
  return (
    <fieldset disabled={disabled}>
      <input name="cardNumber" placeholder="Card number" />
      <input name="cardExpiry" placeholder="MM/YY" />
    </fieldset>
  );
}

function PlaceOrderButton({ pending }) {
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Placing order..." : "Place order"}
    </button>
  );
}

function OrderForm() {
  const [state, formAction, isPending] = useActionState(placeOrder, {
    message: "",
  });

  return (
    <form action={formAction}>
      <PaymentFields disabled={isPending} />
      <PlaceOrderButton pending={isPending} />
    </form>
  );
}

Nothing about this is broken. It works. But isPending lives in OrderForm, and both children only exist to receive it and hand it to a disabled attribute. Add a shipping section, an order-summary sidebar, a coupon field that should lock during submission, and every one of them needs the same prop threaded through, whether or not anything else about them changes. I'd read that useFormStatus was built to skip exactly this, so I went looking for where to put it.

Where I put it first, and why it did nothing

My first instinct was to call the hook right where isPending used to live, in OrderForm itself, treating it like a drop-in replacement.

import { useFormStatus } from "react-dom";

function OrderForm() {
  const { pending } = useFormStatus(); // stays false forever

  return (
    <form action={placeOrder}>
      <PaymentFields disabled={pending} />
      <PlaceOrderButton pending={pending} />
    </form>
  );
}

I clicked "Place order." Nothing disabled. No console warning, no red error overlay, just a button sitting there fully clickable while the network tab showed a request in flight. My first guess was that placeOrder wasn't actually async, or that I'd broken something in the action itself. I spent a few minutes staring at the action function before I even looked back at the hook.

The actual answer is simpler and, once you see it, a little obvious. useFormStatus doesn't read state that OrderForm owns. It reads the status of the parent <form>, and at the moment that hook call runs, OrderForm is still deciding what to render. The <form> tag doesn't exist as anyone's parent yet, it's the thing being built. There's no ancestor for the hook to find, so it falls back to its default, unpending shape, and it stays that way no matter how long the real submission takes.

The rule underneath that: the component calling useFormStatus has to be a descendant of the form it wants to read, never the component rendering the form itself. Fixing it meant pulling the hook out of OrderForm and putting it somewhere further down the tree.

import { useFormStatus } from "react-dom";

function PaymentFields() {
  const { pending } = useFormStatus();
  return (
    <fieldset disabled={pending}>
      <input name="cardNumber" placeholder="Card number" />
      <input name="cardExpiry" placeholder="MM/YY" />
    </fieldset>
  );
}

function PlaceOrderButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Placing order..." : "Place order"}
    </button>
  );
}

function OrderForm() {
  return (
    <form action={placeOrder}>
      <PaymentFields />
      <PlaceOrderButton />
    </form>
  );
}

Same markup, same behavior at a glance, and suddenly pending flips correctly. Neither child receives anything from OrderForm anymore. Both just ask their parent form what's going on and get told the truth.

One detail that's easy to miss on the way there: this hook comes from react-dom, not react. useActionState and useOptimistic both live in react, so if you're moving through this series in order, typing import { useFormStatus } from "react" is a genuinely easy slip, and it fails in a way that doesn't tell you what went wrong either.

The part I didn't expect: it's watching more than a boolean

Once pending worked, I assumed that was the whole hook. It isn't. Calling it gives you an object with three more properties riding along, and I only found a real use for them once I stopped treating useFormStatus as a fancy boolean.

const { pending, data, method, action } = useFormStatus();

data is the FormData currently being submitted, available only while something is in flight. I used it to make the button say something more specific than a generic spinner label:

function PlaceOrderButton() {
  const { pending, data } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? `Placing order for ${data.get("email")}...` : "Place order"}
    </button>
  );
}

data is null the rest of the time, so that .get("email") call only runs safely because it's tucked inside the pending branch of the ternary. Pull it out and call it unconditionally, and the component throws the first time it renders idle.

method is where I got tripped up briefly, because I assumed it would mirror whatever method attribute I'd have put on the form. It doesn't work that way once you're using a function-based action. Any form using the action prop with a function, which is the entire reason this hook has something to track in the first place, submits as 'post' regardless of anything else you configure. You'd only see 'get' here on a form using a plain URL string as its action, or no action prop at all, and the docs only commit to one thing about that case: action itself comes back null. They stay quiet on pending and data, and since only function-based actions actually run through React's Transition tracking, that's not a combination I'd build anything around.

action is a reference back to whatever function you passed to the form's action prop. It's null for a form with no function-based action, and it's also null if there's no parent form at all, which means a falsy value here doesn't automatically tell you which of those two is true. I hit this once trying to conditionally render something based on whether action existed, and had to remind myself both cases collapse to the same falsy check.

The reused-component trick I didn't plan for, and the one I got burned by

The nicest surprise came later, almost by accident. PlaceOrderButton wasn't just used on the checkout page. It got reused, unmodified, on a "save draft order" form elsewhere in the app. I expected to need some kind of context or ID to tell it which form it belonged to. I didn't. useFormStatus resolves the nearest ancestor form independently everywhere it's rendered, so the same component read the correct pending state on both forms without a single line of extra wiring. That's not an edge case worth working around, it's a real reason to build small, reusable status-aware components in the first place.

The edge case that did surprise me went the other direction. Somewhere in an admin panel, a designer had wired a button outside its form using the HTML form="orderForm" attribute instead of physically nesting it. Pure HTML, no React opinion needed, and it submits the form fine. useFormStatus inside that button read as permanently not-pending, even while the form it was technically attached to was mid-submission. The hook walks the component tree, not the DOM-level form attribute association, so as far as it's concerned, that button was never a child of anything. Worth knowing before it surprises you in a codebase that uses this attribute anywhere.

Where I stopped reaching for it

Not every form needed this. On a two-field signup form with a single button in the same component, useActionState's own isPending, read directly where the hook was called, did the job without adding a second hook and a second rule to remember. useFormStatus earns its place once a form's parts genuinely live in separate components, not before.

And it only ever tells you about a submission already underway. useFormStatus isn't a validation API, it tells you what the form is doing once submission has started, not whether that submission should have been allowed to start in the first place. That decision still belongs upstream, in the action function or wherever else you're handling the submit.

Where useActionState, useOptimistic, and useFormStatus actually sit

Three parts into this series and the boundaries finally made sense to me as one picture instead of three separate hooks to memorize. useActionState owns a result and reacts to it, from wherever it was called. useOptimistic shows the finished UI before the server has actually agreed to it. useFormStatus answers one question, is this form pending, from any component underneath it, with nothing passed down to make that possible.

The distinction that finally made it stick for me: useActionState's isPending follows an Action, specifically the one dispatched through that hook call. useFormStatus's pending follows a form, whichever <form> happens to be its nearest parent, regardless of which component or which action put it there. That's why the same PlaceOrderButton worked unmodified on two different forms with two different actions later on. It was never watching an action. It was watching whatever form it happened to be sitting inside.

They stack without fighting each other. The order form I started with ended up using two of the three, useActionState in the parent owning the result, useFormStatus in every child section reading the same pending state independently.

I wrote the full breakdown on my site, including the complete four-section checkout example combining both hooks, the exact difference between this and useActionState's own isPending, and a side-by-side table for picking the right one: React 19 useFormStatus Explained.

If you want to test what you just learned, I also put together a short React 19 useFormStatus Quiz.

If you've built a form where the submit button lives three components away from the one managing the submission, it's worth checking where you actually called the hook before you assume something's broken. I know that's exactly where I lost ten minutes I didn't need to.

I Know the Recipe. I Miss the Winter Kitchen.

Shubhra Pokhariya — Sat, 08 Aug 2026 17:16:03 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art.

Inspiration

When I first read Comfort Food, my mind immediately went somewhere I haven't visited in years.

Not to pizza. Not to desserts. Not even to my favorite recipes.

It went back to my childhood kitchen.

During winter, even though we had a gas stove, my mother would often light our clay chulha. The kitchen felt warmer, the fire crackled softly, and one by one the phulkas would puff over the flame.

I still remember sitting there with my father and siblings, all of us eating from the same plate while waiting for the next phulka to arrive. It wasn't a special recipe. Just wheat flour, water, fire, and my mother's hands.

I've eaten many wonderful meals since then, but somehow those simple phulkas are still the first thing that comes to mind when someone asks me about comfort food.

I still remember how she would quietly place another phulka in front of me before I could even say I was full. If I protested, she'd smile and insist, "Just one more." Somehow, there was always one more.

Today I still love cooking. I know exactly how to make soft phulkas myself. But every now and then I realize I was never missing the recipe.

I was missing that winter kitchen. That feeling of waiting together. That warmth.

Somewhere while writing this, I stopped thinking about the challenge. I wasn't writing a submission anymore. I was simply writing down a memory I never wanted to forget.

Before anyone else reads this, I already know who I want to send it to first. My siblings. Because they'll know exactly which kitchen I'm talking about.

Demo

View the live demo on CodePen

What you're looking at: a clay chulha, firewood at the opening, flames glowing between the sticks, and a phulka cooking on the tawa. Nothing else. I wanted to keep the scene simple and let the story carry everything that isn't visible in the CSS.

The interaction: tap the phulka. It rises and settles, and one line stays on screen for a moment. I never missed the recipe. I missed the winter kitchen.

Journey

As a frontend developer, I wanted this project to be more than drawing food with CSS. I wanted to get the shape right, because the shape is the first thing anyone who grew up around a chulha will recognize, and the first thing that would look wrong to them if I got it wrong.

My first pass was a rounded dome. It looked warm, but it didn't look like a chulha. It read more like generic firelight. The chulha I remember has a solid, tapered clay body with a flat cooking surface on top. I reshaped the base and used layered gradients and border-radius to give the clay body its rounded, hand-built form, then moved the fire into a proper opening at the front instead of letting the flames float above the structure. That single change did more for the piece than every gradient I'd added before it.

The firewood took a few tries. Real sticks angle outward from the opening at different rows, not in a neat fan, so I gave each one its own rotation and length instead of repeating one shape three times. The flames sit low among the sticks now, several small uneven tongues instead of a few tall symmetrical ones, each flickering on its own timing so they never move in sync.

The phulka's lighting was the detail I'm proudest of getting right. The fire sits below and in front of it, so the warm highlight has to come from underneath, not from a generic top-left light source the way most CSS food art defaults to. Once I flipped that, it stopped looking like a painted circle and started looking like something actually sitting near heat.

The puff interaction runs on a single checkbox and the :has() selector. No JavaScript anywhere in the file. Tap the phulka, it lifts with a spring easing, and the line fades in at the top of the scene. prefers-reduced-motion turns off the fire and smoke animations and settles everything into a still, warm frame for anyone who needs that.

I started with more in the frame, a rolling pin, a cloth, even the whole kitchen at one point. Every version I stripped back felt more honest than the one before it. I realized I didn't need to recreate the entire kitchen to tell the story. The kitchen, my mother, my siblings, the warmth, and those hot phulkas are all part of the memory, but the chulha and the phulka are what I could recreate in CSS without trying to turn the memory itself into an illustration. So I kept the scene simple: the chulha, the fire, and the phulka. Everything else lives in the story behind it.

Comfort food isn't always the most elaborate meal. Sometimes it's the simplest one, because what we remember isn't the recipe. It's the people we shared it with.

I hope everyone who sees this remembers a kitchen that instantly takes them back home, wherever home may be.

Built with pure CSS. No JavaScript, no frameworks, no libraries.

React 19's useOptimistic Fixed My Instant UI. Then Combining It With useActionState Broke My Reset Button

Shubhra Pokhariya — Tue, 04 Aug 2026 16:39:10 +0000

Part 1 was about waiting well. This one is about not waiting at all, and about a couple of mistakes I made along the way that are worth walking through in the open.

If you read Part 1 on useActionState, you already know the shape of the problem it solves: three hand-rolled state variables, a try/catch/finally, and a pending flag you're hoping stays in sync with reality. useActionState fixes that for the "wait for the server, then show the result" case, and I closed that piece by saying useOptimistic was the next hook worth learning. This is that piece. But some interactions never wanted to wait in the first place. A comment posts. A like fires. A checklist item gets ticked off. The user expects to see the outcome the instant they act, not the instant the network agrees with them.

That's the gap useOptimistic fills. And building a real example that combines it with useActionState is what exposed two mistakes I'd made without realizing it.

The old trick, and why it quietly lied

Before this hook existed, "instant" UI usually meant something like this:

function handleLike() {
  setLiked(true); // update now, hope the request agrees later
  fetch("/api/like", { method: "POST" }).catch(() => {
    setLiked(false); // manually undo it if the request fails
  });
}

It works, until it doesn't. Forget the catch block and a failed request leaves the UI lying to the user forever. Get a second click in before the first request resolves and you're racing two local booleans against two network calls with no ordering guarantee between them. I shipped a version of this on a follow button once and spent an evening figuring out why the count would occasionally drift by one after a flaky connection. The state wasn't wrong because of a typo. It was wrong because nothing was actually managing the relationship between what I was showing and what was confirmed.

useOptimistic manages exactly that relationship, and it does it without you writing a single line of manual rollback logic, as long as you actually wire it up right. Keep reading, because I didn't, on the first pass.

What it does, briefly

const [optimisticState, setOptimistic] = useOptimistic(value, reducer?);

value is your real, confirmed state, the thing you'd render if nothing were in flight. optimisticState matches value right up until you call the setter inside a Transition, at which point it temporarily reflects whatever you passed in. Once the Transition settles, optimisticState collapses back to value. Not a value you have to reset. Not a flag you have to flip back. It falls back on its own, because that was always the only thing it was ever equal to once nothing's pending.

I go through the full API, the updater-function-versus-reducer decision, and the edge cases in the complete useOptimistic tutorial, so I won't repeat that ground here. What I want to get into is what happens when useActionState and useOptimistic end up in the same form, specifically around resetting it, because that's where things stopped being simple.

Combining them: a comment box

Here's the version I ended up with, after fixing what I got wrong the first time around.

import { useActionState, useOptimistic, startTransition } from "react";

function CommentBox({ comments, onConfirmed }) {
  async function postComment(previousState, formData) {
    if (formData === null) {
      return { error: null };
    }
    const text = formData.get("comment");
    if (!text?.trim()) {
      return { error: "Comment can't be empty." };
    }
    const saved = await saveComment(text);
    startTransition(() => onConfirmed({ id: saved.id, text }));
    return { error: null };
  }

  const [state, formAction, isPending] = useActionState(postComment, {
    error: null,
  });

  const [optimisticComments, addOptimisticComment] = useOptimistic(comments);

  async function handleSubmit(formData) {
    const text = formData.get("comment");
    const id = crypto.randomUUID();
    addOptimisticComment((current) => [...current, { id, text }]);
    return formAction(formData);
  }

  function handleReset() {
    startTransition(() => formAction(null));
  }

  return (
    <div>
      <ul>
        {optimisticComments.map((c) => (
          <li key={c.id}>{c.text}</li>
        ))}
      </ul>
      <form action={handleSubmit}>
        <input name="comment" disabled={isPending} />
        <button disabled={isPending}>Post</button>
        <button type="button" onClick={handleReset} disabled={isPending}>
          Reset
        </button>
        {state.error && <p role="alert">{state.error}</p>}
      </form>
    </div>
  );
}

CommentBox takes an onConfirmed callback the same way the upvote example in the full tutorial does, and it matters for the same reason. useOptimistic never updates the real comments prop for you. Something outside the hook has to. Once saveComment resolves, postComment calls onConfirmed with the confirmed comment, and the parent is expected to fold that into its own state, the same pattern as this:

function CommentThread({ postId }) {
  const [comments, setComments] = useState(initialComments);
  return (
    <CommentBox
      comments={comments}
      onConfirmed={(comment) =>
        setComments((current) => [...current, comment])
      }
    />
  );
}

Skip that wiring and you'll watch every comment you post disappear the moment the Transition settles, even though the server accepted it. That's not a hypothetical. It's the exact "shows you the future, doesn't make it real" mistake the full tutorial calls out, and it's worth restating here because it's easy to leave out of an example like this without noticing.

Notice too that onConfirmed is called inside its own startTransition, nested after the await. That's not decoration. If you update real state after an await inside a reducerAction, the docs are specific that it needs its own Transition wrapper, the same requirement the tutorial's edge cases section covers for the LikeButton example.

One more small thing worth calling out, because I got it wrong on an earlier draft of this same example: the id for each optimistic comment is generated with crypto.randomUUID() in handleSubmit, before it ever reaches the updater passed to addOptimisticComment. Not inside the updater itself. The reducer or updater you give useOptimistic has to be pure, the docs say so directly, and something like Date.now() called from inside it isn't. React can invoke that function more than once for the same update, and a fresh id each time it's called turns one comment into two different keys in your list.

Why remounting breaks more than the form

useActionState doesn't give you a way to clear its own state automatically. One common fix is bumping a key prop to force the whole component to remount, and on its own that's a reasonable option. It does reset the form. This is a different thing from requestFormReset, which React 19 also ships. That one clears uncontrolled DOM field values, not the state useActionState is holding on to, so it solves a narrower problem than the one we're talking about here.

The remount trick has a cost that doesn't show up until useOptimistic enters the picture. A remount doesn't just clear useActionState's result. It tears down and rebuilds the whole component tree underneath that key, and any useOptimistic state riding along in that same component gets torn down with it. If a Transition using that optimistic state hadn't settled yet, the optimistic item doesn't get replaced by the real one. It just vanishes.

My first fix for this, on an earlier pass, was to give the optimistic side its own reset branch too, mirroring the reset-signal pattern useActionState's own docs recommend. Something like:

function commentReducer(current, action) {
  if (action.type === "reset") return [];
  return [...current, action.item];
}

That looks reasonable and it's wrong in a way that only shows up once you trace what current actually holds. current isn't just the pending draft, it's the whole list, confirmed comments included. Returning [] unconditionally means clicking Reset would briefly wipe out comments that had already been saved, not just cancel whatever hadn't gone through yet. It settles back once the Transition resolves, since comments itself never changed, but for a moment the list a real user is looking at goes empty for no reason they'd understand.

The actual fix was realizing useOptimistic doesn't need a reset branch here at all. By the time Reset is even clickable, isPending is false, which means nothing is pending, which means optimisticComments already equals comments. There's nothing left for a reset to clear. The only state that genuinely needed a manual way to reset was useActionState's own return value, the error message, and that's exactly what formAction(null) handles in handleReset above. One piece of state actually needed telling to reset. The other one already had, on its own, which is the whole point of how useOptimistic works in the first place.

Resetting while an action is pending, and the AbortController pattern I got wrong

There's still a real question buried in here: what happens if Reset gets triggered while a submission is still in flight?

In an earlier draft I said React doesn't provide a cancellation mechanism for this. That was wrong, and worth correcting properly instead of quietly editing around it. The current useActionState reference has a section called "Cancelling queued Actions" that threads an AbortController through the payload passed to dispatchAction, letting a new dispatch abort whatever's still pending so it can run immediately instead of waiting in line. It's a documented recipe, not something you'd have to invent from scratch.

What I said next holds up better. Whether you should actually reach for that pattern depends on what the pending action does. The docs are blunt about it: aborting an Action isn't always safe, because cancelling the request client-side doesn't undo a mutation that already landed on the server. If saveComment already wrote to the database by the time an abort fires, the comment is still there no matter what the client thinks happened.

That's why handleReset above never reaches for AbortController. It calls formAction(null) the same way it calls every other dispatch, and because useActionState processes calls to dispatchAction in the order they arrive, the reset just queues behind whatever's still running instead of racing it. Disabling the Reset button while isPending is true isn't there to prevent a bug. It's there so the person clicking it isn't left wondering why nothing happened yet.

If you're building something where cancelling mid-flight genuinely matters, a search-as-you-type action where a stale result arriving late would actively confuse the user is a good example, that AbortController pattern is worth reaching for. For a mutation like posting a comment, letting it finish is the safer default, and as it turns out, the simpler one too.

The takeaway

useOptimistic asks very little of you on its own: show a value, let it fall back automatically. The two mistakes I walked through here both came from not trusting that. Forgetting to close the loop with onConfirmed meant the hook had nothing real to fall back to. Giving it its own reset branch meant fighting a job it was already doing correctly by itself. Trust the parts that are automatic, wire up the parts that aren't, and reset only the state that actually needs telling.

If you haven't read the full breakdown of useOptimistic, including the mistake that makes optimistic updates snap back even on success and when to reach for a reducer instead of an updater function, that's here: React 19 useOptimistic Explained. And if you're doing this inside a real Next.js app with Server Actions, cache invalidation, and error boundaries in the mix, the rollback pattern deep dive covers the parts that only show up once you're past the demo.

React 19's useActionState Showed Me Why Disabling My Submit Button Was Never Enough

Shubhra Pokhariya — Tue, 28 Jul 2026 10:50:54 +0000

Every form I ever shipped before React 19 needed the same three pieces of state, and I wired them up by hand every single time.

One for the result. One for whether it's submitting. One for the error. And at least once a sprint, I'd forget to reset one of them in the right place and spend twenty minutes staring at a button that wouldn't re-enable.

Here's the version I wrote for years, probably the same one you have sitting in a dozen components right now:

function OldSignupForm() {
  const [error, setError] = useState(null);
  const [isSubmitting, setIsSubmitting] = useState(false);

  async function handleSubmit(e) {
    e.preventDefault();
    setIsSubmitting(true);
    setError(null);
    try {
      await signup(new FormData(e.target));
    } catch (err) {
      setError(err.message);
    } finally {
      setIsSubmitting(false);
    }
  }

  return <form onSubmit={handleSubmit}>{/* ... */}</form>;
}

Three state variables. A try/catch/finally. And one bug waiting to happen the moment someone forgets that finally.

I didn't think this pattern was a problem until I actually sat down with useActionState and realized the workaround I'd been shipping to "fix" double submits was never actually fixing anything.

The habit that felt safe but wasn't

Here's what I mean. Most of us migrate a form like this by adding some version of:

function handleClick() {
  setLocalPending(true); // feels safe, isn't tied to anything real
}

On a fast connection, you'll never notice this is broken. On a slow one, that local flag can flip back to false before the actual request has resolved. A user on spotty wifi taps "Place Order" twice, maybe three times, because the button looked re-enabled for a split second. Each tap still goes through. React doesn't drop them, and it doesn't race them either. It queues them and runs them one after another, in order. So instead of one order, you've got three, each one processed like it was intentional.

That was the moment useActionState stopped feeling like just another hook to memorize. It started feeling like React quietly admitting they had watched enough of us get this wrong and finally built the fix.

What it actually does

const [state, formAction, isPending] = useActionState(fn, initialState);

You give it a function, React calls that function with (previousState, formData) whenever the form submits, and whatever it returns becomes your new state. isPending is tied to React's own transition tracking, not a boolean you're guessing the timing of.

A working example, no framework required, plain React:

import { useActionState } from "react";

async function subscribe(previousState, formData) {
  const email = formData.get("email");

  if (!email || !email.includes("@")) {
    return { success: false, message: "Enter a valid email." };
  }

  await new Promise((resolve) => setTimeout(resolve, 800));
  return { success: true, message: "You're subscribed." };
}

function NewsletterForm() {
  const [state, formAction, isPending] = useActionState(subscribe, {
    success: false,
    message: "",
  });

  return (
    <form action={formAction}>
      <input type="email" name="email" placeholder="you@example.com" />
      <button type="submit" disabled={isPending}>
        {isPending ? "Subscribing..." : "Subscribe"}
      </button>
      {state.message && <p>{state.message}</p>}
    </form>
  );
}

No onSubmit. No preventDefault. No separate pending flag to keep in sync. Swap disabled={isPending} in for that fake local flag, and the double-submit problem you thought you'd solved actually gets solved.

The part that genuinely surprised me

I assumed rapid clicks would race each other. Maybe the last one wins, maybe the first one does, classic race-condition territory. That's not what happens.

React queues every call to the action function and runs them sequentially. Each one waits for the previous one to finish before it starts. Click "Add to Cart" four times fast and it takes roughly four times as long to settle, not because anything's broken, but because call two is patiently waiting for call one's promise to resolve first. Nothing races. Nothing gets silently dropped.

Which means the real problem was never a corrupted database write. The problem is that every click still counts. Five taps on a slow connection means five processed actions, not one. disabled={isPending} isn't there to prevent a race, since there isn't one. It's there to stop someone from queuing up four actions they never meant to trigger in the first place.

One more thing worth knowing before it bites you. If an earlier call in that queue throws, React skips every call still waiting behind it. Catch your errors and return a state object instead of letting anything throw, or you'll lose queued actions you never even knew were sitting there.

async function submitOrder(previousState, formData) {
  try {
    const result = await placeOrder(formData);
    return { success: true, orderId: result.id };
  } catch (err) {
    return { success: false, error: "Something went wrong. Try again." };
  }
}

Two more traps I walked straight into

Stale closures. If your action function reaches into component-scoped variables instead of pulling straight from formData.get(...), you're one re-render away from acting on data that's already out of date. Prefer reading submitted values from formData instead of relying on values captured from an earlier render.

Forgetting there's no reset button. useActionState has no built-in way to clear its own state. The docs say so plainly. If you need a "start over" button, you have two real options. Teach your action function to recognize a reset signal as one of its inputs, or change the component's key prop to force a full remount. The reset-signal route is usually the less disruptive one, since it doesn't tear the DOM down to do it.

When I don't reach for it

If the interaction needs to feel instant, think a like button or a checkbox, anything where the UI should update before the server has even responded, useActionState will always feel a beat too slow for that. That's useOptimistic's job, and it's worth pairing the two once you've got the basics down.

And if it's a multi-step wizard with controlled inputs across steps that aren't all mounted at once, fighting the uncontrolled-form model useActionState is built on usually costs you more code than it saves.

The actual takeaway

The pattern you've probably been shipping, disable on click and hope for the best, was hiding the real issue instead of solving it. Every click still lands whether the button looks disabled or not. useActionState doesn't just cut boilerplate. It ties your pending state to something real, so the thing you thought you fixed actually gets fixed.

I wrote the full breakdown on my site, including the complete production signup example with field-level validation, the side-by-side comparison table against useState and useFormStatus, and the accessibility details around aria-busy and disabling inputs during a pending state: React 19 useActionState Explained

I honestly thought I understood this pattern until I started testing it properly. It turned out the problem wasn't React at all. It was the way I'd been managing pending state for years.

If you've been relying on your own pending state to handle form submissions, it's worth taking another look. I know I was surprised by what actually happens.

The Optimistic UI Race Condition That Only Showed Up on the Fifth Click

Shubhra Pokhariya — Tue, 21 Jul 2026 10:24:35 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

I originally shared this debugging story on July 8. When Bug Smash was announced, it immediately came to mind because nothing crashed, nothing logged an error, and the application was still wrong.

The setup

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.

That was the trap. Optimistic UI is designed to look right immediately. Looking right and being right are not the same claim.

The moment I stopped trusting the demo

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 is the bug that is easy to miss with optimistic UI specifically, because the whole point of optimistic UI is that it looks right immediately.

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.

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

One comment made me think harder

After the original post went up, Nazar Boyko left a comment that stuck with me.

He pointed out something I hadn't really separated in my own head. Disabling the checkbox only blocks clicks that go through that specific input. If the same toggle can ever be triggered another way, like a keyboard shortcut or somewhere else in the app, the disabled attribute is only one layer of protection. The real guard is the id keyed pending state, because that prevents the same operation from starting again regardless of how it was triggered.

He also mentioned that the rollback explanation was the part that clicked for him. Most examples manually flip the state back in a catch block without explaining why. Realizing that a plain toggle doesn't need that extra step was one of the biggest things I learned while digging into useOptimistic, so it was nice to hear that it helped someone else too.

That's one of my favorite things about writing technical posts in public. Sometimes someone doesn't find a bug in your code. They help you explain the idea more clearly or think about it from a different angle.

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, does not need solving. useOptimistic does not 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 is one real exception. If the optimistic value is something the server has not confirmed yet at all, a new comment you added with a placeholder id before the database assigned a real one, there is no prior version of that item sitting in your base state to fall back to. A failed insert does not revert a flag, it has to remove something that only ever existed on the client. That is the one case where you keep your own local record of what you added and clear it yourself in the catch block. A toggle does not 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 the site to block on a single write.

For a checkbox someone is staring at as they click it, updateTag is the right one, since it expires the tag immediately so the page the user is currently on reflects their own write right away. If that same task count also fed a sidebar stat somewhere else on the site, one nobody is watching in real time, revalidateTag on that same tag lets it catch up a beat later instead.

One thing worth knowing if you are 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.

What changed for me

I used to demo optimistic UI by clicking once.

Now I deliberately try to break it. Five rapid clicks. Slow networks. Repeated interactions.

Race conditions rarely announce themselves. They don't throw exceptions. They don't light up your console. They quietly wait for a user who is just a little more impatient than you were during development.

That checkbox looked perfect every time I demonstrated it. The bug was there the whole time. It was simply waiting for me to test it like a real user.

If you'd like the full walkthrough, including the rollback patterns, cache decisions, and the rest of the implementation, I've put it all here: shubhra.dev/tutorials/nextjs-16-useoptimistic-rollback-pattern

DEV Community: Shubhra Pokhariya

React 19 useFormStatus Returning False? I Built a SubmitButton That Fixes It

What the first post didn't cover

Locking the rest of the form while it submits

The bug I didn't catch until the second pass

Where this landed

React 19's useTransition Looked Simple. Then I Found a Second Bug Hiding Inside the First One

What useTransition Actually Gives You

A Search Filter That Doesn't Freeze the List

The await Rule, and Why It Actually Happens

Pending UI With No Form in Sight

Errors in a Bare Transition

The Race Condition Nobody's First Draft Handles

When to Reach for useTransition and When Not To

Where This Leaves the Series

The Code I Couldn't Leave Alone

I Throttled My App to Slow 3G. Here's What My Tests Never Caught

Bug one: a race condition, search results arriving in the wrong order

Bug two: the autosave that saves twice, or drops your last edit

What both actually have in common

I Tested generateStaticParams in Next.js Cache Components. My Layout Broke Twice

Does generateStaticParams make a route static?

The bug that took three attempts

What I'd actually check on a real app

React 19 Actions: I Explained 3 Hooks Without Ever Explaining What an Action Is

The word I kept using and never defined

Why any of this needed inventing

<form action={fn}>, and the three things nobody tells you change

Sync Actions exist. They're just not interesting

Client Actions and Server Functions are not the same word twice

The fourth door: useTransition

Where the four actually sit next to each other

The mistake I nearly baked into this whole series

I Turned On Cache Components in Next.js 16.3. It Refused to Build My Simplest Page.

The setup

What actually happened

The fix, and what it actually buys you

What this told me that the changelog didn't

Where I'd actually start

React 19's useFormStatus Fixed My Prop Drilling. Then It Sat There Returning False

The setup that made prop drilling look reasonable

Where I put it first, and why it did nothing

The part I didn't expect: it's watching more than a boolean

The reused-component trick I didn't plan for, and the one I got burned by

Where I stopped reaching for it

Where useActionState, useOptimistic, and useFormStatus actually sit

I Know the Recipe. I Miss the Winter Kitchen.

Inspiration

Demo

Journey

React 19's useOptimistic Fixed My Instant UI. Then Combining It With useActionState Broke My Reset Button

The old trick, and why it quietly lied

What it does, briefly

Combining them: a comment box

Why remounting breaks more than the form

Resetting while an action is pending, and the AbortController pattern I got wrong

The takeaway

React 19's useActionState Showed Me Why Disabling My Submit Button Was Never Enough

The habit that felt safe but wasn't

What it actually does

The part that genuinely surprised me

Two more traps I walked straight into

When I don't reach for it

The actual takeaway

The Optimistic UI Race Condition That Only Showed Up on the Fifth Click

The setup

The moment I stopped trusting the demo

The fix isn't anything specific to useOptimistic

One comment made me think harder

The rollback question that sent me down a rabbit hole

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

What changed for me

`<form action={fn}>`, and the three things nobody tells you change