FormData in JavaScript

FormData packs a form

A form can hold many kinds of fields. A field is one thing the user fills in or picks. For example:

• text boxes and email boxes
• checkboxes and radio buttons
• lists where you can pick more than one option
• submit buttons
• file pickers

You could read each field by hand. But each kind of field has its own rules, and it is easy to forget one. FormData is a browser object that reads the whole form for you. It uses the same rules the browser uses when it sends a form.

You make one with new FormData(form). The result is a list of entries. Each entry is a pair: a name and a value. The name comes from the field's name attribute. The value is what the user typed or picked. The entries stay in the same order as the fields in the form.

You can also pass the submit button that was clicked as a second argument. Then newer browsers add that button's name and value as an entry too.

1const fd = new FormData();2fd.append("name", "Asha");3fd.append("drink", "tea");4console.log(fd.get("name"));5console.log([...fd]);

Line 1 makes an empty FormData object called fd. Here we don't pass a form, so it starts with no entries.

• Line 2 adds an entry with the name name and the value Asha. append means "add to the end".
• Line 3 adds a second entry: drink with the value tea.
• Line 4 reads the value stored under name, so it prints Asha.
• Line 5 copies every entry into an array with [...fd]. Each entry shows as a small [name, value] pair.

Line 5 is a good first check when a server says a field is missing. You see exactly what will be sent.

FormData only carries values. It does not check them. It doesn't know if an email is real, if a number is too big, or if a file is safe. Check the values before you send them. The server must check them again too.

The browser does not take every element inside a form. It takes a field only when all of these are true:

• The field has a name. The name becomes the entry's name.
• The field is not disabled. A disabled field is greyed out and switched off.
• A checkbox or radio button is checked.
• In a list where you can pick more than one option, an option is picked. Each picked option becomes its own entry.

The browser's rules call these fields successful controls. A control is just another word for a form field.

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});

Predict each result first, then press a submit button and check:

• A readonly field is included. The user can't change it, but it is still switched on.
• A disabled field is skipped.
• An unchecked checkbox is skipped.
• A field with no name is skipped.
• Two checked checkboxes with the same name give two entries with that name.
• An empty text box is included. Its value is the empty string, "".
• A file picker with a name but no file chosen is included in current browsers. Its value is an empty file.

1const publishButton = form.querySelector('[value="publish"]');2const data = new FormData(form, publishButton);3console.log(data.get("intent"));

A form can have several submit buttons, like "Save draft" and "Publish". Each has the same name, intent, but a different value.

• Line 1 finds the button whose value is publish.
• Line 2 passes that button as the second argument to new FormData.
• Line 3 reads the intent entry and prints publish.

Without that second argument, no button is included.

FormData is not a plain object. In a plain object, each name holds one value. In FormData, many entries can share one name. This happens often:

• A group of checkboxes uses one name for every box.
• A <select multiple> list, where you can pick more than one option, uses one name for every picked option.
• Your own code can add another entry with the same name using append.

1const fd = new FormData();2fd.append("topic", "forms");3fd.append("topic", "files");4console.log(fd.get("topic"));5console.log(fd.getAll("topic").join(" + "));

Lines 2 and 3 add two entries, both named topic. Line 4 uses get, which gives the first value for a name. It prints forms. Line 5 uses getAll, which gives an array of every value for a name. join(" + ") turns that array into one string, so it prints forms + files. Use getAll for checkbox groups and multi-pick lists.

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(" | "));

The table below lists the methods that are easy to mix up. Read each row as: "when I write this, this happens, and I use it for this."

You can also loop over the entries. Each of these walks through them:

• for (const [name, value] of fd) gives each name and value.
• fd.entries() gives each [name, value] pair.
• fd.keys() gives each name.
• fd.values() gives each value.
• [...fd] copies every pair into an array.

The order is the order you added the entries in. For new FormData(form), it is the order of the fields in the form.

1const fd = new FormData();2fd.append("topic", "forms");3fd.append("topic", "files");4console.log(fd.has("topic"));5fd.delete("topic");6console.log(fd.has("topic"));

Line 4 prints true, because two topic entries exist. Line 5 calls delete, which removes both of them, not just the first. So line 6 prints false.

The formdata event

An event is a signal the browser sends when something happens. Your code can listen for it. The browser sends a formdata event right after it builds a FormData object from a form. The event has a formData property, which is that same FormData object. So your listener can add entries to it.

1form.addEventListener("formdata", (event) => {2  event.formData.append("source", "formdata-event");3  console.log(event.formData.get("source"));4});5 6new FormData(form);

• Line 1 listens for the formdata event on the form.
• Line 2 adds an entry named source to event.formData.
• Line 3 reads that entry back.
• Line 6 builds a FormData object from the form. That sends the event, so the listener runs and prints formdata-event.

