XMLHttpRequest

Why learn XMLHttpRequest?

XMLHttpRequest, usually shortened to XHR, is the older browser API for making HTTP requests from JavaScript. Modern code often uses fetch, but XHR is still worth knowing because it appears in legacy apps, browser libraries, upload progress widgets, and old examples you will meet at work.

The name sounds huge, but the idea is small: create a request object, configure it, attach event handlers, then send it. Instead of returning a promise, XHR talks back through events and a numeric readyState.

You will run real requests in this lesson, but never to external URLs. The labs request this page, a missing same-origin path, generated blob: URLs, or a generated upload body. That keeps the lesson safe on a static site.

The lifecycle has two parts: the code you write and the events the browser fires. Your code runs in this order:

const xhr = new XMLHttpRequest();
xhr.open("GET", url);
xhr.timeout = timeoutMs;
xhr.addEventListener("readystatechange", record);
xhr.addEventListener("loadstart", record);
xhr.addEventListener("progress", record);
xhr.addEventListener("load", record);
xhr.addEventListener("error", record);
xhr.addEventListener("abort", record);
xhr.addEventListener("timeout", record);
xhr.addEventListener("loadend", record);
xhr.send();

The important surprise is that open() does not send the request. It stores the method and URL and changes readyState to OPENED. The trip begins only when send() runs.

1const xhr = new XMLHttpRequest();2xhr.open("GET", targetUrl);3xhr.timeout = target === "timeout" ? 1 : 0;4xhr.responseType = "text";5for (const name of ["loadstart", "progress", "load", "error", "abort", "timeout", "loadend"]) {6  xhr.addEventListener(name, logEvent);7}8xhr.addEventListener("readystatechange", logReadyState);9xhr.send();10if (target === "abort") setTimeout(() => xhr.abort(), 0);

Try “Missing page.” You should see a real HTTP status like 404, but the final event is still load. That is because XHR separates transport success from application success. A server saying “not found” is still a response. A revoked blob URL, timeout, abort, or CORS failure gives no usable HTTP response and normally leaves status at 0.

XHR has five ready states. They are exposed as numbers and as constants on XMLHttpRequest, such as XMLHttpRequest.DONE. People usually write the names in comments or logs because the numbers alone are hard to remember.

The event order is not “one event per ready state.” It is a mix: readystatechange for state changes, loadstart and progress for byte movement, one final outcome event (load, error, abort, or timeout), then loadend for cleanup.

1const xhr = new XMLHttpRequest();Run2xhr.open("GET", url);3xhr.timeout = timeoutMs;4xhr.addEventListener("readystatechange", record);5xhr.addEventListener("loadstart", record);6xhr.addEventListener("progress", record);7xhr.addEventListener("load", record);8xhr.addEventListener("error", record);9xhr.addEventListener("abort", record);10xhr.addEventListener("timeout", record);11xhr.addEventListener("loadend", record);12xhr.send();

XHR gives you several response tools. status is the numeric HTTP status. statusText is the browser’s text for that status when available. responseURL is the final URL after redirects. getAllResponseHeaders() returns the exposed response headers as one string.

For the body, prefer xhr.response. Its type depends on responseType. responseText is only safe for the default empty string or "text". If you set "json", "blob", "arraybuffer", or "document", read response instead.

1const xhr = new XMLHttpRequest();2xhr.open("GET", location.href);3xhr.responseType = selectedType; // "", "text", "json", "blob", "arraybuffer", or "document"4xhr.onload = () => {5  console.log(xhr.status);6  console.log(xhr.responseType || "text default");7  console.log(typeof xhr.response);8};9xhr.send();

The lab sends a generated text Blob to this same page with POST. A static site might reject the method after the browser tries to upload the body, and that is okay for the lesson: we are watching upload events, not storing a file.

1const xhr = new XMLHttpRequest();2xhr.open("POST", location.href);3xhr.upload.onprogress = (event) => {4  const percent = event.lengthComputable5    ? Math.round((event.loaded / event.total) * 100)6    : "unknown";7  console.log("uploaded", percent);8};9xhr.onloadend = () => console.log("finished", xhr.status);10xhr.send(generatedBlob);

The modern fetch API can show download progress through response streams, but it does not provide standard upload progress events like xhr.upload.onprogress. That single difference is the main reason many real upload widgets still use XHR.

XHR was designed before promises were the default style. You can wrap it so the outside of your app uses then, catch, and await, while the inside still listens to XHR events. This is the same idea you learned in the Promisification & promise-based APIs lesson.

1function xhrRequest(url, options = {}) {2  return new Promise((resolve, reject) => {3    const xhr = new XMLHttpRequest();4    xhr.open(options.method ?? "GET", url, true);5    xhr.responseType = options.responseType ?? "";6    xhr.onload = () => resolve({ status: xhr.status, response: xhr.response });7    xhr.onerror = () => reject(new TypeError("Network error"));8    xhr.ontimeout = () => reject(new DOMException("Timed out", "TimeoutError"));9    xhr.onabort = () => reject(new DOMException("Aborted", "AbortError"));10    for (const [name, value] of Object.entries(options.headers ?? {})) {11      xhr.setRequestHeader(name, value);12    }13    xhr.send(options.body ?? null);14  });15}

Notice the policy choice: this wrapper resolves for every HTTP response, including 404. It rejects for transport failures: network error, timeout, or abort. That mirrors how XHR events work and keeps status checking explicit.

const xhr = new XMLHttpRequest();
xhr.open("POST", "/api/messages", true);
xhr.responseType = "json";
xhr.timeout = 5000;
xhr.withCredentials = true;
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(JSON.stringify({ text: "Hello from XHR" }));

New request code usually starts with fetch because it is promise-based and works naturally with AbortSignal, request and response objects, and streams. XHR remains useful in three practical places:

• Upload progress: use xhr.upload.onprogress for file upload bars.
• Legacy code: older jQuery-style AJAX, older library versions, and browser support layers often wrap XHR.
• Fine-grained lifecycle debugging: ready states and events make old behavior easier to inspect.

Common misconceptions

• “XHR is gone.” It is old, not gone. Browsers still support it because the web depends on old pages continuing to work.
• “404 fires error.” No. HTTP error statuses still fire load. Check status.
• “status 0 means HTTP 0.” No. It means there is no usable HTTP response, often because of abort, timeout, network failure, or CORS.
• “progress always knows the total.” No. lengthComputable can be false, so show bytes without a percent.
• “responseText always works.” No. For non-text response types, use response.
• “Synchronous XHR is a handy shortcut.” It blocks the page and is deprecated on the main thread. Do not use it in new code.

Key takeaways

• XHR is old but still supported and common in legacy browser code.
• The sequence is open(), optional configuration and headers, then send().
• readyState moves from 0 to 4; loadend is the final cleanup event.
• HTTP error statuses fire load; network failures, aborts, and timeouts use their own events and often leave status at 0.
• Use xhr.upload.onprogress when you need real upload progress events.

Final definition: XMLHttpRequest is the browser’s older event-based HTTP request object, useful to understand for ready states, progress events, and legacy network code.

Up next: Cookies.