Uploads with real progress: what to measure

Upload progress comes from the bytes the browser says it has sent, through the upload.onprogress event on XMLHttpRequest: a timer that ticks measures nothing.

Why fetch does not expose it

With fetch the request body is an opaque stream and no send-progress event exists: you can read the download in chunks, not the upload. Use XMLHttpRequest or a library that wraps it, such as axios, released under the MIT licence.

The code that measures

function carica(file, onProgress) {
  const body = new FormData();
  body.append("file", file);
  return axios.post("/api/upload", body, {
    onUploadProgress: (e) => onProgress(Math.round((e.loaded / e.total) * 100)),
  });
}

The percentage is loaded divided by total: it measures the bytes sent, not the processing of the file on the server.

The traps

• 100% is not done: the send is complete, and the response may arrive much later.
• total at zero: with Transfer-Encoding: chunked the total is missing and the bar stays indeterminate.
• Several files: add the bytes of every file, never the percentages.
• Cancelling: AbortController stops the request and the event stops arriving.

Installation

npm i axios

The install adds a single MIT dependency; onUploadProgress works in browsers that expose XMLHttpRequest, which leaves out tests on jsdom.

Live records in the catalogue

Three file upload components: file-upload-card, file-upload-2 and avatar-uploader. To browse by category start from 111,985 components.

The limitation

The bar measures the send, not the outcome: when the server queues the file, the reader sees 100% and a wait. Honest progress needs a second phase, with a job id to poll.

Where to continue

The route handler for files is in uploads with Next.js; the comparison of the two field schemes is in controlled and uncontrolled forms; the framework choice is in Vue 3 vs React.