Form actions

A form that calls a function

In Forms and inputs, every form that sent anything had an onSubmit handler that stopped the page from loading, built a FormData, and read it. React 19 can do that part for you. Give the form a function as its action, and React calls it with the form's data. Type a tea in the result and press Add:

1import { useState } from "react";2 3export default function App() {4  const [order, setOrder] = useState(["Chai"]);5 6  function addTea(formData) {7    setOrder([...order, formData.get("tea")]);8  }9 10  return (11    <form action={addTea}>12      <label>13        Tea <input name="tea" required />14      </label>15      <button>Add</button>16      <p>Your order: {order.join(", ")}</p>17    </form>18  );19}

Line 11 passes addTea to the form's action, where plain HTML would have a web address. When you press Add, React calls addTea (lines 6 to 8) with a FormData holding every named field, so line 7 reads the tea with formData.get("tea") and adds it to the order. Type Mint and press Add: line 16 says Your order: Chai, Mint, and the box is empty again.

There's no e.preventDefault(), no new FormData, and no line that empties the box. React did all three:

A function passed to a form this way is called an action. It can be async, it can wait for a server, and React keeps track of it while it runs. That tracking is what the rest of this lesson builds on: showing the server's answer, showing that the form is busy, and knowing when React empties the form.

What React does when the form is submitted

Here is the same order form written the way the last lesson did, with onSubmit. Type Mint and press Add:

1import { useState } from "react";2 3export default function App() {4  const [order, setOrder] = useState(["Chai"]);5 6  function handleSubmit(e) {7    e.preventDefault();8    const formData = new FormData(e.currentTarget);9    setOrder([...order, formData.get("tea")]);10  }11 12  return (13    <form onSubmit={handleSubmit}>14      <label>15        Tea <input name="tea" required />16      </label>17      <button>Add</button>18      <p>Your order: {order.join(", ")}</p>19    </form>20  );21}

The order grows the same way, but Mint stays in the box: nothing here resets the form. Lines 7 and 8 are the two jobs the action version left to React. Both ways work in React 19, and onSubmit with preventDefault is what you'll see in most code written before it.

How to read the table: each row asks one question about sending a form, answered for each way.

React runs an action inside a Transition: a group of updates React may take its time over, and which it marks as pending until it finishes. You don't call anything to start one; a function in action gets one for free. The Transitions lesson covers them in depth. The form actions, useActionState, and useFormStatus in this lesson all arrived in React 19, the version these examples run (19.3.1); the React 19 entry in React's changelog lists them.

A second button with its own action

A button can override the form's action with formAction. Then each button does its own thing with the same fields. Type 3 in the box, press Add to cart, then Save for later:

1import { useState } from "react";2 3export default function App() {4  const [cart, setCart] = useState(0);5  const [saved, setSaved] = useState(0);6 7  function addToCart(formData) {8    setCart(cart + Number(formData.get("packs")));9  }10 11  function saveForLater(formData) {12    setSaved(saved + Number(formData.get("packs")));13  }14 15  return (16    <form action={addToCart}>17      <label>18        Packs of chai <input name="packs" type="number" min="1" defaultValue="1" />19      </label>20      <button>Add to cart</button>21      <button formAction={saveForLater}>Save for later</button>22      <p>In cart: {cart}. Saved for later: {saved}.</p>23    </form>24  );25}

Line 16 makes addToCart the form's action, and line 21 gives the Save for later button formAction={saveForLater}. Line 20's button has none, so it uses the form's. After Add to cart with 3, line 22 says In cart: 3. Saved for later: 0., and the box is back to 1, its defaultValue. Save for later adds the 1: Saved for later: 1. Both functions are actions, so both reset the form when they finish. Don't give a button with a function formAction a name; React needs that spot for itself and warns.

useActionState: the server's answer and the wait

Real forms send their data to a server and wait. Here the server is pretend: the api.js tab answers after one second, and says no to an email that's already on the list. An action can simply await it. Type mint@example.com and press Join:

