The FormData
object lets you compile a set of key/value pairs to send using XMLHttpRequest
. It is primarily intended for use in sending form data, but can be used independently from forms in order to transmit keyed data. The transmitted data is in the same format that the form's submit()
method would use to send the data if the form's encoding type were set to multipart/form-data
.
You can build a FormData
object yourself, instantiating it then appending fields to it by calling its append()
method, like this:
const formData = new FormData();
formData.append("username", "Groucho");
formData.append("accountnum", 123456);
formData.append("userfile", fileInputElement.files[0]);
const content = '<q id="a"><span id="b">hey!</span></q>';
const blob = new Blob([content], { type: "text/xml" });
formData.append("webmasterfile", blob);
const request = new XMLHttpRequest();
request.open("POST", "http://foo.com/submitform.php");
request.send(formData);
Note: The fields "userfile" and "webmasterfile" both contain a file. The number assigned to the field "accountnum" is immediately converted into a string by the FormData.append()
method (the field's value can be a Blob
, File
, or a string: if the value is neither a Blob nor a File, the value is converted to a string).
This example builds a FormData
instance containing values for fields named "username", "accountnum", "userfile" and "webmasterfile", then uses the XMLHttpRequest
method send()
to send the form's data. The field "webmasterfile" is a Blob
. A Blob
object represents a file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File
interface is based on Blob
, inheriting blob functionality and expanding it to support files on the user's system. In order to build a Blob
you can invoke the Blob() constructor
.
To construct a FormData
object that contains the data from an existing <form>
, specify that form element when creating the FormData
object:
Note: FormData will only use input fields that use the name attribute.
const formData = new FormData(someFormElement);
For example:
const formElement = document.querySelector("form");
const request = new XMLHttpRequest();
request.open("POST", "submitform.php");
request.send(new FormData(formElement));
You can also append additional data to the FormData
object between retrieving it from a form and sending it, like this:
const formElement = document.querySelector("form");
const formData = new FormData(formElement);
const request = new XMLHttpRequest();
request.open("POST", "submitform.php");
formData.append("serialnumber", serialNumber++);
request.send(formData);
This lets you augment the form's data before sending it along, to include additional information that's not necessarily user-editable.
You can also send files using FormData
. Include an <input>
element of type file
in your <form>
:
<form enctype="multipart/form-data" method="post" name="fileinfo">
<p>
<label
>Your email address:
<input
type="email"
autocomplete="on"
name="userid"
placeholder="email"
required
size="32"
maxlength="64" />
</label>
</p>
<p>
<label
>Custom file label:
<input type="text" name="filelabel" size="12" maxlength="32" />
</label>
</p>
<p>
<label
>File to stash:
<input type="file" name="file" required />
</label>
</p>
<p>
<input type="submit" value="Stash the file!" />
</p>
</form>
<div id="output"></div>
Then you can send it using code like the following:
const form = document.forms.namedItem("fileinfo");
form.addEventListener(
"submit",
(event) => {
const output = document.querySelector("#output");
const formData = new FormData(form);
formData.append("CustomField", "This is some extra data");
const request = new XMLHttpRequest();
request.open("POST", "stash.php", true);
request.onload = (progress) => {
output.innerHTML =
request.status === 200
? "Uploaded!"
: `Error ${request.status} occurred when trying to upload your file.<br />`;
};
request.send(formData);
event.preventDefault();
},
false,
);
Note: If you pass in a reference to the form, the request method specified in the form will be used over the method specified in the open() call.
Warning: When using FormData to submit POST requests using XMLHttpRequest
or the Fetch_API
with the multipart/form-data
Content-Type (e.g. when uploading Files and Blobs to the server), do not explicitly set the Content-Type
header on the request. Doing so will prevent the browser from being able to set the Content-Type header with the boundary expression it will use to delimit form fields in the request body.
You can also append a File
or Blob
directly to the FormData
object, like this:
data.append("myfile", myBlob, "filename.txt");
When using the append()
method it is possible to use the third optional parameter to pass a filename inside the Content-Disposition
header that is sent to the server. When no filename is specified (or the parameter isn't supported), the name "blob" is used.
A more recent addition to the platform than the FormData
object is the formdata
event — this is fired on an HTMLFormElement
object after the entry list representing the form's data is constructed. This happens when the form is submitted, but can also be triggered by the invocation of a FormData()
constructor.
This allows a FormData
object to be quickly obtained in response to a formdata
event firing, rather than needing to put it together yourself.
Typically this is used as shown in our simple formdata event demo — in the JavaScript we reference a form:
const formElem = document.querySelector("form");
In our submit
event handler we use preventDefault
to stop the default form submission, then invoke a FormData
constructor to trigger the formdata
event:
formElem.addEventListener("submit", (e) => {
e.preventDefault();
new FormData(formElem);
});
When the formdata
event fires we can access the FormData
object using FormDataEvent.formData
, then do what we like with it (below we post it to the server using XMLHttpRequest
).
formElem.addEventListener("formdata", (e) => {
console.log("formdata fired");
const data = e.formData;
for (const value of data.values()) {
console.log(value);
}
const request = new XMLHttpRequest();
request.open("POST", "/formHandler");
request.send(data);
});
Note: The formdata
event and FormDataEvent
object are available in Chrome from version 77 (and other equivalent Chromiums), and Firefox 72 (first available behind the dom.formdata.event.enabled
pref in Firefox 71).
If you want to know how to serialize and submit a form via AJAX without using FormData objects, please read this paragraph.
Gotchas
The FormData
object doesn't include data from the fields that are disabled or the fieldsets that are disabled.
See also