React Reference ยท react-dom Resource and Form APIs
FormData in React form actions
Reference for reading FormData inside React form actions: get, getAll, entries, checkboxes, selects, files, missing fields and turning it into an object.
When you pass a function to <form action> or a button's formAction, React calls it with one argument: a standard browser FormData object. It is a snapshot of the form at the moment of submission. Every field with a name that would be sent by an HTML form is in it; everything else is not.
You do not need useState for each field, a ref, or event.target.elements. You read the values by name inside the action. The values are always strings, except file inputs, which give File objects. Converting to numbers, dates or booleans is your job.
function save(formData) { const email = formData.get('email'); // string | File | null const tags = formData.getAll('tag'); // all values for repeated names }
Try it
Press Send. The disabled input, the input without a name and the unchecked checkbox are absent. Both checked topics appear as separate entries, and Object.fromEntries keeps only the last one (js) because an object cannot hold repeated keys.
With the defaults the result reads Notebook x2, note: none, photo chosen: false, missing field: null. A file input with nothing chosen still produces a File, but an empty one, so test size > 0.
Syntax
function action(formData: FormData): void | Promise<void>;
| Method | Description |
|---|---|
formData.get(name) |
First value for name: a string, a File, or null if the field is absent. |
formData.getAll(name) |
Array of every value for name. Empty array when absent. Use for checkbox groups and <select multiple>. |
formData.has(name) |
true if at least one entry has this name. |
formData.entries(), keys(), values() |
Iterators. FormData is also directly iterable. |
formData.set(name, value), append(name, value), delete(name) |
Change your copy. The form on the page is not affected. |
Returns: the action ignores what you return; see useActionState to send results back to the UI.
Errors / edge cases: get never throws for a missing name, it returns null. A TypeError can still come from your own code, for example formData.get('x').trim() when the value is null.
Usage notes
- What is included. Named, enabled, successful controls: text-like inputs, the checked checkboxes and radio, selected options, textareas, hidden inputs and file inputs. Disabled fields, unnamed fields, unchecked boxes and plain buttons are left out.
- The submitter is included. If the button that was pressed has a
nameandvalue, that pair is added. This is how<button name="intent" value="delete">tells the action which button was used. It does not apply to a button that has its own functionformAction(React replaces its name). - A checked checkbox without
valuesends"on". Compare with=== 'on'or give it an explicitvalue. - Everything is a string. Even
type="number"andtype="date"fields. Convert withNumber(),Number.parseInt()ornew Date()and validate the result; an empty number field gives"", whichNumber("")turns into0. - Values are untrusted. Validate on the server again. A user can send anything, whatever your inputs allow.
Object.fromEntriesloses repeats. Build arrays yourself for repeated names, usinggetAll.- Disabling inputs while pending (via
useFormStatus) is safe: the snapshot was taken before React re-rendered. Fields that were already disabled at submit time are not included. - Large uploads are
Fileobjects; send them withfetchand the sameFormData, or hand them to a server function in a framework. - Server functions receive a
FormDatatoo, rebuilt on the server from the submitted request. Only strings and files can be in it.