1import { joinWaitlist } from "./api.js";2 3export default function App() {4  async function join(formData) {5    await joinWaitlist(formData.get("email"));6  }7 8  return (9    <form action={join}>10      <label>11        Email <input name="email" type="email" required />12      </label>13      <button>Join the waitlist</button>14    </form>15  );16}

Line 5 waits for the server. For a second nothing seems to happen, then the box empties. Did it work? Try asha@example.com, who is already on the list: the same thing happens, and the server's "already on the list" is lost. The form needs two more things: a place for the server's answer, and a way to show that it's waiting. useActionState gives both:

1import { useActionState } from "react";2import { joinWaitlist } from "./api.js";3 4async function join(previousState, formData) {5  const email = formData.get("email");6  const result = await joinWaitlist(email);7  if (!result.ok) return result.error;8  return `Thanks! ${email} is on the list.`;9}10 11export default function App() {12  const [message, formAction, isPending] = useActionState(join, "");13 14  return (15    <form action={formAction}>16      <label>17        Email <input name="email" type="email" required />18      </label>19      <button disabled={isPending}>{isPending ? "Joining…" : "Join the waitlist"}</button>20      <p>{message}</p>21    </form>22  );23}

Line 12 calls useActionState(join, ""): your action, and the state to start with. It returns three things, named here with array destructuring:

• message, the state: "" at first, then whatever join last returned. Line 20 shows it.
• formAction, a new function to give the form instead of join. Line 15 does. When the form is submitted, it calls join for you.
• isPending, true while join runs. Line 19 turns the button off and says Joining….

join itself (lines 4 to 9) changes in one way: it now takes the previous state first and the FormData second. Whatever it returns becomes the new state, like a reducer that's allowed to wait for a server. Join with mint@example.com and the page says Thanks! mint@example.com is on the list. Join with asha@example.com and line 7 returns the server's error instead: asha@example.com is already on the list.

The names are yours to pick. react.dev calls the three state, dispatchAction, and isPending, and your function a reducer action; the React 19 announcement calls them error, submitAction, and isPending. Early previews of React 19 had this Hook in react-dom as useFormState; that name is deprecated. Watch one submit step by step:

1import { useActionState } from "react";2import { joinWaitlist } from "./api.js";3 4async function join(previousState, formData) {5  const email = formData.get("email");6  const result = await joinWaitlist(email);7  if (!result.ok) return result.error;8  return `Thanks! ${email} is on the list.`;9}10 11export default function App() {12  const [message, formAction, isPending] = useActionState(join, "");13 14  return (15    <form action={formAction}>16      <label>17        Email <input name="email" type="email" required />18      </label>19      <button disabled={isPending}>{isPending ? "Joining…" : "Join the waitlist"}</button>20      <p>{message}</p>21    </form>22  );23}

With the button Off while waiting, the log shows join starting, isPending turning true, the server answering a second later, and then one update: isPending false, the new message, and an empty box. With Always on, press Join twice: the second call starts only after the first has answered, and its previousState is the first call's answer. React queues the calls, because each one needs the state the one before it returned. That's usually a reason to turn the button off while isPending is true.

useFormStatus: a button that knows its form is busy

isPending lives in the component that renders the form. A submit button you reuse in many forms can't reach it without a prop. useFormStatus, from react-dom, lets a component inside a form ask that form directly. Type an email in the first form and press its button:

1import { useFormStatus } from "react-dom";2import { joinWaitlist } from "./api.js";3 4function SubmitButton({ children }) {5  const { pending, data } = useFormStatus();6  return (7    <button disabled={pending}>8      {pending ? `Sending ${data.get("email")}…` : children}9    </button>10  );11}12 13async function join(formData) {14  await joinWaitlist(formData.get("email"));15}16 17export default function App() {18  return (19    <>20      <form action={join}>21        <input name="email" type="email" aria-label="Email for the waitlist" required />22        <SubmitButton>Join the waitlist</SubmitButton>23      </form>24      <form action={join}>25        <input name="email" type="email" aria-label="Email for tasting invites" required />26        <SubmitButton>Get tasting invites</SubmitButton>27      </form>28    </>29  );30}

