FormData: FormData() constructor

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Note: This feature is available in Web Workers.

The FormData() constructor creates a new FormData object.

Syntax

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

Parameters

form Optional: An HTML <form> element — when specified, the FormData object will be populated with the form's current keys/values using the name property of each element for the keys and their submitted value for the values. It will also encode file input content. A formdata event is fired on the form when the FormData object is created, allowing the form to modify the formdata if necessary.
submitter Optional: A submit button that is a member of the form. If the submitter has a name attribute or is an <input type="image">, its data will be included in the FormData object (e.g. btnName=btnValue).

Exceptions

TypeError: Thrown if the specified submitter is not a submit button.
NotFoundError DOMException: Thrown if the specified submitter isn't a member of the form. The submitter must be either a descendant of the form element or must have a form attribute referring to the form.

Examples

Creating an empty FormData

The following line creates an empty FormData object:

const formData = new FormData();

You could add a key/value pair to this using append():

formData.append("username", "Chris");

Prepopulating from a HTML form element

You can specify the optional form and submitter arguments when creating the FormData object, to prepopulate it with values from the specified form.

Note: Only successful form controls are included in a FormData object, i.e. those with a name and not in a disabled state.

HTML

html

<form id="form">
  <input type="text" name="text1" value="foo" />
  <input type="text" name="text2" value="bar" />
  <input type="text" name="text2" value="baz" />
  <input type="checkbox" name="check" checked disabled />
  <button name="intent" value="save">Save</button>
  <button name="intent" value="saveAsCopy">Save As Copy</button>
</form>

<output id="output"></output>

form {
  display: none;
}

output {
  display: block;
  white-space: pre-wrap;
}

JavaScript

const form = document.getElementById("form");
const submitter = document.querySelector("button[value=save]");
const formData = new FormData(form, submitter);

const output = document.getElementById("output");

for (const [key, value] of formData) {
  output.textContent += `${key}: ${value}\n`;
}

Result

For brevity, the <form> element is hidden from view.

Specifications

Specification
XMLHttpRequest # dom-formdata

desktop mobile server
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
FormData() constructor
submitter parameter