Clarify form value preservation examples and guidance

Author: aurorascharff

src/content/reference/react-dom/components/form.md

@@ -213,9 +213,9 @@ function AddToCart({ productId }) {
 }
 ```
 
-`addToCart.bind(null, productId)` calls `addToCart(productId, formData)`.
+When the form is submitted, React calls `addProductToCart(formData)`, which calls `addToCart(productId, formData)`.
 
-[`useActionState`](/reference/react/useActionState) passes the previous state before `FormData`. Bound arguments come first, so the Server Function receives the bound values, the previous state, and then `formData`. Define that function in a separate file and bind it from the Client Component.
+If you also use [`useActionState`](/reference/react/useActionState), the Server Function receives `productId`, `previousState`, and `formData`, in that order. Define that function in a separate file and bind it from the Client Component.
 
 #### A function in the component {/*passing-extra-data-function*/}
 
@@ -248,15 +248,15 @@ export async function updateCart(productId, formData) {
 }
 ```
 
-Users can submit this form only after JavaScript loads.
+Because `addToCart` runs in the browser, the component's JavaScript must load before the form can submit.
 
 </DeepDive>
 
 ---
 
 ### Displaying a pending state during form submission {/*display-a-pending-state-during-form-submission*/}
 
-To display a pending state when a form is being submitted, you can call the `useFormStatus` Hook in a component rendered in a `<form>` and read the `pending` property returned.
+To display a pending state when a form is being submitted, you can call the [`useFormStatus`](/reference/react-dom/hooks/useFormStatus) Hook in a component rendered in a `<form>` and read the `pending` property returned.
 
 Here, we use the `pending` property to indicate the form is submitting.
 
