Enhance form documentation for form default reset behavior by MaxwellCohen · Pull Request #8512 · reactjs/react.dev

MaxwellCohen · 2026-06-29T16:06:26Z

Summary

Documents React’s default form-reset behavior when using the function action / formAction props, and explains how to preserve field values when you don’t want that reset. Applying @rickhanlonii's feedback from #7795 and building off of work @aurorascharff recentlly did.

Adds default reset behavior in Caveats, the action prop section, and a new Troubleshooting entry (“Why does my form reset when I use an action?”). React resets uncontrolled fields after a successful action, matching browser <form action="..."> behavior (including before JS loads).
Adds “Preserve form values after submission” with a Sandpack example: call e.preventDefault() in onSubmit, then run the action manually inside useTransition while keeping the action prop for progressive enhancement.
Adds a DeepDive for finer control: requestFormReset from react-dom, and returning submitted FormData from server actions to restore values via defaultValue (with useActionState).
Updates the multiple-submission-types example to a draft/publish scenario that shows how controlled state and key/defaultValue keep textarea content after “Save draft.”

Closes #8397

Alternative to #7795 and #8465

github-actions · 2026-06-29T16:08:45Z

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

aurorascharff · 2026-06-30T23:51:54Z

Going to dig a bit into the current behavior of this, so might take some time to review! Thank you!

