From 094602601e7110f87907aeba616fd7ba9a7903f4 Mon Sep 17 00:00:00 2001
From: Felix <146006641+Felix-ming@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:16:43 +0800
Subject: [PATCH 1/6] docs: explain useFormStatus with custom form actions

Closes #8682.

Document when `useFormStatus().pending` is set for a `preventDefault()` submit handler that starts a Transition in the same event, and add a runnable example for a custom form action. The example also notes that this pattern does not reset the form automatically.

Validation: `yarn check-all` and `git diff --check` pass locally. The initial draft was prepared with AI assistance and reviewed against the React DOM tests and issue details.
---
 .../react-dom/hooks/useFormStatus.md          | 59 ++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 7517d8ae22f..2ecb69aa780 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -54,7 +54,7 @@ In the above example, `Submit` uses this information to disable `<button>` press
 
 A `status` object with the following properties:
 
-* `pending`: A boolean. If `true`, this means the parent `<form>` is pending submission. Otherwise, `false`.
+* `pending`: A boolean. If `true`, this means the parent `<form>` is pending submission. Otherwise, `false`. `pending` is also `true` while a Transition started from a `submit` event handler is pending, as long as the handler calls `event.preventDefault()` and starts the Transition in the same event.
 
 * `data`: An object implementing the [`FormData interface`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) that contains the data the parent `<form>` is submitting. If there is no active submission or no parent `<form>`, it will be `null`.
 
@@ -112,6 +112,63 @@ export async function submitForm(query) {
 ```
 </Sandpack>
 
+### Display a pending state with a custom form action {/*display-a-pending-state-with-a-custom-form-action*/}
+
+If you need to handle form submission in an `onSubmit` event handler instead of passing a function to the `<form action>` prop, call `event.preventDefault()` and start a Transition in the same event handler. A component inside the form can then use `useFormStatus` to read the pending state while the action is running.
+
+<Sandpack>
+
+```js src/App.js
+import { startTransition } from 'react';
+import { useFormStatus } from 'react-dom';
+import { submitForm } from './submitForm.js';
+
+function SubmitButton() {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Submitting...' : 'Submit'}
+    </button>
+  );
+}
+
+function Form({ submitAction }) {
+  function handleSubmit(event) {
+    event.preventDefault();
+    const formData = new FormData(event.currentTarget);
+    startTransition(async () => {
+      await submitAction(formData);
+    });
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="query" />
+      <SubmitButton />
+    </form>
+  );
+}
+
+export default function App() {
+  async function submitAction(formData) {
+    await submitForm(formData);
+  }
+
+  return <Form submitAction={submitAction} />;
+}
+```
+
+```js src/submitForm.js hidden
+export async function submitForm(formData) {
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+}
+```
+
+</Sandpack>
+
+Unlike a function passed to the `<form action>` prop, handling submission this way does not automatically reset the form.
+
+
 <Pitfall>
 
 ##### `useFormStatus` will not return status information for a `<form>` rendered in the same component. {/*useformstatus-will-not-return-status-information-for-a-form-rendered-in-the-same-component*/}

From d8ff8ddc13592c0b355da877d413b4fbb2765f64 Mon Sep 17 00:00:00 2001
From: Aurora Scharff <aurora.sofie@gmail.com>
Date: Wed, 4 Nov 2026 19:27:22 -0600
Subject: [PATCH 2/6] Polish useFormStatus onSubmit documentation

---
 .../reference/react-dom/hooks/useFormStatus.md   | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 2ecb69aa780..99fad23b7bd 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -112,9 +112,11 @@ export async function submitForm(query) {
 ```
 </Sandpack>
 
-### Display a pending state with a custom form action {/*display-a-pending-state-with-a-custom-form-action*/}
+---
+
+### Display a pending state with an `onSubmit` handler {/*display-a-pending-state-with-an-onsubmit-handler*/}
 
-If you need to handle form submission in an `onSubmit` event handler instead of passing a function to the `<form action>` prop, call `event.preventDefault()` and start a Transition in the same event handler. A component inside the form can then use `useFormStatus` to read the pending state while the action is running.
+If you need to handle form submission in an `onSubmit` event handler instead of passing a function to the `<form action>` prop, call `event.preventDefault()` and start a Transition in the same event handler. A component inside the form can then use `useFormStatus` to read the pending state while the Action is running.
 
 <Sandpack>
 
