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.
const data = new FormData(form); console.log(data.get("email"));
Try it
Syntax
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,
disabledfields, controls without aname, and buttons other than the submitter are skipped. - Values are strings or files. A number input gives
"42", not42. Convert as needed. - Repeated names.
Object.fromEntries(formData)keeps only the last value of repeated names. UsegetAll()for checkboxes and multi-selects. - Sending with
fetch(). Pass the object asbody. Do not setContent-Type: the browser addsmultipart/form-datawith 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'snameandvalue, as in a real submission. formdataevent. A listener on the form can add data while theFormDatais being built.- It is a snapshot. Later changes in the form do not update an existing object.
- Files from
<input type="file">appear asFileobjects; 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.