Line 5 asks for the status of the form around SubmitButton. It returns an object with four properties:

• pending: true while that form's action runs.
• data: the FormData being sent, or null when nothing is. Line 8 reads the email from it.
• method and action: the form's method and its action function, which you'll rarely need.

Join with mint@example.com: the first button turns off and says Sending mint@example.com…, while the second still says Get tasting invites. Each SubmitButton only follows the form it sits in (lines 20 to 27), and the forms need no props for it.

The form must be above the component that calls useFormStatus. A component that renders the form itself gets nothing. Press Join here:

1import { useFormStatus } from "react-dom";2import { joinWaitlist } from "./api.js";3 4async function join(formData) {5  await joinWaitlist(formData.get("email"));6}7 8function StatusLine() {9  const { pending } = useFormStatus();10  return <p>StatusLine, inside the form: {pending ? "sending…" : "ready"}</p>;11}12 13export default function App() {14  const { pending } = useFormStatus();15  return (16    <form action={join}>17      <input name="email" type="email" aria-label="Email" required />18      <button>Join</button>19      <StatusLine />20      <p>App, which renders the form: {pending ? "sending…" : "ready"}</p>21    </form>22  );23}

While join waits, StatusLine says sending…: it calls useFormStatus on line 9 and is rendered inside the form on line 19. App's line stays ready, because App calls it on line 14 and there's no form above App; the form is something App renders below itself.

How to read the table: each row asks one question, answered for each Hook.

When React empties the form

Every action form so far emptied its boxes on its own. React resets a form after its action, and the exact rule matters, because it surprises people. Look back at the waitlist: join with asha@example.com and the box is empty when the error appears. The person has to type the email again to fix it.

Three facts explain it:

1. When: React resets the form when the action finishes, not when you press the button. The text stays while the action runs, and the reset arrives in the same update as the new state.
2. Whatever it returns: React doesn't read your result. Any action that finishes without throwing counts as done, even one that returns an error message.
3. What it resets: React calls the browser's form.reset(), which puts each field back to its default value. A controlled field still shows your state afterwards, because the reset doesn't change state.

The fix for the lost email uses the first fact. React updates every field's defaultValue first and resets the form after, so you can send the typed value back in the state and make it the default:

1import { useActionState } from "react";2import { joinWaitlist } from "./api.js";3 4async function join(previousState, formData) {5  const email = formData.get("email");6  const result = await joinWaitlist(email);7  if (!result.ok) return { message: result.error, email };8  return { message: `Thanks! ${email} is on the list.`, email: "" };9}10 11export default function App() {12  const [state, formAction, isPending] = useActionState(join, { message: "", email: "" });13 14  return (15    <form action={formAction}>16      <label>17        Email <input name="email" type="email" defaultValue={state.email} required />18      </label>19      <button disabled={isPending}>{isPending ? "Joining…" : "Join the waitlist"}</button>20      <p>{state.message}</p>21    </form>22  );23}

The state is now an object. On an error, line 7 returns the message and the email; on success, line 8 returns an empty email. Line 17 uses state.email as the box's defaultValue. Join with asha@example.com: the error appears, and the box still holds asha@example.com, ready to fix. Join with mint@example.com: the thanks appear, and the box is empty.

Try every combination: what the server says, and whether the email box gets its value back.

1import { useActionState, useState } from "react";2 3async function save(previousState, formData) {4  const email = formData.get("email");5  await new Promise((resolve) => setTimeout(resolve, 800));6  return { message: `${email} is already on the list.`, email };7}8 9export default function App() {10  const [name, setName] = useState("Asha");11  const [state, formAction] = useActionState(save, { message: "", email: "" });12  return (13    <form action={formAction}>14      <input name="name" aria-label="Name" value={name} onChange={(e) => setName(e.target.value)} />15      <input name="email" aria-label="Email" />16      <button>Save</button>17      <p>{state.message}</p>18    </form>19  );20}

