React Reference ยท Built-in DOM Components
The React form element
Reference for the React form element: pass a function to action, receive FormData, understand the automatic reset, and choose between action and onSubmit.
<form> collects fields and submits them. React 19 added a major feature: the action prop can be a function. When the form is submitted, React calls your function with a FormData object, runs it inside a transition, and prevents the browser's default page navigation. After the action finishes successfully, React resets the form's uncontrolled fields.
You can still use the classic onSubmit handler and call event.preventDefault() yourself. Actions are the newer, more integrated path: they work with useFormStatus, useActionState and useOptimistic, and they can be asynchronous.
function save(formData) { console.log(formData.get('title')); } <form action={save}> <input name="title" /> <button>Save</button> </form>
Try it
Syntax
<form action={string | ((formData: FormData) => void | Promise<void>)} onSubmit={handler} />
| Name | Description |
|---|---|
action |
A URL string (normal browser submit) or a function called with the FormData of the form. |
onSubmit |
Called on the submit event. Call event.preventDefault() to stop the browser navigating. Runs before the action; calling preventDefault() there skips the action. |
onReset |
Called on the reset event. |
method, encType, target, noValidate, autoComplete, acceptCharset |
Same as in HTML. They matter when action is a string. |
children |
The fields and buttons. |
Returns: an HTMLFormElement.
Action function: receives one FormData argument. It may return a promise. A rejected promise is treated as an error and goes to the nearest error boundary. A button with its own formAction overrides the form's action for that submission.
Usage notes
- Fields need a
name.FormDataonly contains named, non-disabled fields. Checkboxes appear only when checked, and file inputs giveFileobjects. - Automatic reset. After a function action completes, React resets the form like
form.reset(). Uncontrolled fields go back to theirdefaultValue. Controlled fields are driven by state, so keep their state in step (reset the state in the action if you want them cleared). - No reset with
onSubmit. The automatic reset belongs to function actions only. WithonSubmityou clear fields yourself. - String actions. A string
actionis a normal HTML form: the browser navigates to that URL. In the sandboxed preview that goes nowhere, so use a function. - Pending state. Child components can call
useFormStatus()to readpending,dataandmethodof the nearest parent form. The hook must be called in a component rendered inside the form, not in the component that renders the form. - State updates. Updates made inside an action run in a transition, so they are not urgent and the UI stays responsive. Updates after an
awaitare not part of the transition unless you wrap them instartTransition. - Submitting from code.
form.requestSubmit()triggers validation and the submit event, and so triggers your action.form.submit()skips both and goes straight to the browser's default behavior, so avoid it. - Validation. Native attributes such as
requiredandtype="email"run before the submit event. AddnoValidateonly when you replace them with your own checks. preventDefaultcancels the action. If youronSubmithandler callsevent.preventDefault(), React does not run a functionaction. Use one mechanism per form.