Log in
Every form I built before React 19 needed the same three pieces of state. One for the result. One for whether it's submitting. One for the error. Every time, I wired them up by hand, and every time I forgot to reset one of them in the right place.
useActionState is React's answer to that. It's not magic, it's just React finally admitting that "handle a form submission" is a common enough pattern to deserve its own hook. Here's what it actually does, where it breaks in production, and where it doesn't belong.
This is Part 1 of the React 19 Deep Dive series. It's framework-agnostic, everything here works in plain React, not just Next.js. If you're working inside Next.js specifically, my Server Actions production guide and the useOptimistic rollback pattern post go deeper on how these hooks behave with Server Actions.
I'm running React 19.2.7 while writing this, verified directly, not assumed. I built and ran every code example in this tutorial against that exact version before publishing it.
Forms are the one place in a React app where you're almost always doing the same three things: run an async operation, track whether it's in flight, and show the result or the error when it's done. Nobody wrote a reusable abstraction for that because everyone's forms look "just different enough."
React 19 pulled the pattern out anyway. useActionState ties a function directly to a form's action attribute, or a button's formAction, and gives you back the state, the pending flag, and a wrapped action, all synced to the same transition. It works with any action function you give it, not exclusively Server Actions, you can use this in a plain client-rendered React app with no framework at all. Progressive enhancement, where the form still works before JavaScript finishes loading, is a separate benefit layered on top, and it depends on your framework or runtime actually supporting server rendering. In a plain client-side app it won't apply, the hook still works, you just don't get that extra layer for free.
This is the pattern most of us wrote by hand for years:
Three state variables, a try/catch/finally, and one bug waiting to happen if you forget the finally. useActionState collapses that into one hook call.
fn: the function that runs when the form submits. React calls it with(previousState, formData). It can be sync or async, and whatever it returns becomes the newstate.initialState: whateverstateholds before the first submission.permalink(optional): a URL React can fall back to for progressive enhancement in frameworks that support server rendering before hydration finishes. This is a niche feature, most React developers will never set it by hand.state: the latest return value offn, orinitialStateif nothing's been submitted yet.formAction: pass this to<form action={formAction}>or a button'sformActionprop. Don't call it yourself.isPending:truewhile the action is running. This is React tracking a transition for you, not a flag you manage.
One thing worth knowing if you're reading older blog posts: this hook used to live in react-dom as useFormState during the React 19 canary releases. It moved to react and got renamed before the stable release, so anything referencing useFormState is talking about the same hook under its old name.
One naming note if you cross reference the official docs directly: React calls the function you pass in reducerAction, and the second return value dispatchAction, consistently, in the signature, the Parameters section, and every example, including the ones that use forms. I use fn and formAction throughout this tutorial instead, since those read more naturally once you're wiring things up for a form specifically, but that naming is this tutorial's own choice, not something the docs use.
If you're calling it manually rather than through a <form> or formAction prop, you also need to wrap the call in startTransition yourself, or React logs an error in development: "An async function with useActionState was called outside of a transition." Passing it to a <form action={...}> or button formAction handles this for you automatically, which is one more reason to prefer that path unless you have a specific reason not to.
If you'd rather have this signature and every gotcha on one scannable page while you code, the useActionState cheatsheet covers the same ground in reference form.
Plain React, no framework required:
No onSubmit, no manual preventDefault, no separate pending state. React wires all of it through formAction. I ran this exact component against React 19.2.7 in a test sandbox before publishing, both the validation-failure and success paths behave as shown.
Here's the one I see most often, including in my own early code: developers migrate from the old onSubmit pattern but keep their instinct to disable the button on click, instead of trusting isPending.
On a fast connection you'll never notice. On a slow one, a local flag can flip back before the real request resolves, letting a user queue up several more clicks than they meant to. Each one still runs, in order, since React queues calls rather than dropping or racing them, so a distracted user can end up with several duplicate actions processed one after another instead of one. isPending from useActionState is tied to React's actual pending state across the whole queue, not a flag you're guessing the timing of. Wire the disabled prop to it directly and the problem disappears:
The second version of this mistake: forgetting that fn's first argument is previousState, not the submit event. If you're used to onSubmit={(e) => ...}, it's an easy slip to write function subscribe(formData) and wonder why formData.get() throws. The signature is always (previousState, formData) for form-triggered submissions, in that order, no exceptions.
Multiple rapid submissions don't race the way you'd expect. React queues calls to the dispatch function and runs them sequentially, each one waits for the previous call to resolve before it starts, rather than firing concurrently. The official docs demonstrate this directly with a counter example: clicking an "Add" button four times in a row takes roughly four times as long to settle, not because of a bug, but because each queued call receives the result of the one before it. So the danger isn't a race to the database, it's that every click still counts. If a user taps "Add to cart" five times before realizing it's working, you get five items added, each one processed in order, not lost or overwritten. Disabling the control while isPending is true is still the right move, not to prevent a race condition, but to stop the user from queuing up actions they didn't mean to trigger.
One more queuing detail worth knowing: if an earlier queued call throws an error, React skips every call still waiting behind it in the queue. Catching errors inside your action function and returning an error state, instead of throwing, protects the rest of the queue as well as the current call.
Stale closures. If your action function reads from component-scoped variables, props, other state, instead of pulling fresh values from formData, you'll act on outdated data if the component re-renders between when the form opened and when it's submitted. Pull everything you need from formData.get(...), not from closure.
Uncaught async errors. If fn throws instead of returning an error state, React cancels every action still waiting in the queue and the error propagates up to the nearest error boundary, your form can disappear mid-interaction, along with any other queued clicks that hadn't run yet. Wrap the risky part in try/catch and return a structured error shape instead of letting it throw:
Validation errors don't clear themselves. state only updates when the action runs again. If a user fixes the invalid field but hasn't resubmitted yet, the old error message is still sitting there. If you want it to clear as they type, that's on you to wire up with a separate local state watching the input, useActionState won't do it automatically.
This is part of a bigger gap worth knowing about: useActionState has no built-in reset function at all, the official docs say so directly. If you need to clear the state programmatically, say, after a "start over" button, you have two documented options. Design your action function to handle a reset signal as one of its possible inputs:
Or give the component a key prop and change it to force a full remount, which wipes the state along with everything else local to that component. The reset-signal approach is usually less disruptive since it doesn't tear down the DOM.
Pending UI accessibility. Disabling the button isn't enough for screen reader users. Add aria-busy={isPending} to the form and consider disabling the inputs too, not just the submit button, so nothing looks interactive while a submission is actually in flight.
Calling the dispatch function during render. This one is easy to hit by accident if you call it directly in the component body instead of inside an event handler. Doing so schedules a state update, which triggers a re-render, which calls it again, an infinite loop. React's own docs flag this as a distinct error: "Cannot update action state while rendering." Only call the dispatch function in response to an actual event, a click, a submit, never unconditionally in the render path.
If you're about to ship something built on this hook, the build and review checklist walks through every one of these failure modes as a pre-merge pass.
Anything that isn't tied to a form or button action. Data fetching on mount, polling, background sync, all of that belongs to useEffect or a query library, not this hook. useActionState is specifically for actions the user triggers through a form.
When you need the UI to update before the server responds. useActionState waits for fn to resolve before state changes. If you want the UI to update instantly and roll back on failure, think: a like button, a todo checkbox, pair it with useOptimistic instead. useActionState alone will always feel a beat behind for that kind of interaction. Part 2 of this series covers the pairing directly.
Multi-step, fully controlled wizard forms. If you're managing input values across multiple steps that aren't all rendered at once, you need controlled inputs and your own state tree. useActionState is built around the uncontrolled, native-form submission model, and fighting that model for a step-by-step wizard usually creates more code than it saves.
Trivial forms with no async work. A local search filter or a client-only toggle doesn't need a transition-aware hook. Plain useState is fewer lines and easier to read.
A signup form with field-level validation, structured errors, and a pending state, close to what you'd actually ship:
I tested this component's logic directly too: both validation-error and success paths, including the case where both fields are invalid at once, return exactly the shape shown above.
The action runs inside a React transition, which means it doesn't block other urgent UI updates while it's pending, you can still type into an unrelated input while a form is submitting elsewhere on the page. Beyond that, there isn't much to optimize here specifically: don't put heavy synchronous computation inside fn on the client, and if you're in a full-stack framework, push real work into a server function instead of running it in the browser. The re-render triggered by a state update is scoped to the component that owns the hook, not the whole tree.
| Approach | Boilerplate | Needs JavaScript? | Works with Server Actions? | Supports optimistic UI? | Typical use case |
|---|---|---|---|---|---|
useState + manual handlers | High | Yes | Yes, manually wired | No, build it yourself | Full custom control, non-form async work |
useActionState | Low | Yes to run; forms can progressively enhance in frameworks that support it | Yes, this is the primary pattern | No, pair with useOptimistic | Form and button-triggered actions |
useFormStatus (imported from react-dom, not react) | N/A, reads status | Yes | Yes, reads the parent form's action | No | Child components inside a form that need pending status without prop drilling |
useOptimistic | Medium | Yes | Yes, pairs with useActionState | Yes, this is its purpose | Instant UI updates before the server confirms |
If your form submits data and waits for a result, useActionState is usually the right fit. If you need the UI to update the instant someone clicks, before any server response comes back, reach for useOptimistic instead. Knowing which situation you're in matters more than memorizing either API by heart.
Part 2 of the React 19 Deep Dive series covers useOptimistic, the hook to reach for when waiting for a server response makes the interaction feel slower than it should.
If you're working with Next.js, my Server Actions production guide and useOptimistic rollback pattern go deeper into how these hooks behave with Server Actions and the caching layer underneath them.
React: useActionState. The official React 19 reference for useActionState, including reset patterns, action queuing, manual dispatch with startTransition, and the upgrade from useFormState.
React: useFormStatus. The React 19 reference for useFormStatus, including the react-dom import requirement, pending states, and the complete status object available to forms.
React: useOptimistic. The React 19 reference for useOptimistic, including automatic rollback, optimistic UI patterns, and computing optimistic state with an update function.
Want to test what you just read? The 35-question interview set covers reasoning and edge cases beyond API recall, and the quiz is a faster, timed version of the same check.
Now you know when useActionState is the right choice, when to reach for useOptimistic instead, and the production mistakes that usually don't show up until real users start clicking.
