Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Document and Elements

The FormData interface

Reference for FormData: build it from a form, read values with get() and getAll(), iterate entries, convert to objects, append files and send with fetch.

FormData is a collection of name and value pairs that mirrors what a form would send. Pass a <form> element to the constructor and it reads every successful control for you: text inputs, checked boxes and radios, selected options, files and the submitter button if you provide it. You can also build one from scratch with append().

It is the most convenient way to read a whole form in a submit handler, and it is the body type fetch() uses for multipart/form-data uploads.

JavaScript
const data = new FormData(form);
console.log(data.get("email"));

Try it

Read a form
Build one by hand

Syntax

JavaScript
new FormData()
new FormData(form)
new FormData(form, submitter)

Methods

Method Description
append(name, value) Adds a pair, keeping any existing pairs with the same name.
append(name, blob, filename) Adds a file; the value becomes a File.
set(name, value) Replaces all pairs with that name by one (or adds it).
get(name) The first value for the name, or null.
getAll(name) An array of all values for the name (empty if none).
has(name) true if the name exists.
delete(name) Removes all pairs with the name.
entries(), keys(), values(), forEach() Iterate over the pairs; the object itself is iterable.

Return value

The constructor returns a FormData. get() returns a string, a File or null. Setters and delete() return undefined.

Usage notes

  • Only successful controls are included. Unchecked checkboxes and radios, disabled fields, controls without a name, and buttons other than the submitter are skipped.
  • Values are strings or files. A number input gives "42", not 42. Convert as needed.
  • Repeated names. Object.fromEntries(formData) keeps only the last value of repeated names. Use getAll() for checkboxes and multi-selects.
  • Sending with fetch(). Pass the object as body. Do not set Content-Type: the browser adds multipart/form-data with the correct boundary. For URL-encoded data, wrap it: new URLSearchParams(formData). If the form has files, that conversion is not suitable.
  • The submitter. The second constructor argument, such as event.submitter, includes that button's name and value, as in a real submission.
  • formdata event. A listener on the form can add data while the FormData is being built.
  • It is a snapshot. Later changes in the form do not update an existing object.
  • Files from <input type="file"> appear as File objects; an empty selection gives a file with an empty name and size 0.
  • Not logged readably. console.log(formData) often shows an empty-looking object; iterate it to see the pairs.

Browser support

FormData and its core methods work in every current browser. The submitter argument to the constructor is more recent, so check a compatibility table.