Most React applications deal with forms. Traditionally, we handle submissions with onSubmit.
React 19 added support for passing functions to a form’s action prop.
In this post, we’ll compare three approaches: plain onSubmit, action, and onSubmit with useTransition.
Throughout this post, we’ll use the following mock subscription API.
It simulates a one-second request and returns an error for test@example.com,
or success for any other email. All three form examples below refer to this same subscribe function.
async function subscribe(email: string) { await new Promise((resolve) => setTimeout(resolve, 1000)); if (email === "test@example.com") { return { success: false as const, error: "This email is already subscribed.", }; } return { success: true as const }; }
Handling form submissions with onSubmit
Let’s start with a newsletter subscription form using onSubmit:
import { useState } from "react"; export default function NewsletterForm() { const [isSubmitting, setIsSubmitting] = useState(false); const [error, setError] = useState(""); const [success, setSuccess] = useState(false); async function handleSubmit(event: React.FormEvent<HTMLFormElement>) { event.preventDefault(); const form = event.currentTarget; const formData = new FormData(form); const email = formData.get("email") as string; setIsSubmitting(true); setError(""); setSuccess(false); try { // Uses the mock subscribe() API defined above. const result = await subscribe(email); if (!result.success) { setError(result.error); return; } setSuccess(true); // Reset the form after a successful subscription. form.reset(); } catch { setError("Something went wrong. Please try again."); } finally { setIsSubmitting(false); } } return ( <form onSubmit={handleSubmit}> <input type="email" name="email" placeholder="Enter your email" required /> <button type="submit" disabled={isSubmitting}> {isSubmitting ? "Subscribing..." : "Subscribe"} </button> {error && <p role="alert">{error}</p>} {success && <p>Successfully subscribed!</p>} </form> ); }
Handling form submissions with action
Here is the same example written using the action prop:
import { useState } from "react"; import { useFormStatus } from "react-dom"; // Track submission status to disable the button and show progress. function SubmitButton() { const { pending } = useFormStatus(); return ( <button type="submit" disabled={pending}> {pending ? "Subscribing..." : "Subscribe"} </button> ); } // Show success or error messages, hiding them while submitting. function FormMessages({ error, success }: { error: string; success: boolean }) { const { pending } = useFormStatus(); if (pending) return null; return ( <> {error && <p role="alert">{error}</p>} {success && <p>Successfully subscribed!</p>} </> ); } export default function NewsletterForm() { const [error, setError] = useState(""); const [success, setSuccess] = useState(false); async function action(formData: FormData) { const email = formData.get("email") as string; setError(""); setSuccess(false); try { // Uses the mock subscribe() API defined above. const result = await subscribe(email); if (!result.success) { setError(result.error); return; } setSuccess(true); } catch { setError("Something went wrong. Please try again."); } } return ( <form action={action}> <input type="email" name="email" placeholder="Enter your email" required /> <SubmitButton /> <FormMessages error={error} success={success} /> </form> ); }
Comparing action prop with plain onSubmit
As you may notice there are some changes between the two examples. Let's go through what changes when we use action instead of onSubmit.
With action, we don't need event.preventDefault() - React handles the submission without triggering the browser's default navigation.
The action receives FormData directly, so we don't have to access event.currentTarget and construct it ourselves.
Automatic form reset
React resets uncontrolled fields when the action completes without throwing, eliminating the manual form.reset() call.
In our action example, since we handle the error without throwing, React clears the email field even when
the subscription fails. In the onSubmit example, we call form.reset() only after a successful subscription, so the email stays in the field when something goes wrong.
It is possible to preserve form values after action as explained here.
The gist is that we have to save the value in state and pass it as field's defaultValue and update the state when the action finishes.
For more options, see React’s documentation on other ways to control form resets.
Function passed to action runs in transition
Besides these, the main difference from plain onSubmit is that React runs the function passed to action inside a Transition
(following the action prop pattern).
This lets us use features that work with Transitions, such as optimistic updates and error boundaries.
useFormStatus and FormMessages
Notice that we also had to refactor the code a little to use useFormStatus for the loading indicator and to hide previous error or success messages while submitting using the FormMessages component.
State updates made synchronously inside the action are marked as Transition updates and can be deferred until the submission finishes. As a result, a manual loading flag may never appear during the request,
which is why we use useFormStatus for the loading indicator. For the same reason, an old error or success message can remain visible while the button says “Subscribing...”.
FormMessages uses that pending state to hide previous messages during submission.
Just a note: useFormStatus reads the status of a parent <form>, so we call it in components rendered inside the form.
Calling it in NewsletterForm itself would not track the form that component returns.
Handling form submissions with onSubmit and useTransition
As we said action prop runs the function passed to it inside a Transition. However, we can also start a Transition ourselves
by combining onSubmit with useTransition. This hook returns isPending to track pending work and startTransition to start the Transition:
import { useState, useTransition } from "react"; export default function NewsletterForm() { const [isPending, startTransition] = useTransition(); const [error, setError] = useState(""); const [success, setSuccess] = useState(false); function handleSubmit(event: React.FormEvent<HTMLFormElement>) { event.preventDefault(); const form = event.currentTarget; const formData = new FormData(form); const email = formData.get("email") as string; setError(""); setSuccess(false); startTransition(async () => { try { // Uses the mock subscribe() API defined above. const result = await subscribe(email); if (!result.success) { setError(result.error); return; } setSuccess(true); // Reset the form after a successful subscription. form.reset(); } catch { setError("Something went wrong. Please try again."); } }); } return ( <form onSubmit={handleSubmit}> <input type="email" name="email" placeholder="Enter your email" required /> <button type="submit" disabled={isPending}> {isPending ? "Subscribing..." : "Subscribe"} </button> {error && <p role="alert">{error}</p>} {success && <p>Successfully subscribed!</p>} </form> ); }
Here we clear the previous error and success messages before calling startTransition, so they disappear immediately
(they are not deferred as in the example with action prop so we don't use the FormMessages component).
We use isPending for the loading indicator and don't need useFormStatus in this example.
There is another difference now between using action prop and onSubmit with useTransition: progressive enhancement when working with Server Functions.
With onSubmit, our submission handler runs on the client, meaning JavaScript must be loaded and the component hydrated before the handler can execute.
On the other hand, when we pass a Server Function to the action prop, React can support form submissions even before JavaScript has loaded.
This is something that onSubmit combined with startTransition cannot provide.
Comparing all three approaches
| Behavior | Plain |
| Function passed to |
|---|---|---|---|
| Prevent browser navigation | Call | Call | Automatic |
| Obtain submitted values | Construct | Construct | Receives |
| Runs in a Transition | Requires a Transition | Yes, through | Automatic |
| Show a loading indicator during submission | Manage a loading flag yourself | Read | Read |
| Hide previous error or success messages when submitting again | Clear message state at the start of the handler | Clear message state before calling | Hide messages while |
| Reset uncontrolled fields | Call | Call | Automatic when the action completes without throwing. |
Optimistic updates with | Requires a Transition | Supported inside the Transition | Supported inside the action |
| Uncaught async errors reach an Error Boundary | Requires a Transition | Yes, from the Transition | Yes, from the action |
| Progressive enhancement with a Server Function | Client handler requires JavaScript | Client handler requires JavaScript | Supported in a compatible framework |
Next: useActionState
There is also another option of working with the forms which works with the action prop: useActionState.
It returns the action's result as state and exposes an isPending flag, so we don't need separate useState
calls or a useFormStatus child component. This is a topic maybe for another post.
Notes
These examples use uncontrolled inputs, so their values are not stored in React state. All three approaches also work with controlled inputs.
With controlled inputs, we would manage the email with value and onChange, could read it from state instead of FormData, and would clear it
with setEmail("") rather than form.reset() or the automatic reset from action. Automatic resets only apply to uncontrolled fields;
the pending-state and Transition behavior discussed above stays the same.