The FormData API
Collect form data programmatically with the FormData interface.
The FormData API is a free HTML Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the HTML Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What FormData Is
FormData is a built-in object representing form fields and their values, suitable for direct submission via fetch or XMLHttpRequest. It handles file uploads, multipart encoding, and arbitrary key-value pairs without manual serialization.
Construct From a Form
Pass a <form> element to the constructor: const data = new FormData(formElement). The result contains every successful form control (named inputs, selects, textareas, checked checkboxes, files). Disabled and unchecked controls are excluded automatically.
document.forms.checkout.addEventListener("submit", async (e) => {
e.preventDefault();
const data = new FormData(e.target);
await fetch("/api/checkout", { method: "POST", body: data });
});Submit with fetch
Passing FormData as fetch's body sets the request's Content-Type to multipart/form-data automatically (with the right boundary). Do not set Content-Type manually — fetch needs to generate the boundary itself.
Append, Set, Delete
data.append(key, value) adds a key (allowing duplicates). data.set(key, value) replaces any existing value for the key. data.delete(key) removes all values for a key. data.has(key) checks presence.
const data = new FormData();
data.append("tag", "html");
data.append("tag", "css");
console.log(data.getAll("tag")); // ["html", "css"]File Uploads
FormData handles files transparently: data.append("avatar", fileInput.files[0]). The server receives a multipart upload with the file's name and MIME type. This is the standard way to upload files with fetch in modern code.
Iterating
FormData is iterable: for (const [key, value] of data) { ... }. Use data.entries(), data.keys(), data.values() for specific iterations. Useful for logging, validation or building a JSON copy of the form.
Converting to JSON
To send as JSON instead of multipart: Object.fromEntries(data) produces a plain object — but loses duplicate keys. For correct duplicate handling, iterate entries and group manually. For pure JSON APIs, simpler to build the object directly without going through FormData.
Programmatic Population
Construct an empty FormData and append values manually: const data = new FormData(); data.append("title", title); data.append("file", file);. Useful when sending data that did not originate in a form (drag-dropped files, API responses, generated payloads).
Submitter Detection
If multiple submit buttons exist, pass the submitter as the second argument to FormData: new FormData(form, e.submitter). The submitter's name and value are included in the data — important for multi-action forms.
URLSearchParams Cousin
For application/x-www-form-urlencoded encoding (the default form encoding without files), construct a URLSearchParams from FormData: new URLSearchParams(data). Cheaper than multipart for plain text-only forms.
Common Pitfall
Setting fetch's Content-Type header explicitly to "multipart/form-data" breaks the upload — the browser can no longer add the required boundary. Omit Content-Type when sending FormData and let fetch handle it.
Knowledge Check
Why should you NOT set Content-Type manually when sending FormData with fetch?
Summary
FormData represents form contents and submits cleanly with fetch — including file uploads via multipart/form-data. Construct from a form element, append/set/delete entries, iterate as needed. Do not set Content-Type when sending — fetch generates the boundary automatically. Use URLSearchParams for text-only urlencoded forms.
Frequently asked questions
Is the “The FormData API” lesson free?
Yes — the full text of “The FormData API” is free to read here on the web, and the HTML Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the HTML Academy course, upgrade to CoddyKit PRO.
What will I learn in “The FormData API”?
Collect form data programmatically with the FormData interface. You practise HTML Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start HTML Academy?
No prior experience is required. HTML Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “The FormData API” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this HTML Academy lesson?
Yes. Every HTML Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.