@@ -126,16 +128,16 @@ import { submitForm } from './submitForm.js';
 function SubmitButton() {
   const { pending } = useFormStatus();
   return (
-    <button type="submit" disabled={pending}>
+    <button type='submit' disabled={pending}>
       {pending ? 'Submitting...' : 'Submit'}
     </button>
   );
 }
 
 function Form({ submitAction }) {
-  function handleSubmit(event) {
-    event.preventDefault();
-    const formData = new FormData(event.currentTarget);
+  function handleSubmit(e) {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
     startTransition(async () => {
       await submitAction(formData);
     });
@@ -143,7 +145,7 @@ function Form({ submitAction }) {
 
   return (
     <form onSubmit={handleSubmit}>
-      <input name="query" />
+      <input name='query' />
       <SubmitButton />
     </form>
   );

From 6907d6cd65038ecd6ff5be57ce7986d08723adf7 Mon Sep 17 00:00:00 2001
From: Aurora Scharff <aurora.sofie@gmail.com>
Date: Wed, 4 Nov 2026 19:29:56 -0600
Subject: [PATCH 3/6] Clarify pending status and link form reset guidance

---
 src/content/reference/react-dom/hooks/useFormStatus.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 99fad23b7bd..272078ead7d 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -54,7 +54,7 @@ In the above example, `Submit` uses this information to disable `<button>` press
 
 A `status` object with the following properties:
 
-* `pending`: A boolean. If `true`, this means the parent `<form>` is pending submission. Otherwise, `false`. `pending` is also `true` while a Transition started from a `submit` event handler is pending, as long as the handler calls `event.preventDefault()` and starts the Transition in the same event.
+* `pending`: A boolean. If `true`, the parent `<form>` is pending submission, either through its `action` prop or through an `onSubmit` handler that calls `event.preventDefault()` and starts a Transition in the same event. Otherwise, `false`.
 
 * `data`: An object implementing the [`FormData interface`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) that contains the data the parent `<form>` is submitting. If there is no active submission or no parent `<form>`, it will be `null`.
 
@@ -168,7 +168,7 @@ export async function submitForm(formData) {
 
 </Sandpack>
 
-Unlike a function passed to the `<form action>` prop, handling submission this way does not automatically reset the form.
+Unlike a function passed to the `<form action>` prop, handling submission this way [does not automatically reset the form](/reference/react-dom/components/form#other-ways-to-control-form-resets).
 
 
 <Pitfall>

From f6a767bcafe484da81c392aa0b16b4fa93bc79ce Mon Sep 17 00:00:00 2001
From: Aurora Scharff <aurora.sofie@gmail.com>
Date: Wed, 4 Nov 2026 19:31:40 -0600
Subject: [PATCH 4/6] Shorten pending definition and link onSubmit guidance

---
 src/content/reference/react-dom/hooks/useFormStatus.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 272078ead7d..b0b27962c9c 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -54,7 +54,7 @@ In the above example, `Submit` uses this information to disable `<button>` press
 
 A `status` object with the following properties:
 
-* `pending`: A boolean. If `true`, the parent `<form>` is pending submission, either through its `action` prop or through an `onSubmit` handler that calls `event.preventDefault()` and starts a Transition in the same event. Otherwise, `false`.
+* `pending`: A boolean. `true` while the parent `<form>` is submitting an Action or [running a Transition from `onSubmit`](#display-a-pending-state-with-an-onsubmit-handler). Otherwise, `false`.
 
 * `data`: An object implementing the [`FormData interface`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) that contains the data the parent `<form>` is submitting. If there is no active submission or no parent `<form>`, it will be `null`.
 

From 1a0e53622d29941a64350a9b431ca16960ddee3b Mon Sep 17 00:00:00 2001
From: Aurora Scharff <aurora.sofie@gmail.com>
Date: Wed, 4 Nov 2026 19:33:12 -0600
Subject: [PATCH 5/6] Link form submission and Transition references

---
 src/content/reference/react-dom/hooks/useFormStatus.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index b0b27962c9c..026f3bef4fe 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -116,7 +116,7 @@ export async function submitForm(query) {
 
 ### Display a pending state with an `onSubmit` handler {/*display-a-pending-state-with-an-onsubmit-handler*/}
 
-If you need to handle form submission in an `onSubmit` event handler instead of passing a function to the `<form action>` prop, call `event.preventDefault()` and start a Transition in the same event handler. A component inside the form can then use `useFormStatus` to read the pending state while the Action is running.
+If you need to handle form submission in an `onSubmit` event handler instead of passing a function to the [`<form action>` prop](/reference/react-dom/components/form#handle-form-submission-with-an-action-prop), call [`event.preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) and [start a Transition](/reference/react/startTransition) in the same event handler. A component inside the form can then use `useFormStatus` to read the pending state while the Action is running.
 
 <Sandpack>
 

From 1df25ec9a4c8d0ac610fadf89ab8f7cda3c098e0 Mon Sep 17 00:00:00 2001
From: Aurora Scharff <aurora.sofie@gmail.com>
Date: Wed, 4 Nov 2026 19:34:08 -0600
Subject: [PATCH 6/6] Make form pending-state headings parallel

---
 src/content/reference/react-dom/hooks/useFormStatus.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 026f3bef4fe..d208535131d 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -72,7 +72,7 @@ A `status` object with the following properties:
 
 ## Usage {/*usage*/}
 
-### Display a pending state during form submission {/*display-a-pending-state-during-form-submission*/}
+### Display a pending state with an `action` prop {/*display-a-pending-state-during-form-submission*/}
 To display a pending state while a form is submitting, you can call the `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.