Uploading files and multipart forms

Build a multipart body from files and fields, report progress honestly, validate before the bytes leave the browser, and know what resumable means.

Building the body

const fd = new FormData();

// values from a form, including file inputs
for (const [name, value] of new FormData(formEl)) fd.append(name, value);

// add a file that was never in a form
fd.append('avatar', file, 'avatar.png');      // third argument sets the filename
fd.append('alt', 'Team photo');
fd.append('tags', 'one');                     // repeated names become an array
fd.append('tags', 'two');

// never set Content-Type by hand: the browser must add the boundary
await fetch('/api/upload', { method: 'POST', body: fd });

// sending JSON instead of multipart, for comparison
await fetch('/api/upload-meta', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ alt: 'Team photo', size: file.size })
});

• Setting Content-Type: multipart/form-data yourself removes the boundary parameter and the server cannot parse the body. Let the browser set the header.
• FormData values are strings or blobs. A number becomes text, so the server must parse it, and a boolean becomes the string 'true'.
• A File from an input is a Blob with a name. You can append any blob, which is how canvas exports and generated PDFs are uploaded.
• A whole form can be passed to the constructor: new FormData(formEl) collects every named control, including hidden inputs.

Progress reporting

Upload progress is the one capability fetch still does not expose. If a progress bar matters, XMLHttpRequest remains the straightforward tool, or you can send the file in slices and count the slices that have completed.

function upload(file, onProgress) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();

    xhr.upload.onprogress = event => {
      if (event.lengthComputable) {
        onProgress(Math.round((event.loaded / event.total) * 100));
      }
    };
    xhr.upload.onload = () => onProgress(100);   // bytes sent, response still pending

    xhr.onload = () => (xhr.status >= 200 && xhr.status < 300)
      ? resolve(JSON.parse(xhr.responseText))
      : reject(new Error('HTTP ' + xhr.status));
    xhr.onerror = () => reject(new Error('network'));
    xhr.ontimeout = () => reject(new Error('timeout'));
    xhr.timeout = 120000;

    const fd = new FormData();
    fd.append('file', file);
    xhr.open('POST', '/api/upload');
    xhr.send(fd);
  });
}

• lengthComputable is false when the total size is unknown, which happens with a streaming body. Guard for it or your bar jumps to NaN.
• Upload progress reaching 100 percent means the bytes left the browser. The server may still be writing them to disk, so keep the UI in a pending state until the response arrives.
• A cancelled upload cannot be resumed. The request is gone, and the bytes already accepted by the server are unaccounted for.

Checks, drag and drop, and resumable uploads

const MAX = 20 * 1024 * 1024;
const OK_TYPES = ['image/png', 'image/jpeg', 'application/pdf'];

function check(file) {
  if (file.size > MAX) return 'File is larger than 20 MB';
  if (!OK_TYPES.includes(file.type)) return 'Unsupported type: ' + (file.type || 'unknown');
  return null;
}

dropzone.addEventListener('drop', event => {
  event.preventDefault();
  const files = Array.from(event.dataTransfer.files);
  for (const f of files) {
    const problem = check(f);
    if (problem) { showError(f.name + ': ' + problem); continue; }
    upload(f, percent => setProgress(f.name, percent)).catch(showError);
  }
});

// resumable: slice the file and upload numbered chunks
async function chunked(file, chunkSize = 5 * 1024 * 1024, uploadId) {
  for (let offset = 0; offset < file.size; offset += chunkSize) {
    const slice = file.slice(offset, Math.min(offset + chunkSize, file.size));
    await fetch('/api/upload/' + uploadId + '?offset=' + offset, {
      method: 'PUT',
      body: slice
    });
  }
}

FAQ

Related

Streaming and long-lived connections Building an API client layer

Last refreshed 2026-09-18.