React Reference ยท react-dom Resource and Form APIs
React requestFormReset() function
Reference for react-dom requestFormReset(): reset an uncontrolled form to its default values when a transition finishes, with onSubmit patterns and caveats.
requestFormReset(form) schedules a reset of a <form> element: every uncontrolled field goes back to its default value (defaultValue, defaultChecked, the selected option), exactly as if the user had pressed a reset button. The important detail is when it happens. React waits until the surrounding transition or action has finished and then resets, so the form does not blank out while a save is still running.
When you use a function in <form action={fn}>, React already resets the form after the action succeeds, and you do not need this function. It exists for the other cases: forms handled with onSubmit, and resets triggered from somewhere else, such as a "Clear" button.
import { requestFormReset } from 'react-dom'; startTransition(async () => { requestFormReset(formElement); await saveDraft(); });
Try it
Type something and press Post. The text stays in the box while the button says "Saving...", and the field empties together with the new list item when the transition ends.
Edit the name or untick the box, then press the button: both return to Ada and checked.
Syntax
requestFormReset(form)
function requestFormReset(form: HTMLFormElement): void;
| Name | Description |
|---|---|
form |
A form DOM element that React rendered, usually from event.currentTarget or a ref. |
Returns: nothing (undefined).
Errors / edge cases: it throws if the argument is not a form rendered by React ("Invalid form element"). In development it warns when called outside a transition or action, because the reset then has nothing to wait for.
Usage notes
- Call it inside a transition or action. That is what delays the reset until the work is done. Outside one it still resets, but immediately, and development builds log a warning.
- Call it before the first
await. Inside anasynctransition, code after anawaitis no longer tracked as part of the transition. Request the reset at the top, as in the first example. It is held back until the whole action completes. - Capture the form first.
event.currentTargetisnullafter anawait; read it into a variable at the start of the handler. - Only uncontrolled fields reset. Inputs with a
valueprop are driven by your state, so clear that state yourself. A form that mixes both resets only the uncontrolled ones. - Defaults, not blank. Fields return to
defaultValue/defaultChecked, which may be non-empty. If you want an empty form, make the defaults empty. - No need with
<form action={fn}>. React resets those automatically after the action. If you do not want that reset, keep the values in state and render them asdefaultValue, or use controlled inputs; see<form action>. - File inputs reset too, so an uploaded selection is cleared along with the text fields.