React Form Actions: useActionState & useFormStatus Guide

You've built this submit button before. useState(false) for isSubmitting, set it true at the top of the handler, await the request, set it back false in a finally. It works — until a teammate adds an early return inside a validation branch that skips the finally, or a request fails in a way your catch didn't anticipate, and now the button is disabled forever. The state and the reality it's supposed to describe have quietly come apart.

This is episode three of React Deep Dive, a weekly series on what React itself decides, not JavaScript with a React import at the top. The first two episodes covered re-render vs. remount and what the React Compiler automates — useful background, neither required here. This episode is about form Actions: useActionState, useFormStatus, and useOptimistic, and the specific problem they solve, which isn't "nicer syntax for async handlers" — it's removing a piece of state you were maintaining by hand and could get wrong.

This article is written against React 19.2 (verified 19.2.8, the current npm release as of this writing) and assumes React 19-era function components and hooks throughout.

By the end of this article you'll be able to:

You've written function components with useState and useEffect, and you've handled at least one form submission with a manual loading flag. No prior exposure to React 19's Actions is assumed.

Here's the version most of us wrote before React 19:

This isn't wrong, and for a single form it isn't even that risky. The bugs show up as the form grows: a second early return added months later that bypasses the try, a child button that also needs to know isSubmitting and now takes it as a prop, a second submit handler that copies this pattern and forgets the finally. isSubmitting is a fact you're asserting about the world — "a request is in flight" — and nothing enforces that the assertion stays true. It's exactly the kind of derived state that's easy to let rot, the same category of bug as storing a value in state when you could have computed it from something else.

The mental model: a function passed to a <form>'s action prop (or a <button>'s formAction prop) becomes an Action — React runs it inside an implicit transition, the same mechanism behind startTransition. The pending flag you get back (isPending from useActionState, or pending from useFormStatus) is not a useState you or React set by hand — it's derived from whether that transition is currently in flight. It flips true the instant the action starts and flips back false when the action's returned state finishes committing, on the success path and the error path alike, because both are just the transition ending. There's no finally to forget, because there's no manually-set flag to reset.

That's the whole shift: you stop asserting "a request is in flight" with a boolean you maintain, and start asking React "is the transition I handed you still running" — a question it can always answer correctly, because it's the one running it.

The smallest form of this is passing a function directly to action — no hook required yet:

Key concept: the function receives the submitted FormData directly — no e.preventDefault(), no reading e.target.elements by hand. React intercepts the native submit, builds the FormData, and calls your function inside a transition. On success, React automatically resets the form's uncontrolled fields, mirroring what a plain HTML form submission would have done. This stage has no visible pending state yet — for that, reach for useActionState.

useActionState bundles three things a form usually needs — the action's result, whether it's still running, and a wrapped version of the action to pass to action — into one hook:

The signature is useActionState(fn, initialState, permalink?), returning [state, formAction, isPending]. fn receives (previousState, formData) — the previous return value is threaded back in automatically, which is exactly the "give me the last result" pattern a reducer gives you, applied to an async action. state is initialState until the action has run once, then it's whatever fn last returned. formAction is what you pass to the form's action prop; calling the raw saveName directly wouldn't give you isPending or the threaded previousState.

Key concept: the error here is returned, not thrown. That distinction matters enough to get its own section below — it's the one real trap in this whole feature.

A submit button that needs to know "is my parent form pending" doesn't have to receive that as a prop:

useFormStatus reads status from the nearest enclosing <form> through context — { pending, data, method, action }. The one rule that trips people up: the component calling it must be a descendant of the <form>, never the same component that renders the form. Call it inside ProfileForm itself and pending is always false, because from <form>'s own perspective there's no enclosing form to read.

This is the payoff for a design system: a <SubmitButton> component that works inside any form, with zero props, because the status lives in context rather than being threaded down by hand.

Layered on top, useOptimistic(actualState, updateFn?) returns [optimisticState, addOptimistic] — a value that snaps back to actualState once the surrounding action settles, letting the UI update the instant the user acts rather than waiting for the network:

Key concept: setOptimisticLiked only has an effect while called inside a transition (an Action, or an explicit startTransition) — outside one, it's a no-op that just re-renders with the real state. If toggleLike fails and never updates the real likedByMe, the optimistic value reverts on its own once the transition ends; you don't manually roll it back the way you would with a hand-rolled optimistic update.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

No. Everything in this article runs with plain client-side functions — saveName, subscribe, toggleLike are ordinary async functions, no "use server" directive involved. Server Actions (functions that actually execute on a server, callable from a client component) are a related but separate feature that frameworks like Next.js build on top of this same Actions mechanism.

Only its uncontrolled fields, and only after the action's promise resolves without the action itself preventing it. Controlled fields (anything with value tied to state) are unaffected — you're already the one deciding what they show.

They describe the same underlying transition. useActionState's isPending is available in the component that owns the form and called the hook. useFormStatus's pending is for a descendant component that doesn't have access to that hook's return value and would otherwise need it prop-drilled down.

Yes — nothing about it is form-specific. The like-button example above never touches a <form>; it just needs the state update wrapped in a transition (an Action or startTransition) to take effect.

Each call to the wrapped formAction starts its own transition; React processes them in the order they were dispatched, threading each previousState from the prior one. In practice, keep the trigger disabled while pending/isPending is true (every example above does this) so a second dispatch normally can't start until the first finishes.

Think it clicked? Take the 7-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

The button that stayed disabled forever in the opening example was disabled because a human had to remember to turn it back off, and one code path forgot. Actions remove that human step for the pending flag specifically — not by hiding the async work, but by tying isPending to something that's always accurate: whether the transition you started is still running. The try/catch/finally scaffolding doesn't disappear; it moves inside the action, where a missed case fails loudly (a thrown error, caught by a boundary) instead of quietly (a button stuck disabled that nobody notices until support tickets show up).

Have you moved a form over to useActionState yet, and did the "return the error, don't throw it" rule bite you the first time? Tell me in the comments.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: