Codectionary / Developer documentation / JavaScript

FormData

FormData represents a set of key-value pairs, mirroring an HTML form's data, and is commonly used to send form submissions (including file uploads) via fetch() without manually constructing multipart request bodies. It can be created from an existing <form> element or built up manually.

Syntax

const formData = new FormData(formElement);
formData.append(key, value);

Examples

Creating FormData from a Form Element

Automatically capturing all fields from an existing HTML form.

// <form id="signupForm">
//   <input name="email" value="user@example.com">
//   <input name="password" value="secret123">
// </form>

const form = document.querySelector("#signupForm");
const formData = new FormData(form);

console.log(formData.get("email")); // "user@example.com"

Building FormData Manually

Constructing form data from scratch, including a file upload.

const formData = new FormData();
formData.append("username", "alice");
formData.append("avatar", fileInput.files[0]); // a File object from an <input type="file">

fetch("/api/upload", {
  method: "POST",
  body: formData // no need to set Content-Type manually - the browser sets it correctly
});

Best practices

  • Use FormData instead of JSON when a request includes file uploads - it correctly handles multipart/form-data encoding
  • Do not manually set the Content-Type header when sending FormData with fetch() - the browser sets the correct boundary automatically
  • Use formData.getAll() rather than get() when a form has multiple inputs sharing the same name (like checkboxes)
  • Construct FormData directly from a form element with new FormData(formElement) rather than manually appending every field, when the form already exists in the DOM

Runtime & versions

Browsers and JavaScript runtimes. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

ECMAScript specification

Specifications & further reading