How to read the table: each row is something that happened, whether React resets the form, and why.

// A form action was provided. Prevent native navigation.
event.preventDefault();

// Dispatch the action and set a pending form status.
const formData = new FormData(form, submitter);
const pendingState: FormStatus = {
  pending: true,
  data: formData,
  method: form.method,
  action: action,
};
startHostTransition(formInst, pendingState, action, formData);

: () => {
    // Automatically reset the form when the action completes.
    requestFormReset(formFiber);
    return action(formData);
  },

if (needsFormReset) {
  // A form component requested to be reset during this commit. We do this
  // after all mutations in the rest of the tree so that `defaultValue`
  // will already be updated. This way you can update `defaultValue` using
  // data sent by the server as a result of the form submission.
  needsFormReset = false;
  recursivelyResetForms(finishedWork);
}

Menus don't follow a new defaultValue

One kind of field breaks the defaultValue trick: a <select>. React reads a menu's defaultValue only when the menu first appears, so after a reset the menu goes back to its first default. Pick Large and press Choose:

1import { useActionState } from "react";2 3function pick(previousState, formData) {4  return formData.get("size");5}6 7export default function App() {8  const [size, formAction] = useActionState(pick, "small");9 10  return (11    <form action={formAction}>12      <select name="size" aria-label="Size" defaultValue={size}>13        <option value="small">Small</option>14        <option value="large">Large</option>15      </select>16      <button>Choose</button>17      <p>You chose: {size}</p>18    </form>19  );20}

The state says large, and line 17 shows You chose: large, but the menu on line 12 shows Small again. Press Edit & run and add key={size} to the <select>: a new key gives React a new menu, which reads defaultValue again (the Preserving and resetting state lesson explains keys). Radio buttons don't have this problem: React updates defaultChecked on every render, as the review form below relies on.

Resetting by hand with requestFormReset

A form with onSubmit is never reset by React. When you want React's reset there, react-dom has requestFormReset(form). It asks for the same reset an action gets, so it must be called inside a Transition, and the reset happens when that Transition finishes. react.dev has no reference page for it yet; the React 19 changelog announces it next to form actions. Here a booking form checks the number first, and only books, and resets, when it's fine:

1import { startTransition, useState } from "react";2import { requestFormReset } from "react-dom";3import { bookSeats } from "./api.js";4 5export default function App() {6  const [error, setError] = useState("");7 8  function handleSubmit(e) {9    e.preventDefault();10    const form = e.currentTarget;11    const seats = Number(new FormData(form).get("seats"));12    if (seats > 4) {13      setError("You can book up to 4 seats.");14      return;15    }16    setError("");17    startTransition(async () => {18      requestFormReset(form);19      await bookSeats(seats);20    });21  }22 23  return (24    <form onSubmit={handleSubmit}>25      <label>26        Seats at the tasting <input name="seats" type="number" min="1" defaultValue="2" />27      </label>28      <button>Book</button>29      <p>{error}</p>30    </form>31  );32}

Lines 12 to 15 stop at a number over 4, before any Transition starts: type 6 and press Book, and the error shows while the box keeps your 6. For 3, line 17 starts a Transition with startTransition from react, line 18 asks for the reset, and line 19 waits for the server. The box keeps the 3 while it waits, then goes back to its default, 2, when bookSeats answers. Calling the browser's form.reset() instead would empty it at once, before the booking is done.

When an action fails

Actions fail in two ways, and each gets its own treatment:

• Errors you expect, like an email already on the list or a comment that's too short. Return them as part of the state and show them next to the fields, as the waitlist does. The form stays usable.
• Errors you don't expect, like a server that's down or a bug in your code. Let them throw. React stops the action and shows the closest error boundary: a component that shows something else when a part of the page fails.

