FormData: Package Form Data for HTTP Requests

Why it exists

Before FormData, developers had to manually collect form values, encode them correctly (especially for file uploads), and set the right Content-Type headers for AJAX requests. This was tedious and error-prone. FormData was created to automate this entire process, simplifying form submissions in JavaScript.

The mental model

FormData is a specialized key/value store that mirrors an HTML form. It acts as a ready-to-send package for your data, handling the complex multipart/form-data encoding for you, which is crucial for file uploads. You can give it a <form> element and it will grab all the inputs, or you can build it piece by piece using its methods.

How it works

You create a new FormData object, optionally passing an HTML <form> element to its constructor to pre-populate it with that form's data. You can then manipulate the data using methods like append(key, value), set(key, value), and delete(key). When you pass this FormData object as the body of a fetch() request, the browser automatically sets the correct Content-Type: multipart/form-data header and serializes the data for you.

When to use it

Use FormData whenever you need to submit form data via JavaScript, especially when the form includes file uploads (<input type="file">). It's also useful for programmatically constructing data that mimics a form submission without an actual <form> element on the page. It works seamlessly with fetch(), XMLHttpRequest, and navigator.sendBeacon().

When not to use it

For simple key/value data without files, sending a plain JSON object with Content-Type: application/json can be simpler and is more common for modern APIs. If you only need to create a URL query string for a GET request, using URLSearchParams directly might be more straightforward, although FormData can be passed to its constructor.

One canonical example

To send a form with an ID user-profile-form that includes a file input, you can write: const myForm = document.getElementById('user-profile-form'); const formData = new FormData(myForm); fetch('/api/profile', { method: 'POST', body: formData });. The browser handles all the encoding and header details.