FormData in JavaScript

FormData packs a form

A form often has more than one kind of value: text, email addresses, checkboxes, radio buttons, multi-select choices, submit buttons, and files. Reading each control by hand is possible, but it is easy to forget a rule. FormData lets the browser apply the same rules it uses for a real form submission.

The main move is new FormData(form). It creates an ordered collection of name → value entries. If you pass the clicked submit button as the second argument, newer browsers can include that button’s name=value too.

The browser does not pack every element inside a form. It collects successful controls: named controls that are not disabled, plus control-specific details such as checked checkboxes and selected options.

1form.addEventListener("submit", (event) => {2  event.preventDefault();3  const form = event.currentTarget;4  const submitter = event.submitter;5 6  // Newer browsers can include the clicked submit button.7  const data = new FormData(form, submitter);8  for (const [name, value] of data) {9    console.log(name, value instanceof File ? value.name : value);10  }11});

Try these predictions: a readonly input is included, a disabled input is skipped, an unchecked checkbox is skipped, a nameless input is skipped, checked checkboxes with the same name create repeated entries, and an empty text field is included as "". An enabled named file input with no selection appears in current browsers as an empty File entry.

FormData is not a plain object. Repeated names are allowed and common: checkbox groups use them, <select multiple> uses them, and your own code can create them with append.

1const fd = new FormData();Run2fd.append("topic", "forms");3fd.append("topic", "files");4fd.append("topic", "uploads");5console.log(fd.get("topic"));6console.log(fd.getAll("topic").join(", "));7console.log([...fd.entries()].map(([name, value]) => name + "=" + value).join(" | "));

Iteration is also part of the toolset. You can use for (const [name, value] of fd), fd.entries(), fd.keys(), fd.values(), or [...fd]. The order is the insertion order you created or the form’s control order.

A FormData object can be the body of a request. For a real upload you would write fetch("/profile", { method: "POST", body: formData }). Do not set the multipart Content-Type header yourself; the browser adds the boundary that matches the body.

1async function previewRequest(formData) {2  const request = new Request("/profile", {3    method: "POST",4    body: formData,5  });6 7  const parsed = await request.formData();8  const multipart = await new Request("/profile", {9    method: "POST",10    body: formData,11  }).text();12 13  return {14    parsed: [...parsed.entries()],15    startsWithMultipart: multipart.includes("form-data"),16  };17}

1const avatar = new Blob(["hello"], { type: "text/plain" });2const fd = new FormData();3fd.append("avatar", avatar, "avatar.txt");4const file = fd.get("avatar");5console.log(file.name);6console.log(file.size);7console.log(file.type);

Run the local request preview.

Files are local until you send them. Selecting a file in the playground only lets the page show its name, size, and type. Generated data can be added too: formData.append("avatar", blob, "avatar.png").

1const fd = new FormData();2fd.append("name", "Ada Lovelace");3fd.append("topic", "forms");4const body = new URLSearchParams(fd);5console.log(body.toString());

new URLSearchParams(formData) is useful for old-style URL-encoded bodies when every value is a string. It is the wrong shape for real files.

You may see Object.fromEntries(formData) in examples. It is convenient for truly single-value forms, but it silently collapses repeated names. Objects are single-slot organizers: the last value for a property overwrites earlier ones.

1function formDataToObject(fd) {2  const result = {};3  for (const [name, value] of fd) {4    if (Object.hasOwn(result, name)) {5      result[name] = Array.isArray(result[name])6        ? [...result[name], value]7        : [result[name], value];8    } else {9      result[name] = value;10    }11  }12  return result;13}14 15const fd = new FormData();16fd.append("topic", "forms");17fd.append("topic", "files");18fd.append("age", 12);19console.log(Object.fromEntries(fd).topic);20console.log(formDataToObject(fd).topic.join(" + "));21console.log(typeof formDataToObject(fd).age);

Also notice type conversion: non-Blob values become strings. If a form field represents a number, validate and convert it on purpose after you read it.

Where you will use this

Use FormData for profile forms, contact forms with attachments, import tools, checkout notes, support tickets, and admin dashboards where a submit event already gives you a form element. It pairs naturally with the Form events lesson’s preventDefault() and the Form validation lesson’s checkValidity() / reportValidity().

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  if (!form.reportValidity()) return;

  const data = new FormData(form, event.submitter);
  data.append("clientTimeZone", Intl.DateTimeFormat().resolvedOptions().timeZone);

  await fetch("/profile", {
    method: "POST",
    body: data,
  });
});

The next lesson, fetch & JSON, will focus on the request/response side. Here, the key is that the body is already prepared.

Common misconceptions

• “FormData is JSON.” It is an iterable form body, usually sent as multipart data.
• “Every input is included.” Disabled, nameless, unchecked checkbox/radio controls are skipped.
• “Repeated names are wrong.” They are how checkbox groups and multi-selects work.
• “Object.fromEntries is always safe.” It loses earlier repeated values.
• “I should set Content-Type.” Let the browser add the multipart boundary.

Key takeaways

• new FormData(form) collects named, enabled successful controls in form order.
• Repeated names are normal; use getAll or arrays when you need every value.
• append adds; set replaces; delete removes all values for a name.
• Values are strings or File/Blob objects. Convert numbers intentionally.
• Send FormData as a fetch body without hard-setting multipart Content-Type.

Final definition: FormData is an ordered, iterable package of form entries that follows browser submission rules and can be inspected, edited, converted, or sent.

Up next: fetch & JSON.

Want to revisit object conversion first? The published Object.keys, values & entries lesson pairs well with this one.