From b6e9b3c44da5f02d016b218da239dd466df7ac14 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 24 Jun 2026 22:39:15 +0200 Subject: [PATCH 1/2] [form] Document onSubmit event handler alongside action --- .../reference/react-dom/components/form.md | 39 ++++++++++++++++++- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/src/content/reference/react-dom/components/form.md b/src/content/reference/react-dom/components/form.md index 1043b13a0de..9c078aa028d 100644 --- a/src/content/reference/react-dom/components/form.md +++ b/src/content/reference/react-dom/components/form.md @@ -48,9 +48,44 @@ To create interactive controls for submitting information, render the [built-in ## Usage {/*usage*/} -### Handle form submission on the client {/*handle-form-submission-on-the-client*/} +### Handle form submission with an event handler {/*handle-form-submission-with-an-event-handler*/} -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. After the `action` function succeeds, all uncontrolled field elements in the form are reset. +Pass a function to the `onSubmit` event handler to run code when the form is submitted. By default, the browser sends the form data to the current URL and refreshes the page, so call [`e.preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) to override that behavior. Read the submitted data with [`new FormData(e.target)`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). + + + +```js src/App.js +export default function Search() { + function handleSubmit(e) { + // Prevent the browser from reloading the page + e.preventDefault(); + + // Read the form data + const formData = new FormData(e.target); + const query = formData.get("query"); + alert(`You searched for '${query}'`); + } + + return ( +
+ + +
+ ); +} +``` + + + + + +Reading form data with `onSubmit` works in every version of React and gives you direct access to the [submit event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event). The `action` prop, described next, builds on this with extra features like automatic form resets, pending states with [`useFormStatus`](/reference/react-dom/hooks/useFormStatus), and [Server Functions](/reference/rsc/server-functions). + + + +### Handle form submission with an action {/*handle-form-submission-with-an-action*/} + +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. From 1f48fb46a8d1d3b4c8758f18a7aec55323152242 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 24 Jun 2026 22:50:49 +0200 Subject: [PATCH 2/2] [form] Refine onSubmit/action framing and address review --- src/content/reference/react-dom/components/form.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/content/reference/react-dom/components/form.md b/src/content/reference/react-dom/components/form.md index 9c078aa028d..10e9c67940e 100644 --- a/src/content/reference/react-dom/components/form.md +++ b/src/content/reference/react-dom/components/form.md @@ -50,7 +50,9 @@ To create interactive controls for submitting information, render the [built-in ### Handle form submission with an event handler {/*handle-form-submission-with-an-event-handler*/} -Pass a function to the `onSubmit` event handler to run code when the form is submitted. By default, the browser sends the form data to the current URL and refreshes the page, so call [`e.preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) to override that behavior. Read the submitted data with [`new FormData(e.target)`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). +Pass a function to the `onSubmit` event handler to run code when the form is submitted. By default, the browser sends the form data to the current URL and refreshes the page, so call [`e.preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) to override that behavior. + +This example reads the submitted values with [`new FormData(e.target)`](https://developer.mozilla.org/en-US/docs/Web/API/FormData), which collects every field by its `name`. This keeps the inputs [uncontrolled](/reference/react-dom/components/input#reading-the-input-values-when-submitting-a-form). If you instead [control an input with state](/reference/react-dom/components/input#controlling-an-input-with-a-state-variable), read from that state on submit rather than from `FormData`. @@ -61,7 +63,8 @@ export default function Search() { e.preventDefault(); // Read the form data - const formData = new FormData(e.target); + const form = e.target; + const formData = new FormData(form); const query = formData.get("query"); alert(`You searched for '${query}'`); } @@ -79,11 +82,11 @@ export default function Search() { -Reading form data with `onSubmit` works in every version of React and gives you direct access to the [submit event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event). The `action` prop, described next, builds on this with extra features like automatic form resets, pending states with [`useFormStatus`](/reference/react-dom/hooks/useFormStatus), and [Server Functions](/reference/rsc/server-functions). +Reading form data with `onSubmit` works in every version of React and gives you direct access to the [submit event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event), so you can call `e.preventDefault()` and read the data yourself. Passing the function to the `action` prop instead runs the submission in a [Transition](/reference/react/useTransition). React then tracks the pending state, sends thrown errors to the nearest error boundary, and lets the form work with [`useActionState`](/reference/react/useActionState) and [`useOptimistic`](/reference/react/useOptimistic). An `action` can also be a [Server Function](/reference/rsc/server-functions), which `onSubmit` does not support. -### Handle form submission with an action {/*handle-form-submission-with-an-action*/} +### Handle form submission with an action prop {/*handle-form-submission-with-an-action-prop*/} 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.