@@ -302,14 +302,14 @@ To learn more about the `useFormStatus` Hook, see the [reference documentation](
 
 ### Optimistically updating form data {/*optimistically-updating-form-data*/}
 
-The `useOptimistic` Hook provides a way to optimistically update the user interface before a background operation, like a network request, completes. In the context of forms, this technique helps to make apps feel more responsive. When a user submits a form, instead of waiting for the server's response to reflect the changes, the interface is immediately updated with the expected outcome.
+The [`useOptimistic`](/reference/react/useOptimistic) Hook provides a way to optimistically update the user interface before a background operation, like a network request, completes. In the context of forms, this technique helps to make apps feel more responsive. When a user submits a form, instead of waiting for the server's response to reflect the changes, the interface is immediately updated with the expected outcome.
 
 For example, when a user types a message into the form and hits the "Send" button, the `useOptimistic` Hook allows the message to immediately appear in the list with a "Sending..." label, even before the message is actually sent to a server. This "optimistic" approach gives the impression of speed and responsiveness. The form then attempts to truly send the message in the background. Once the server confirms the message has been received, the "Sending..." label is removed.
 
 <Sandpack>
 
 ```js src/App.js
-import { useOptimistic, useState, useRef } from 'react';
+import { startTransition, useOptimistic, useState, useRef } from 'react';
 import { deliverMessage } from './actions.js';
 
 function Thread({ messages, sendMessage }) {
@@ -352,7 +352,9 @@ export default function App() {
   ]);
   async function sendMessage(formData) {
     const sentMessage = await deliverMessage(formData.get('message'));
-    setMessages((messages) => [...messages, { text: sentMessage }]);
+    startTransition(() => {
+      setMessages((messages) => [...messages, { text: sentMessage }]);
+    });
   }
   return <Thread messages={messages} sendMessage={sendMessage} />;
 }
@@ -374,7 +376,7 @@ To learn more about the `useOptimistic` Hook, see the [reference documentation](
 
 ### Handling form submission errors {/*handling-form-submission-errors*/}
 
-To handle errors thrown by a function passed to a `<form>`'s `action` prop, wrap the form in an Error Boundary. React displays the boundary's fallback when the function throws.
+To handle errors thrown by a function passed to a `<form>`'s `action` prop, wrap the form in an [Error Boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary). React displays the boundary's fallback when the function throws.
 
 <Sandpack>
 
@@ -412,15 +414,13 @@ export default function Search() {
 
 </Sandpack>
 
----
-
-### Displaying a form submission error without JavaScript {/*display-a-form-submission-error-without-javascript*/}
+#### Handling form submission errors before JavaScript loads {/*display-a-form-submission-error-without-javascript*/}
 
 Displaying a form submission error message before the JavaScript bundle loads for progressive enhancement requires that:
 
 1. `<form>` be rendered by a [Client Component](/reference/rsc/use-client)
 1. the function passed to the `<form>`'s `action` prop be a [Server Function](/reference/rsc/server-functions)
-1. the `useActionState` Hook be used to display the error message
+1. the [`useActionState`](/reference/react/useActionState) Hook be used to display the error message
 
 Define the Server Function in a separate file with the [`'use server'`](/reference/rsc/use-server) directive. It receives the previous state followed by the submitted `FormData`:
 
@@ -469,75 +469,56 @@ If the form is submitted before JavaScript loads, React includes the Server Func
 
 ### Preserving form values after an Action {/*preserve-form-values-after-an-action*/}
 
-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. To keep the submitted values, store each value in state and pass it to that field's `defaultValue`. The reset then restores each field to its `defaultValue` instead of clearing it.
-
-To keep those values when users submit the form before JavaScript loads, render the `<form>` from a [Client Component](/reference/rsc/use-client) and pass a [Server Function](/reference/rsc/server-functions) to [`useActionState`](/reference/react/useActionState). Pass the Action it returns to the form's `action` prop. The Server Function receives the previous state, followed by the submitted `FormData`, as shown in [Displaying a form submission error without JavaScript](#display-a-form-submission-error-without-javascript). Return an object with the values to keep, and pass each value, such as `state.title`, to the matching field's `defaultValue`:
-
-```js
-// actions.js
-'use server';
-
-import { saveTitle } from './api.js';
-
-export async function updateTitle(previousState, formData) {
-  const title = formData.get('title');
-  await saveTitle(title);
-  return { title };
-}
-```
+When a function passed to `action` or `formAction` completes without throwing, React resets the form's [uncontrolled fields](/reference/react-dom/components/input#reading-the-input-values-when-submitting-a-form). You may want to keep the submitted values after saving edits, or when the Action returns a [validation error](/reference/react/useActionState#displaying-validation-errors-and-preserving-form-values).
 
-```js
-// EditForm.js
-'use client';
+To preserve those values, you can store them with [`useState`](/reference/react/useState) and pass them to each field's [`defaultValue`](/reference/react-dom/components/input#providing-an-initial-value-for-an-input). Update the state when the Action finishes. React applies the updated defaults before resetting the form, so the fields keep those values.
 
-import { useActionState } from 'react';
-import { updateTitle } from './actions.js';
-
-export default function EditForm() {
-  const [state, updateTitleAction, isPending] = useActionState(updateTitle, {
-    title: 'My draft',
-  });
-
-  return (
-    <form action={updateTitleAction}>
-      <input name="title" defaultValue={state.title} />
-      <button type="submit" disabled={isPending}>
-        {isPending ? 'Saving...' : 'Save'}
-      </button>
-    </form>
-  );
-}
-```
-
-Users can submit the form before JavaScript loads. After the Action succeeds, `defaultValue={state.title}` restores the title from the returned object.
-
-For a form that submits only after JavaScript loads, store the values with [`useState`](/reference/react/useState). Update that state when the Action finishes. React applies the new `defaultValue`, then resets the form, so each field shows the submitted value:
+Try changing the title and clicking **Save**. In this example, [`useFormStatus`](/reference/react-dom/hooks/useFormStatus) shows "Saving..." during a simulated one-second request. Then `setTitle` updates the saved title and preserves it in the input.
 
 <Sandpack>
 
 ```js src/App.js
-import { useState } from 'react';
+import { startTransition, useState } from 'react';
+import SaveButton from './SaveButton.js';
 
 export default function EditForm() {
   const [title, setTitle] = useState('My draft');
 
   async function saveAction(formData) {
     await new Promise((res) => setTimeout(res, 1000));
-    setTitle(formData.get('title'));
+    startTransition(() => {
+      setTitle(formData.get('title'));
+    });
   }
 
   return (
     <form action={saveAction}>
       <input name="title" defaultValue={title} />
-      <button type="submit">Save</button>
+      <SaveButton />
+      <p>Saved title: {title}</p>
     </form>
   );
 }
 ```
 
+```js src/SaveButton.js hidden
+import { useFormStatus } from 'react-dom';
+
+export default function SaveButton() {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Saving...' : 'Save'}
+    </button>
+  );
+}
+```
+
 </Sandpack>
 
-Call a Server Function from `saveAction`, then store its return value in state. Because `saveAction` is defined in the Client Component, users can submit this form only after JavaScript loads:
+The call to `setTitle` [after `await`](/reference/react/useTransition#react-doesnt-treat-my-state-update-after-await-as-a-transition) needs another [`startTransition`](/reference/react/startTransition) to mark it as a Transition update.
+
+`saveAction` can also call a [Server Function](/reference/rsc/server-functions) and store its return value:
 
 ```js
 // actions.js
@@ -552,25 +533,58 @@ export async function submitTitle(formData) {
 }
 ```
 
+Add [`'use client'`](/reference/rsc/use-client) at the top of the component's file, import `submitTitle`, and replace `saveAction`. The rest of the form stays the same:
+
+```js
+import { submitTitle } from './actions.js';
+
+async function saveAction(formData) {
+  const savedTitle = await submitTitle(formData);
+  startTransition(() => {
+    setTitle(savedTitle);
+  });
+}
+```
+
+#### Preserving form values before JavaScript loads {/*preserving-form-values-before-javascript-loads*/}
+
+With [`useActionState`](/reference/react/useActionState), React can display a [Server Function](/reference/rsc/server-functions)'s returned value before hydration completes. The form can use those values as its new defaults. In a [Client Component](/reference/rsc/use-client), `useActionState` receives the Server Function and returns an Action for the form's `action` prop.
+
+See [Handling form submission errors before JavaScript loads](#display-a-form-submission-error-without-javascript) for the same behavior with errors.
+
+The Server Function receives the previous state followed by the submitted `FormData`. In this example, `updateTitle` saves the title and returns `{ title }`, which becomes the new state. Passing `state.title` to `defaultValue` preserves the saved title after the reset:
+
+```js
+// actions.js
+'use server';
+
+import { saveTitle } from './api.js';
+
+export async function updateTitle(previousState, formData) {
+  const title = formData.get('title');
+  await saveTitle(title);
+  return { title };
+}
+```
+
 ```js
 // EditForm.js
 'use client';
 