Here the action always throws. The ErrorBoundary.jsx tab is ready-made; the Error boundaries lesson shows how to write one. Press Order and wait a second:

1import ErrorBoundary from "./ErrorBoundary.jsx";2 3async function sendOrder(formData) {4  await new Promise((resolve) => setTimeout(resolve, 1000));5  throw new Error("The tea shop's server is down.");6}7 8export default function App() {9  return (10    <ErrorBoundary>11      <form action={sendOrder}>12        <label>13          Tea <input name="tea" defaultValue="Chai" />14        </label>15        <button>Order</button>16      </form>17    </ErrorBoundary>18  );19}

Line 5 throws after the wait. React stops the action and line 10's ErrorBoundary replaces the form with Something went wrong: The tea shop's server is down. The console under the result shows the error React reported. Without a boundary, React removes the whole app: press Edit & run, delete lines 10 and 17, and press Order. The result is replaced by the error itself.

A thrown error also cancels any submits still waiting in the queue, so for anything you can foresee, return a message instead. And check simple things in the action before calling the server at all: returning early is fast and needs no network, as the review form below does. The browser's own checks still work too: a required field stops the submit before your action runs.

A product review form

Here is everything together: an action that checks the fields and returns errors, sends the review when it's fine, keeps what people typed after an error, and a reusable button that knows when the form is busy. Press Post review with nothing filled in first.

1import { useActionState } from "react";2import { useFormStatus } from "react-dom";3import { saveReview } from "./api.js";4 5const blank = { errors: {}, values: { name: "", rating: "5", comment: "" }, saved: "" };6 7async function postReview(previousState, formData) {8  const values = Object.fromEntries(formData);9  const errors = {};10  if (values.name.trim() === "") errors.name = "Tell us your name.";11  if (values.comment.trim().length < 10) errors.comment = "Write at least 10 characters.";12  if (Object.keys(errors).length > 0) return { errors, values, saved: "" };13  await saveReview(values);14  return { ...blank, saved: `Thanks, ${values.name}! Your ${values.rating}-star review is up.` };15}16 17function SubmitButton() {18  const { pending } = useFormStatus();19  return <button disabled={pending}>{pending ? "Posting…" : "Post review"}</button>;20}21 22export default function App() {23  const [state, formAction] = useActionState(postReview, blank);24  const { errors, values } = state;25 26  return (27    <form action={formAction} noValidate>28      {state.saved && <p>{state.saved}</p>}29      <label htmlFor="name">Name</label>30      <input id="name" name="name" defaultValue={values.name}31        aria-invalid={Boolean(errors.name)} aria-describedby="name-error" />32      <p id="name-error" className="error">{errors.name}</p>33      <fieldset>34        <legend>Rating</legend>35        {["5", "4", "3"].map((stars) => (36          <label key={stars}>37            <input type="radio" name="rating" value={stars} defaultChecked={values.rating === stars} /> {stars} stars38          </label>39        ))}40      </fieldset>41      <label htmlFor="comment">Comment</label>42      <textarea id="comment" name="comment" defaultValue={values.comment}43        aria-invalid={Boolean(errors.comment)} aria-describedby="comment-error" />44      <p id="comment-error" className="error">{errors.comment}</p>45      <SubmitButton />46    </form>47  );48}

postReview (lines 7 to 15) turns the FormData into a plain object with Object.fromEntries on line 8, and checks it. With errors, line 12 returns them together with the values, without calling the server. Lines 30, 37, and 42 use those values as defaults, so after the reset each field shows what was typed, and the radio button you picked stays picked. aria-invalid and aria-describedby on lines 31 and 43 point a screen reader at each message, as in Forms and inputs.

Fill in Asha, pick 3 stars, write short, and press Post review: only the comment's error shows, and your name, rating, and comment are all still there. Write Smooth and malty. and post again. SubmitButton (lines 17 to 20) says Posting… for a second, then line 14 returns the blank state with a thank-you, and line 28 says Thanks, Asha! Your 3-star review is up. The fields go back to blank and 5 stars.

