📦 FormData API and Processing

What FormData Is

The FormData interface builds a set of key/value pairs representing form fields and their values, ready to be sent with fetch or XMLHttpRequest. It shines in four situations:

• AJAX submissions — send a form with no page reload.
• File uploads — <input type="file"> values come along automatically.
• Dynamic data — assemble fields in code, not just from the DOM.
• Multipart data — mix text and binary files in a single request.

💡 The courier analogy. FormData is a digital courier service. Instead of mailing a paper form, it neatly boxes up all your fields — including bulky attachments like files — labels the package correctly, and delivers it to the server, handling the fiddly logistics (encoding, boundaries) for you.

Creating FormData Objects

From a form element

The most common route — pass a <form> and every named control is captured automatically, files included:

const form = document.querySelector('#profile-form');
const data = new FormData(form);

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

Empty, then filled programmatically

const data = new FormData();
data.append('username', 'raydev');
data.append('email', 'ray@example.com');
data.append('joinedAt', new Date().toISOString());

// Attach a file straight from an input
const fileInput = document.querySelector('input[type="file"]');
data.append('avatar', fileInput.files[0]);

This is ideal when your data doesn't map one-to-one to visible form fields, or when you build a request from several user interactions — like an e-commerce configurator that appends each chosen option as the user clicks.

The FormData Methods

A handful of methods cover everything. The one distinction that trips people up is append versus set.

const data = new FormData();

data.append('tag', 'js');
data.append('tag', 'css');     // now 'tag' holds TWO values
data.getAll('tag');            // ['js', 'css']

data.set('tag', 'html');       // replaces both
data.getAll('tag');            // ['html']

// FormData is iterable — loop straight over it
for (const [key, value] of data) {
  console.log(`${key} = ${value}`);
}

Multi-value fields work for free

Checkbox groups and <select multiple> that share a name are gathered automatically — no special code required:

<input type="checkbox" name="interests" value="sports">
<input type="checkbox" name="interests" value="music">
<select name="countries" multiple> … </select>

const data = new FormData(form);
data.getAll('interests');  // e.g. ['sports', 'music']
data.getAll('countries');  // e.g. ['us', 'ca']

Submitting with fetch

Sending FormData is a one-liner body. The golden rule bears repeating: do not set a Content-Type header. The browser sets multipart/form-data with the correct boundary string automatically; setting it yourself corrupts the request.

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const button = form.querySelector('button[type="submit"]');
  button.disabled = true;
  button.textContent = 'Submitting…';

  try {
    const res = await fetch('/api/submit', {
      method: 'POST',
      body: new FormData(form),   // no Content-Type header!
    });
    if (!res.ok) throw new Error(`Server ${res.status}`);
    const result = await res.json();
    console.log('Success:', result);
    form.reset();
  } catch (err) {
    console.error('Submit failed:', err);
  } finally {
    button.disabled = false;
    button.textContent = 'Submit';
  }
});

Upload progress

fetch still can't report upload progress natively, so for a progress bar the venerable XMLHttpRequest remains the practical choice thanks to its upload.onprogress event:

function uploadWithProgress(formData, onProgress) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', '/api/upload');

    xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) onProgress((e.loaded / e.total) * 100);
    });

    xhr.addEventListener('load', () =>
      xhr.status === 200 ? resolve(xhr.responseText) : reject(xhr.statusText)
    );
    xhr.addEventListener('error', () => reject('Network error'));
    xhr.send(formData);
  });
}

// Usage
uploadWithProgress(new FormData(form), (percent) => {
  progressBar.value = percent;
});

Converting FormData to JSON

Some APIs want JSON, not multipart form data. For flat, text-only forms the conversion is a two-line idiom using Object.fromEntries:

const data = new FormData(form);
const json = Object.fromEntries(data.entries());

await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(json),
});

To preserve multi-value keys, build the object manually:

function formDataToObject(formData) {
  const obj = {};
  for (const [key, value] of formData) {
    if (key in obj) {
      obj[key] = [].concat(obj[key], value);  // grow into an array
    } else {
      obj[key] = value;
    }
  }
  return obj;
}

Processing on the Server

Multipart FormData looks the same on the wire regardless of backend; each ecosystem has its idiomatic way to read it. Here is the same profile-upload endpoint in three stacks.

Node.js + Express (multer)

const express = require('express');
const multer = require('multer');

const app = express();
const upload = multer({ dest: 'uploads/' });

// upload.single() parses one file field; text fields land in req.body
app.post('/api/profile', upload.single('avatar'), (req, res) => {
  res.json({
    message: 'Saved',
    user: req.body,     // { username, email }
    file: req.file,     // { filename, size, mimetype, … }
  });
});

app.listen(3000);

PHP

<?php
header('Content-Type: application/json');

$username = $_POST['username'] ?? '';
$email    = $_POST['email'] ?? '';

if (isset($_FILES['avatar']) && $_FILES['avatar']['error'] === UPLOAD_ERR_OK) {
    $name = basename($_FILES['avatar']['name']);
    move_uploaded_file($_FILES['avatar']['tmp_name'], "uploads/$name");
}

echo json_encode(['message' => 'Saved', 'user' => $username]);

Python + Flask

from flask import Flask, request, jsonify
from werkzeug.utils import secure_filename
import os

app = Flask(__name__)

@app.route('/api/profile', methods=['POST'])
def profile():
    username = request.form.get('username')
    email = request.form.get('email')

    file = request.files.get('avatar')
    if file and file.filename:
        filename = secure_filename(file.filename)
        file.save(os.path.join('uploads', filename))

    return jsonify(message='Saved', user=username)

Hands-on Exercise

const input = document.querySelector('#avatar');
const preview = document.querySelector('#preview');
const bar = document.querySelector('#bar');
const status = document.querySelector('#status');
const form = document.querySelector('#upload-form');

const MAX = 2 * 1024 * 1024; // 2 MB

input.addEventListener('change', () => {
  const file = input.files[0];
  if (!file) return;
  if (!file.type.startsWith('image/')) {
    status.textContent = 'Please choose an image file.';
    input.value = '';
    return;
  }
  if (file.size > MAX) {
    status.textContent = 'That image is over 2 MB.';
    input.value = '';
    return;
  }
  status.textContent = '';
  preview.src = URL.createObjectURL(file);
  preview.onload = () => URL.revokeObjectURL(preview.src);
});

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  if (!input.files[0]) return;
  try {
    await uploadWithProgress(new FormData(form), (p) => { bar.value = p; });
    status.textContent = '✅ Uploaded!';
  } catch (err) {
    status.textContent = '⚠️ Upload failed. Try again.';
  }
});

Best Practices & Security

Summary & Quiz

📚 Further Reading

• MDN — FormData
• MDN — Using the Fetch API
• JavaScript.info — FormData

🚀 What's Next?

You can now collect, package, and send any form. Next we move from sending data to keeping it in the browser: localStorage and sessionStorage for saving drafts, preferences, and session state between visits.