…ction` prop and its behavior: - including the handling of `FormData`, - the necessity of `name` attributes, - the advantages of using a function over a URL. - removed redundant information about `e.preventDefault()` for the `action` prop.

aurorascharff · 2026-07-05T19:11:40Z

+Give each input a `name` attribute so its value is included in `FormData`. You can use [uncontrolled](/reference/react-dom/components/input#reading-the-input-values-when-submitting-a-form) inputs instead of controlled `value`/`onChange` pairs, and you don't need an `onSubmit` handler or `e.preventDefault()`.

-Pass a function to the `action` prop of form to run the function when the form is submitted. [`formData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) will be passed to the function as an argument so you can access the data submitted by the form. This differs from the conventional [HTML action](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#action), which only accepts URLs. Unlike `onSubmit`, an `action` runs in a [Transition](/reference/react/useTransition) and calling `e.preventDefault()` isn't needed. After the `action` function succeeds, all uncontrolled field elements in the form are reset.
+This extends the [HTML `action` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#action), which only accepts a URL, to also accept a function. Because the form stays a native HTML form, it can be submitted before JavaScript loads; with a [Server Function](/reference/rsc/server-functions), it works without JavaScript enabled.


ecause the form stays a native HTML form, it can be submitted before JavaScript loads; with a [Server Function](/reference/rsc/server-functions), it works without JavaScript enabled

this part is a bit unclear and hard to parse!

Great point. When I read it 3 times last week, it seemed so clear ;) now it is not

udpate in b341728

I feel you on that 😂

aurorascharff · 2026-07-05T19:13:00Z

+
+* Runs the submission function in a [Transition](/reference/react/useTransition).
+* Tracks pending state so child components can read it with [`useFormStatus`](/reference/react-dom/hooks/useFormStatus).
+* Sends thrown errors to the nearest error boundary.


Not sure if "sends" is the right terminology for this 🤔

Good point! I will reword!

see b341728

aurorascharff · 2026-07-05T19:13:35Z

+* Runs the submission function in a [Transition](/reference/react/useTransition).
+* Tracks pending state so child components can read it with [`useFormStatus`](/reference/react-dom/hooks/useFormStatus).
+* Sends thrown errors to the nearest error boundary.
+* Works with [`useActionState`](/reference/react/useActionState) and [`useOptimistic`](/reference/react/useOptimistic) for form state and optimistic UI.


This bullet seems out of place in its framing, since the intro to the list is When you pass a function to action, React: but here "works" is not answering that question!

is b341728 better

aurorascharff · 2026-07-05T19:15:42Z

-### Display a pending state during form submission {/*display-a-pending-state-during-form-submission*/}
+### Preserving form values after submission {/*preserve-form-values-after-submission*/}
+
+The browser clears a form's input state on submit. A URL `action` follows this same behavior. React does the same when `action` is a function, so your form works consistently before and after JavaScript loads.


this paragraph reads a little strange, and the behavior was explained better above!

is 4f39d4b better?

aurorascharff · 2026-07-05T19:16:44Z

+
+</Sandpack>
+
+Because you call the action manually from `onSubmit`, [`useFormStatus`](/reference/react-dom/hooks/useFormStatus) won't report its pending state. Read `isPending` from the same [`useTransition`](/reference/react/useTransition) call instead.


Hm, i thought useFormStatus worked regardless, also with onSubmit?

yep, I got just using onSubmit without action confused

aurorascharff · 2026-07-05T19:22:29Z

-When a user taps a specific button, the form is submitted, and a corresponding action, defined by that button's attributes and action, is executed. For instance, a form might submit an article for review by default but have a separate button with `formAction` set to save the article as a draft.
+When a button without `formAction` submits the form, React calls the form's `action`. When a button with `formAction` submits the form, React calls that button's action instead. For example, the form below publishes an article by default, but its **Save draft** button stores the current content without publishing it.
+
+In this example the draft is held in state, so the saved content stays in the textarea after you submit it. In a real app you would persist the draft on the server. Pass a [Server Function](/reference/rsc/server-functions) (a function marked with [`'use server'`](/reference/rsc/use-server)) to `formAction` to save the draft from the server, optionally combined with [`useActionState`](/reference/react/useActionState) to track its pending state and result.


(a function marked with 'use server')

is this a common pattern in the docs?

Most of the examples are called out in the code update it in code, so moving to code and using useActionState
947c926

To be clear, sorry if this was too biref, i was wondering about the usage of the () inline linking of in that way!!

But i think its better the way you did it regardless

aurorascharff · 2026-07-05T19:25:29Z

+function EditForm() {
+  // The action returns { submitted: formData, error } on failure
+  const [state, formAction] = useActionState(submitForm, {});
+  const values = state.submitted ?? new FormData();


Why do we need a seperate variable for values? Is this pattern better than returning the values from the useActionState function?

https://aurorascharff.no/posts/handling-form-validation-errors-and-resets-with-useactionstate/
https://www.robinwieruch.de/react-server-action-reset-form/

Good point, I forgot about optional chaining (one of my favorite JS features when working on making the examples)

hernan-yadiel · 2026-07-06T15:10:27Z

 export default function Search() {
  function handleSubmit(e) {
-    // Prevent the browser from reloading the page
-    e.preventDefault();


Why was this e.preventDefault() removed? 🤔

I removed e.preventDefault() to show that, by default, forms reset their values. My goal is to progressively disclose the behavior of forms. React extends HTML form behavior with the onSubmit and action props, not replaces it. I think this is the brilliance of React 19 form APIs.

React is at its best when it takes something that was hard, such as updating content on the page or building reusable components, and makes it easy (sometimes too easy with useEffect 😉 ). I see the form APIs as the next step of this.

If it is unclear, or better to have it, I am open to suggestions.

hernan-yadiel · 2026-07-06T15:28:40Z

+
+When you pass a function to `action` or `formAction`, React resets the form's [uncontrolled fields](/reference/react-dom/components/input#reading-the-input-values-when-submitting-a-form) after the action succeeds. This reset only affects uncontrolled fields—[inputs controlled with state](/reference/react-dom/components/input#controlling-an-input-with-a-state-variable) are never cleared.
+
+To preserve the values of uncontrolled fields after submission, add an `onSubmit` handler that calls `e.preventDefault()` and runs the action inside a [Transition](/reference/react/useTransition). Keep the `action` prop on the form so it continues to work before JavaScript loads.


I just tried this and it calls both: the submitForm action and the handleSubmit function.

If we want the form to progressively enhance and at the same time preserving values after submission, I believe the right answer is useActionState.

"use client"; import { useActionState } from "react"; import { someServerFunction } from "./some-server-function"; export default function EditForm() { const [state, dispatchAction, isPending] = useActionState(someServerFunction, { title: "My draft", }); return ( <form action={dispatchAction}> <input name="title" defaultValue={state.title} /> <button type="submit" disabled={isPending}> {isPending ? "Saving..." : "Save"} </button> </form> ); }

Enhance form documentation for form default reset behavior

5245923

vercel Bot deployed to Preview June 29, 2026 16:07 View deployment

rickhanlonii requested a review from aurorascharff June 29, 2026 17:09

aurorascharff requested a review from rickhanlonii June 29, 2026 18:05

Reorder sections for better progressive disclosure of ideas

e426aa5

vercel Bot deployed to Preview June 29, 2026 19:07 View deployment

MaxwellCohen marked this pull request as ready for review June 29, 2026 19:09

aurorascharff requested a review from gaearon July 1, 2026 17:21

MaxwellCohen added 4 commits July 2, 2026 10:07

fix typos in form.md

93f421c

Normalize MDN links in form.md

7795146

Standardized all Usage headings in form.md to imperative form

2925e1d

add useOptimistic reference

fad1a7d

vercel Bot deployed to Preview July 2, 2026 18:18 View deployment

Standardize section headings in form.md to imperative form

ffb4824

vercel Bot deployed to Preview July 2, 2026 18:37 View deployment

revert 'action' prop change

d6b03fa

vercel Bot deployed to Preview July 2, 2026 18:51 View deployment

vercel Bot deployed to Preview July 2, 2026 19:55 View deployment

aurorascharff reviewed Jul 5, 2026

View reviewed changes

MaxwellCohen added 2 commits July 5, 2026 22:08

clean up Handling form submission with an action prop

b341728

clean up preserving form values after submission

4f39d4b

vercel Bot deployed to Preview July 6, 2026 04:11 View deployment

MaxwellCohen force-pushed the feat/8397/disabling-default-form-reset branch from 7288a0d to 08359a5 Compare July 6, 2026 04:17

vercel Bot deployed to Preview July 6, 2026 04:18 View deployment

update code example for Handling multiple submission types

947c926

MaxwellCohen force-pushed the feat/8397/disabling-default-form-reset branch from 08359a5 to 947c926 Compare July 6, 2026 04:18

vercel Bot deployed to Preview July 6, 2026 04:19 View deployment

Clean up code example for Handling multiple submission types

5a9e230

vercel Bot deployed to Preview July 6, 2026 13:04 View deployment

hernan-yadiel reviewed Jul 6, 2026

View reviewed changes


		</Sandpack>

		Because you call the action manually from `onSubmit`, [`useFormStatus`](/reference/react-dom/hooks/useFormStatus) won't report its pending state. Read `isPending` from the same [`useTransition`](/reference/react/useTransition) call instead.


		When you pass a function to `action` or `formAction`, React resets the form's [uncontrolled fields](/reference/react-dom/components/input#reading-the-input-values-when-submitting-a-form) after the action succeeds. This reset only affects uncontrolled fields—[inputs controlled with state](/reference/react-dom/components/input#controlling-an-input-with-a-state-variable) are never cleared.

		To preserve the values of uncontrolled fields after submission, add an `onSubmit` handler that calls `e.preventDefault()` and runs the action inside a [Transition](/reference/react/useTransition). Keep the `action` prop on the form so it continues to work before JavaScript loads.

Uh oh!

Conversation

MaxwellCohen commented Jun 29, 2026

Summary

Uh oh!

github-actions Bot commented Jun 29, 2026

Size changes

📦 Next.js Bundle Analysis for react-dev

Uh oh!

aurorascharff commented Jun 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxwellCohen Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxwellCohen Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxwellCohen Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aurorascharff Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hernan-yadiel Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MaxwellCohen Jul 6, 2026 •

edited

Loading

MaxwellCohen Jul 6, 2026 •

edited

Loading

MaxwellCohen Jul 6, 2026 •

edited

Loading

aurorascharff Jul 6, 2026 •

edited

Loading

hernan-yadiel Jul 6, 2026 •

edited

Loading