Common mix-ups

• "An action still needs e.preventDefault()." No. An action never gets the event; React stops the page load itself.
• "With useActionState, the FormData is the action's first argument." No. The previous state comes first, the FormData second.
• "useFormStatus works in the component that renders the form." No. It reads the form above the component that calls it, so put it in a child, like a submit button.
• "useFormStatus comes from react." No. It comes from react-dom; useActionState comes from react.
• "React only resets the form when the action succeeds." Not in the way most people mean. It resets after any action that finishes without throwing, including one that returns an error message.
• "The form resets as soon as you press submit." No. The fields keep their text while the action runs, and the reset comes with the new state.

Practice exercises

Each exercise shows its code's result, or shows it when you press Edit & run. The slow ones import the same pretend server, in the api.js tab. Try a guess first, then use the hints.

1import { useState } from "react";2 3export default function App() {4  const [notes, setNotes] = useState([]);5 6  function handleSubmit(e) {7    e.preventDefault();8    const formData = new FormData(e.currentTarget);9    setNotes([...notes, formData.get("note")]);10  }11 12  return (13    <form onSubmit={handleSubmit}>14      <input name="note" aria-label="Tasting note" required />15      <button>Add note</button>16      <ul>17        {notes.map((note, index) => (18          <li key={index}>{note}</li>19        ))}20      </ul>21    </form>22  );23}

1import { useState } from "react";2 3export default function App() {4  const [notes, setNotes] = useState([]);5 6  function addNote(formData) {7    setNotes([...notes, formData.get("note")]);8  }9 10  return (11    <form action={addNote}>12      <input name="note" aria-label="Tasting note" required />13      <button>Add note</button>14      <ul>15        {notes.map((note, index) => (16          <li key={index}>{note}</li>17        ))}18      </ul>19    </form>20  );21}

1import { useFormStatus } from "react-dom";2import { joinWaitlist } from "./api.js";3 4async function join(formData) {5  await joinWaitlist(formData.get("email"));6}7 8export default function App() {9  const { pending } = useFormStatus();10  return (11    <form action={join}>12      <input name="email" type="email" aria-label="Email" required />13      <button disabled={pending}>{pending ? "Sending…" : "Send"}</button>14    </form>15  );16}

1import { useFormStatus } from "react-dom";2import { joinWaitlist } from "./api.js";3 4async function join(formData) {5  await joinWaitlist(formData.get("email"));6}7 8function SendButton() {9  const { pending } = useFormStatus();10  return <button disabled={pending}>{pending ? "Sending…" : "Send"}</button>;11}12 13export default function App() {14  return (15    <form action={join}>16      <input name="email" type="email" aria-label="Email" required />17      <SendButton />18    </form>19  );20}

1import { joinWaitlist } from "./api.js";2 3export default function App() {4  async function join(formData) {5    await joinWaitlist(formData.get("email"));6  }7 8  return (9    <form action={join}>10      <label>11        Email <input name="email" type="email" required />12      </label>13      <button>Join the waitlist</button>14    </form>15  );16}

1import { useActionState } from "react";2import { joinWaitlist } from "./api.js";3 4async function join(previousState, formData) {5  const email = formData.get("email");6  const result = await joinWaitlist(email);7  return result.ok ? `Thanks! ${email} is on the list.` : result.error;8}9 10export default function App() {11  const [message, formAction] = useActionState(join, "");12 13  return (14    <form action={formAction}>15      <label>16        Email <input name="email" type="email" required />17      </label>18      <button>Join the waitlist</button>19      <p>{message}</p>20    </form>21  );22}

1import { useActionState } from "react";2import { joinWaitlist } from "./api.js";3 4async function join(previousState, formData) {5  const email = formData.get("email");6  const result = await joinWaitlist(email);7  if (!result.ok) return result.error;8  return `Thanks! ${email} is on the list.`;9}10 11export default function App() {12  const [message, formAction, isPending] = useActionState(join, "");13 14  return (15    <form action={formAction}>16      <label>17        Email <input name="email" type="email" required />18      </label>19      <button disabled={isPending}>{isPending ? "Joining…" : "Join the waitlist"}</button>20      <p>{message}</p>21    </form>22  );23}

