Skip to content
Tutorials Center
My learning

Topics

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.

JSX
function save(formData) {
  const email = formData.get('email');       // string | File | null
  const tags = formData.getAll('tag');       // all values for repeated names
}

Try it

What ends up in FormData

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.

Parsing and validating values

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

TypeScript
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 name and value, 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 function formAction (React replaces its name).
  • A checked checkbox without value sends "on". Compare with === 'on' or give it an explicit value.
  • Everything is a string. Even type="number" and type="date" fields. Convert with Number(), Number.parseInt() or new Date() and validate the result; an empty number field gives "", which Number("") turns into 0.
  • Values are untrusted. Validate on the server again. A user can send anything, whatever your inputs allow.
  • Object.fromEntries loses repeats. Build arrays yourself for repeated names, using getAll.
  • 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 File objects; send them with fetch and the same FormData, or hand them to a server function in a framework.
  • Server functions receive a FormData too, rebuilt on the server from the submitted request. Only strings and files can be in it.