This is handy for an entry every form on a site should send, like an app version number or a form id.

A request is a message your page sends to a server. The body is the data inside that message. A FormData object can be the body. For a real upload you would write:

fetch("/profile", { method: "POST", body: formData })

fetch sends the request. POST means "I am sending data to you". The browser turns the FormData into a format called multipart form data. It keeps each entry in its own part, so text and files can travel together.

The parts are split by a boundary: a long random line of text the browser makes up. The browser also writes a Content-Type header that names the format and that boundary. A header is a short note sent along with the body. Do not write the Content-Type header yourself. You can't know the boundary, so the server can't split the parts.

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);

Press Build the request.

A file stays on your computer until you send it. When you pick a file in the playground, the page only shows its name, size, and type.

You can also make file data in code. A Blob is a chunk of raw data, like the contents of a file. A File is a Blob with a file name. To add a Blob as a file, give it a file name as the third argument: 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());

Some older servers want a simpler format called URL-encoded. It looks like the end of a web address: name=value pairs joined with &.

• Lines 2 and 3 add two text entries.
• Line 4 turns the FormData into a URLSearchParams object. That object holds the same pairs in URL-encoded form.
• Line 5 prints the text. A space becomes +, so it prints name=Ada+Lovelace&topic=forms.

Use this only when every value is a string. It has no way to carry a real file.

You may see Object.fromEntries(formData) in examples. It turns the entries into a plain object. That works well when every name has one value.

But a plain object has room for only one value per name. If two entries share a name, the second one overwrites the first. The first value is lost, and you get no warning.

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);

The helper function at the top of the playground code keeps every value:

• The first time it sees a name, it stores the value as it is.
• When it sees the same name again, it turns that property into an array and adds the new value.

Notice one more thing: age is a string in both results. FormData turns every value that is not a file into a string. If a field holds a number, check it and turn it back into a number yourself.

1const fd = new FormData();2fd.append("age", 12);3const age = Number(fd.get("age"));4console.log(age);5console.log(typeof age);

• Line 2 adds the number 12. FormData stores it as the text "12".
• Line 3 reads the text and turns it into a number with Number(...).
• Line 4 prints 12.
• Line 5 uses typeof, which tells you a value's type. It prints number.

Still check the value first. Number gives NaN ("not a number") when the text is not a number.

1const fd = new FormData();2fd.append("name", "Asha");3fd.append("topic", "forms");4fd.append("topic", "files");5console.log([...fd.keys()].join(", "));

keys() gives every name, even repeated ones. So line 5 prints name, topic, topic. Use it to check which names you are about to send.

Where you will use this

Use FormData whenever a submit event gives you a form. For example:

• profile forms with a photo
• contact forms and support tickets with attachments
• tools that import a file
• checkout notes and admin dashboards

It goes well with two earlier lessons. From Form events, you use preventDefault() to stop the page from reloading. From Form validation, you use checkValidity() or reportValidity() to check the fields first.

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,
  });
});

• Line 2 stops the page from reloading.
• Line 3 checks the fields. If one is wrong, the browser shows a message and the function stops.
• Line 5 builds the FormData from the form and the clicked button.
• Line 6 adds one more entry: the user's time zone, such as Asia/Kolkata.
• Lines 8 to 11 send the FormData as the request body.

The next lesson, fetch & JSON, is about sending requests and reading the answers. Here, the body is already ready to send.

Common misconceptions

• “FormData is JSON.” It is its own kind of object. The browser usually sends it as multipart form data, not JSON.
• “Every field is included.” Disabled fields, fields with no name, and unchecked checkboxes and radio buttons are skipped.
• “Two entries with one name is a mistake.” It is normal. Checkbox groups and multi-pick lists work this way.
• “Object.fromEntries is always safe.” When a name repeats, it keeps only the last value.
• “I should set Content-Type myself.” Let the browser set it. Only the browser knows the boundary.

The table below pairs each mistake with what is really true. The last column says how to see it for yourself.

Key takeaways

• new FormData(form) takes every field that has a name and is not disabled, in form order. Checkboxes and radio buttons must be checked.
• Many entries can share one name. Use getAll when you need every value.
• append adds. set replaces. delete removes every entry with that name.
• A value is a string or a file. Turn numbers back into numbers yourself.
• Send FormData as the fetch body. Don't write the Content-Type header yourself.

Final definition: FormData is a list of name and value entries, in order. The browser fills it from a form using its own rules. You can read it, change it, turn it into other shapes, or send it.

Up next: fetch & JSON, where you send requests and read the answers.

Want to practice turning entries into objects first? See the Object.keys, values & entries lesson.