1import { useActionState } from "react";2import { joinWaitlist } from "./api.js";3 4async function join(previousState, formData) {5  const email = formData.get("email");6  const result = await joinWaitlist(email);7  if (!result.ok) return { message: result.error, email };8  return { message: `Thanks! ${email} is on the list.`, email: "" };9}10 11export default function App() {12  const [state, formAction, isPending] = useActionState(join, { message: "", email: "" });13 14  return (15    <form action={formAction}>16      <label>17        Email <input name="email" type="email" defaultValue={state.email} required />18      </label>19      <button disabled={isPending}>{isPending ? "Joining…" : "Join the waitlist"}</button>20      <p>{state.message}</p>21    </form>22  );23}

1import { useState } from "react";2 3export default function App() {4  const [status, setStatus] = useState("Nothing yet.");5 6  function publish(formData) {7    setStatus(`Published: ${formData.get("review")}`);8  }9 10  return (11    <form action={publish}>12      <textarea name="review" aria-label="Your review" defaultValue="Great chai" />13      <button>Publish</button>14      <p>{status}</p>15    </form>16  );17}

1import { useState } from "react";2 3export default function App() {4  const [status, setStatus] = useState("Nothing yet.");5 6  function publish(formData) {7    setStatus(`Published: ${formData.get("review")}`);8  }9 10  function saveDraft(formData) {11    setStatus(`Draft saved: ${formData.get("review")}`);12  }13 14  return (15    <form action={publish}>16      <textarea name="review" aria-label="Your review" defaultValue="Great chai" />17      <button>Publish</button>18      <button formAction={saveDraft}>Save draft</button>19      <p>{status}</p>20    </form>21  );22}

1import { useActionState } from "react";2 3async function saveCups(previousState, formData) {4  const cups = Number(formData.get("cups"));5  return `Saved: ${cups} cups a day.`;6}7 8export default function App() {9  const [message, formAction] = useActionState(saveCups, "");10 11  return (12    <form action={formAction}>13      <label>14        Cups a day <input name="cups" defaultValue="3" />15      </label>16      <button>Save</button>17      <p>{message}</p>18    </form>19  );20}

1import { useActionState } from "react";2 3async function saveCups(previousState, formData) {4  const cups = Number(formData.get("cups"));5  if (!Number.isInteger(cups) || cups < 0) return "Enter a whole number of cups.";6  return `Saved: ${cups} cups a day.`;7}8 9export default function App() {10  const [message, formAction] = useActionState(saveCups, "");11 12  return (13    <form action={formAction}>14      <label>15        Cups a day <input name="cups" defaultValue="3" />16      </label>17      <button>Save</button>18      <p>{message}</p>19    </form>20  );21}

Check your understanding

For each code question, find which function React calls and with what, then follow its result to the screen. Press Edit & run on a question's code to check your answer.

Key takeaways

• Pass a function to a form's action, and React stops the page load, calls it with the form's FormData, and runs it in a Transition. A button's formAction overrides it for that button.
• useActionState(action, initialState) returns [state, formAction, isPending]. The action gets (previousState, formData), and what it returns becomes the state. Calls queue, one after another.
• useFormStatus(), from react-dom, gives a component inside a form pending and data for that form. It sees nothing in the component that renders the form.
• React resets the form when the action finishes without throwing, whatever it returns, in the same update as the new state. Controlled fields keep your state; send typed values back as defaultValue to keep them after an error.
• Return expected errors as state. Let unexpected ones throw to an error boundary. requestFormReset(form) asks for the reset yourself, inside a Transition.

Coming next: Optimistic updates. With useOptimistic, the page shows the result of an action before the server confirms it, and rolls back if it fails.