Creating Custom Forms Using the JavaScript FormData API


While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

Building a form is easy to do as long as you don’t have an edge case. Then the bacon fat goes down the drain and your pipes are ruined. So you sometimes need some extra tools in your toolbelt to deal with it. The FormData API can be one of your tools.

The Core FormData API

FormData has a lot of features but the only method that works across all browsers is append. Let’s say we want to create a social application for people to share their bacon pictures. Here we’ll create a form that allows users to send a picture with a title and the author’s name. Our HTML markup will look like this:

<input type="text" name="author"  id="author-input" />
<input type="text" name="title" id="title-input" />
<input type="file" name="picture" id="picture-input" />
<button id="submit-button">SUBMIT</button>

To handle our data we can create the following code:

Module: bacon-form.js
const inputs = document.getElementsByTagName('input');
// This object will keep track of the changes of inputs
const applicationState = {
  title: "",
  author: "",
  picture: ""

document.getElementById('submit-button').onclick = async () => {
  // We create a new form object
  const form = new FormData();
  // we append each element to the form
  form.append('title', applicationState.title);
  form.append('author', applicationState.author);
  form.append('picture', applicationState.picture);

  const res = await fetch('https://postman-echo.com/post', {
    method: 'POST',
    mode: 'no-cors',
    body: form
  // ... Do something with the response

// The rest of this code is functional
// It is not directly related to FormData

// This for loop reflects input changes to the application's state
for (let i = 0; i < inputs.length; i++) {
  const input = inputs[i]
  const inputName = input.name

  input.onchange = (e) => {
    let value = e.target.value
    // updating the application state according to the input the user interacted with
    if (inputName === 'picture' && e.target.files[0]) {
    } else {
      applicationState[inputName] = value;
// setPicture takes a file reads it as a base64URL and assigns that value to application.picture
const setPicture = (file) => {
  const fr = new FileReader();
  // Reading the data and encoding it as base64 to send it to the server
  // When the data is done loading we assign it to picture
  fr.onloadend = (fileData) => {
    applicationState.picture = fileData.target.result;

If this is our input:

Input sample with author name Jack Misteli Picture Name Alligator Bacon and a picture file

Then we press the submit button we’ll roughly get the following request headers:

  "Accept-Encoding": "gzip, deflate, br",
  "Connection": "keep-alive",
  "Content-Length": "4369",
  "Content-Type": "multipart/form-data",
  "Host": "postman-echo.com",
  "Origin": "null",
  "Sec-Fetch-Mode": "no-cors",
  "Sec-Fetch-Site": "cross-site"

And the following body:

  "title": "Alligator Bacon",
  "author": "Jack Misteli",
  "picture": "data:text/javascript;base64,iVBORw0KGgoAA......."

Please note that FormData constructor can take form data as an argument. So you could do:

Module: regular-form.html
<form id="user-form">
  <input type="text" name="username">
  <input type="password" name="password">
  <input type="file" name="picture" id="picture-input"/>
  <input type="submit">
  document.getElementById('user-form').onsubmit = async function (e) {
    // here `this` is the user-form HTML element
    const form = new FormData(this);
    ///... send form to server

Another important gotcha, is that append does not overwrite a key if it already exists.

Module: double-bacon-form.js
const form = new FormData();
form.append('baconType', 'pork');
form.append('baconType', 'vegan');
// When you send your form it will look like this:
// {
//  baconType: pork
//  baconType: vegan

If you want to overwrite a key value you will have to use other functions.

Advanced Forms

The FormData constructor and the append method are available in all browsers. Most of the other methods are pretty self-descriptive:

  • FormData.has(key): Checks if the key exists in the form.
  • FormData.set(key, value): Changes the value associated to the key.
  • FormData.delete(key): Deletes the entry associated with the key.
  • FormData.get(key): Accesses the first value associated with the key.
  • FormData.getAll(key): Creates an array of all the values associated with a key.
  • FormData.keys(), FormData.values(), FormData.entries(): Iterators used to get all the keys, associated values or just entries of the FormData.

🥓 That’s it if you have any questions you can fire them up on Twitter with a link to the article and I’ll do my best to answer them!

Creative Commons License