How to use the FormData object

The FormData object is used to store form input fields values.

It’s especially useful when you need to send files to the server.

It’s probably the only time you’ll actually need it.

Here is one example of using FormData to send the content of a file using fetch.

We have an input field:

<input type="file" id="fileUpload" />

We attach a change event handler on it:

document.querySelector('#fileUpload').addEventListener('change', (event) => {
  handleImageUpload(event)
})

and we manage the bulk of our logic in the handleImageUpload() function:

const handleImageUpload = (event) => {
  const files = event.target.files
  const formData = new FormData()
  formData.append('myFile', files[0])

  fetch('/saveImage', {
    method: 'POST',
    body: formData,
  })
    .then((response) => response.json())
    .then((data) => {
      console.log(data)
    })
    .catch((error) => {
      console.error(error)
    })
}

In this example we POST to the /saveImage endpoint.

You could send more data too by appending it to the formData object.

In the server-side, to access the file data you must parse the request as a multipart form.

See for example how to upload files in a Next.js form

The FormData object you create has many useful methods:

• append() to add a value to the object, with the specified key. If the key already exists, the value is added to that key, without eliminating the first one
• delete() deletes a key value pair
• entries() gives an Iterator object you can loop to list the key value pairs hosted
• get() get the value associated with a key. If more than one value was appended, it returns the first one
• getAll() get all the values associated with a key
• has() returns true if there’s a key
• keys() gives an Iterator object you can loop to list the keys hosted
• set() to add a value to the object, with the specified key. If the key already exists, the value is replaced
• values() gives an Iterator object you can loop to list the values hosted

FormData was introduced with the XMLHttpRequest 2 spec, and it works in every modern browser. As you saw above, you pass it straight to fetch() as the request body, and the browser sets the multipart/form-data boundary for you.

The one reason to still send it through XHR is upload progress events, which fetch() does not give you.

See how to handle images uploaded server-side.

Want me to talk about your product? You can sponsor this site.