-import { useState } from 'react';
-import { submitTitle } from './actions.js';
+import { useActionState } from 'react';
+import { updateTitle } from './actions.js';
 
 export default function EditForm() {
-  const [title, setTitle] = useState('My draft');
-
-  async function saveAction(formData) {
-    const savedTitle = await submitTitle(formData);
-    setTitle(savedTitle);
-  }
+  const [state, updateTitleAction, isPending] = useActionState(updateTitle, {
+    title: 'My draft',
+  });
 
   return (
-    <form action={saveAction}>
-      <input name="title" defaultValue={title} />
-      <button type="submit">Save</button>
+    <form action={updateTitleAction}>
+      <input name="title" defaultValue={state.title} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Saving...' : 'Save'}
+      </button>
     </form>
   );
 }
@@ -584,7 +598,7 @@ The examples above keep every submitted value by storing it before the reset. Yo
 
 * **Keep values only when validation fails.** Return the same state shape from every submission. When validation fails, include the submitted `FormData` and read each field with `state.submitted?.get('title') ?? ''`. When validation succeeds, set that `FormData` to `null` so the reset clears those fields. [`useActionState`](/reference/react/useActionState#displaying-validation-errors-and-preserving-form-values) shows this pattern.
 
-* **Skip the reset with `onSubmit`.** Handle the submission in `onSubmit`, call `e.preventDefault()`, and run the Action inside [`startTransition`](/reference/react/useTransition). Because the form's `action` does not run, React does not reset the form. Users can submit this form only after JavaScript loads.
+* **Skip the reset with `onSubmit`.** Handle the submission in `onSubmit`, call `e.preventDefault()`, and run the Action inside [`startTransition`](/reference/react/useTransition). Because the form's `action` does not run, React does not reset the form.
 
 * **Reset at a specific moment.** Call the form element's [`reset()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reset) method to immediately reset uncontrolled fields to their default values. To schedule a reset as part of an Action or Transition, call [`requestFormReset`](/blog/2024/12/05/react-19#form-actions) from `react-dom` instead.
 
@@ -596,7 +610,7 @@ The examples above keep every submitted value by storing it before the reset. Yo
 
 ### Handling multiple submission types {/*handling-multiple-submission-types*/}
 
-A form can have more than one submit button, each running a different Action. A button without `formAction` runs the form's `action`; a button with `formAction` runs its own Action instead. For example, the form below publishes an article by default, but its **Save draft** button stores the current content without publishing it:
+A form can have more than one submit button, each running a different Action. A button without `formAction` runs the form's `action`; a button with `formAction` runs its own Action instead. For example, the form below publishes an article by default, but its **Save draft** button stores the current content without publishing it. It uses [`useActionState`](/reference/react/useActionState) to preserve the saved draft:
 
 <Sandpack>
 
@@ -650,3 +664,13 @@ export default function ArticleForm() {
 ```
 
 </Sandpack>
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### My form fields are cleared after submission {/*my-form-fields-are-cleared-after-submission*/}
+
+When a function passed to `action` or `formAction` succeeds, React resets the form's uncontrolled fields to their default values. Text fields without a `defaultValue` become empty. Returning a validation error instead of throwing also triggers this reset.
+
+To keep a submitted value, store it in state and pass it to the field's `defaultValue`. See [Preserving form values after an Action](#preserve-form-values-after-an-action) for examples, or [preserving values when validation fails](/reference/react/useActionState#displaying-validation-errors-and-preserving-form-values).

src/content/reference/react/useActionState.md

@@ -1245,7 +1245,7 @@ When validation fails, `updateName` returns an error and the submitted `FormData
 
 <RSC>
 
-When the `reducerAction` passed to `useActionState` is a [Server Function](/reference/rsc/server-functions), pass the returned `submitAction` to the form's `action` prop. React can then display the Server Function's returned value before hydration completes. Return the submitted `FormData` and use it to set each field's `defaultValue` to preserve those values before JavaScript loads. On pages with dynamic content, you can also use the optional `permalink` parameter for progressive enhancement.
+The example above runs `updateName` in the browser. To display the error and preserve the submitted name before JavaScript loads, make `updateName` a [Server Function](/reference/rsc/server-functions). Keep passing `submitAction` to the form's `action` prop. React can then display the Server Function's returned value before hydration completes. See [preserving form values before JavaScript loads](/reference/react-dom/components/form#preserving-form-values-before-javascript-loads) for the setup. On pages with dynamic content, you can also use the optional [`permalink`](#parameters) parameter for progressive enhancement.
 
 </RSC>