diff --git a/src/content/reference/react-dom/components/form.md b/src/content/reference/react-dom/components/form.md index 459c27e0be9..5676dbb7381 100644 --- a/src/content/reference/react-dom/components/form.md +++ b/src/content/reference/react-dom/components/form.md @@ -103,6 +103,8 @@ When you pass a function to `action`, React: * Propagates any errors to the nearest Error Boundary. * Resets the form's uncontrolled fields when the function succeeds. To keep their values, see [Preserving form values after an Action](#preserve-form-values-after-an-action). +If you handle submission manually, you can [request the same reset behavior with `requestFormReset`](/reference/react-dom/requestFormReset#requesting-a-reset-in-a-custom-form-action). + Because the Action runs in a Transition, you can also use [`useActionState`](/reference/react/useActionState) to manage form state and [`useOptimistic`](/reference/react/useOptimistic) for optimistic UI. For [Server Functions](/reference/rsc/server-functions) and progressive enhancement, see [Handling form submission with a Server Function](#handle-form-submission-with-a-server-function). diff --git a/src/content/reference/react-dom/index.md b/src/content/reference/react-dom/index.md index 6ba5cdc9332..1c0e03a2e7f 100644 --- a/src/content/reference/react-dom/index.md +++ b/src/content/reference/react-dom/index.md @@ -16,6 +16,7 @@ These APIs can be imported from your components. They are rarely used: * [`createPortal`](/reference/react-dom/createPortal) lets you render child components in a different part of the DOM tree. * [`flushSync`](/reference/react-dom/flushSync) lets you force React to flush a state update and update the DOM synchronously. +* [`requestFormReset`](/reference/react-dom/requestFormReset) lets you request a form reset when handling submissions with custom Actions or Transitions. ## Resource Preloading APIs {/*resource-preloading-apis*/} diff --git a/src/content/reference/react-dom/requestFormReset.md b/src/content/reference/react-dom/requestFormReset.md new file mode 100644 index 00000000000..cd99a904a4c --- /dev/null +++ b/src/content/reference/react-dom/requestFormReset.md @@ -0,0 +1,89 @@ +--- +title: requestFormReset +--- + + + +`requestFormReset` lets you reset a React-managed form after an Action or Transition finishes. + +```js +requestFormReset(form) +``` + + + + + +--- + +## Reference {/*reference*/} + +### `requestFormReset(form)` {/*requestformreset*/} + +Call `requestFormReset` to request that a form resets after the current Action or Transition completes. + +```js +import { startTransition } from 'react'; +import { requestFormReset } from 'react-dom'; + +function handleSubmit(form) { + startTransition(async () => { + const formData = new FormData(form); + requestFormReset(form); + await save(formData); + }); +} +``` + +[See more examples below.](#usage) + +#### Parameters {/*parameters*/} + +* `form`: an [HTML form element](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement) rendered by React. + +#### Returns {/*returns*/} + +`requestFormReset` returns nothing. + +#### Caveats {/*caveats*/} + +* Pass a form element that is rendered by React. Passing a non-form element, or a form not managed by React, throws an error. +* `requestFormReset` is intended for Actions and Transitions. If called outside an Action or Transition, React warns in development and performs a synchronous reset. +* `requestFormReset` is useful when you implement form submission logic yourself (for example with `onSubmit` + `startTransition`) and still want React's form reset behavior. +* This API requests a reset for uncontrolled form fields. For controlled fields, handle resets by updating state, such as in `onReset`. + +--- + +## Usage {/*usage*/} + +### Requesting a reset in a custom form Action {/*requesting-a-reset-in-a-custom-form-action*/} + +React [automatically resets uncontrolled fields after a successful `
` submission](/reference/react-dom/components/form#handle-form-submission-with-an-action-prop). When you implement submission manually, you can opt into the same behavior by calling `requestFormReset`. + +```js +import { startTransition } from 'react'; +import { requestFormReset } from 'react-dom'; + +function SearchForm() { + async function onSubmit(event) { + event.preventDefault(); + + const form = event.currentTarget; + const formData = new FormData(form); + + startTransition(async () => { + requestFormReset(form); + await submitSearch(formData); + }); + } + + return ( + + + +
+ ); +} +``` + +If your submission uses the built-in `
` behavior, you don't need to call `requestFormReset` manually. diff --git a/src/sidebarReference.json b/src/sidebarReference.json index be0b0c1836b..05f9e7fc05e 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -262,6 +262,10 @@ "title": "flushSync", "path": "/reference/react-dom/flushSync" }, + { + "title": "requestFormReset", + "path": "/reference/react-dom/requestFormReset" + }, { "title": "preconnect", "path": "/reference/react-dom/preconnect"