XMLHttpRequest

Why learn XMLHttpRequest?

An HTTP request is a message your page sends to a server. It asks for data, or it sends data. XMLHttpRequest is an object the browser gives you for sending HTTP requests from JavaScript. People shorten its name to XHR.

XHR is the older way to send requests. Newer code usually uses fetch(). You still need to know XHR, because you will meet it in these places:

• Older apps that were written before fetch() existed.
• Older libraries, such as old jQuery code, that use XHR inside.
• Upload progress bars, because XHR can report how much of a file has been sent.

The name sounds big, but the steps are small:

1. Create a request object.
2. Open it with a method, such as GET, and an address (a URL).
3. Add listeners for its events. A listener is a function that runs when its event happens.
4. Send it.

XHR doesn't give you a promise. It tells you what happened in two ways: through events, and through a number called readyState.

In this lesson you will send real requests, but only to this website. The demos ask for one of these:

• This page.
• A page on this site that doesn't exist.
• A blob: URL. A blob URL points at data that the page made itself, so no other server is involved.

One more word before we start. A header is a short line of extra information sent with a request or an answer, such as the type of data inside it.

A lifecycle is the list of steps something goes through, from start to end. A request has two sides:

• The code you write.
• The events the browser fires back. An event is a signal, such as "the request started" or "the answer arrived".

Here is the code side, in the order it runs:

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();

1. Line 1 creates the request object.
2. Line 2 calls open() with the method GET and the address in url.
3. Line 3 sets a time limit, in milliseconds, with timeout.
4. Lines 4 to 11 add one listener for each event. Every listener here is record, which prints the event's name.
5. Line 12 calls send(), which starts the request.

The next example is a tiny fake request object. It shows the order of the calls without using the network. It uses status, the HTTP status code. That is a number the server sends back, such as 200 for "OK" or 404 for "Not Found".

const events = [];
const xhr = {
  status: 0,
  open(method, url) { events.push("open " + method + " " + url); },
  send() { this.status = 200; events.push("load " + this.status); },
};
xhr.open("GET", "/profile");
xhr.send();
console.log(events.join(" -> "));

1. Line 4: open() saves the text open GET /profile.
2. Line 5: send() sets status to 200 and saves load 200.
3. Lines 7 and 8 call open(), then send().
4. Line 9 prints open GET /profile -> load 200.

A 404 and a broken connection are not the same thing:

• A 404 means the server answered. Its answer was "not found".
• A broken connection means no answer came back at all.

XHR fires a different event for each. load means an answer arrived, whatever its status. error means no answer reached your code. This small model prints the two cases without contacting a server:

function describeOutcome(status, eventName) {
  if (eventName === "load") return "load with status " + status;
  return eventName + " with status " + status;
}

console.log(describeOutcome(404, "load"));
console.log(describeOutcome(0, "error"));

Line 6 prints load with status 404. Line 7 prints error with status 0.

One more surprise: open() does not send anything. It only saves the method and the URL, and changes readyState to 1, which is named OPENED. The request leaves 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 get a real 404 status, but the outcome event is still load. That is because XHR answers two different questions:

• Did an answer arrive? load says yes.
• Did the server give you what you asked for? Only status tells you that.

Some requests get no answer that your code can read. In these cases status usually stays 0:

• A revoked blob URL: the page has already thrown that data away.
• A timeout: the time limit ran out.
• An abort: your code stopped the request.
• A CORS failure: another site didn't allow your page to read its answer.

readyState is a number on the request object. It tells you which step the request has reached. It goes from 0 to 4. Each number also has a name, kept on XMLHttpRequest. For example, XMLHttpRequest.DONE is 4. People write the names in logs, because the numbers alone are hard to remember.

The answer from a server has two parts:

• The headers: short lines of information, including the status.
• The body: the main content, such as a page or some data.

In the table, each row is one step. Read it from left to right: the number, its name, what it means, and what you can read at that step.

const names = ["UNSENT", "OPENED", "HEADERS_RECEIVED", "LOADING", "DONE"];
for (const state of [0, 1, 2, 3, 4]) {
  console.log(state + " " + names[state]);
}

The loop goes through the numbers 0 to 4. For each one, it prints the number and its name, from 0 UNSENT to 4 DONE.

The events don't match the steps one to one. Here is the order they fire in:

1. readystatechange fires each time readyState changes.
2. loadstart fires once, when the request starts.
3. progress fires while bytes of the answer arrive. A byte is one small piece of data.
4. Exactly one outcome event fires: load, error, abort, or timeout.
5. loadend fires last, every time. It is the place to clean up, such as hiding a loading spinner.

The readystatechange events happen in between the others, as the number goes up. Step through the cases below to see the full order.

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();

When the answer arrives, XHR gives you these properties and methods to read it:

• status is the HTTP status number, such as 200 or 404.
• statusText is the short text for that status, such as "OK", when the browser has it.
• responseURL is the final address of the answer. It can be different from the address you asked for, if the server sent you on to another address. That is called a redirect.
• getAllResponseHeaders() returns the headers your code may see, as one string.

To read the body, use xhr.response. The kind of value it holds depends on responseType. You set responseType before you send:

• "" (empty, the default) or "text": a string.
• "json": a JavaScript value made from JSON text.
• "blob": a Blob, which is raw data like a file.
• "arraybuffer": an ArrayBuffer, which is raw bytes.
• "document": an HTML or XML page, already turned into a Document object.

There is also an older property, responseText. It only works when responseType is "" or "text". For every other type, read response.

const fakeResponse = { name: "Asha", items: 2 };
const responseType = "json";
console.log(responseType + ": " + fakeResponse.name);
console.log("items: " + fakeResponse.items);

This example doesn't send a request. Line 1 builds the object that a JSON answer would turn into. Line 3 prints json: Asha, and line 4 prints items: 2. With a real request, you would read the same fields from xhr.response.

With a real request, responseType = "json" asks the browser to turn the JSON text into a value before onload runs. If the text isn't valid JSON, response is null. So check for null before you read a property.

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();

In the table, each row is one property or method. The middle column says what it is for. The last column says what to look out for.

Uploading means sending data from your browser to a server, such as a photo. Download progress tells you that bytes are arriving. Upload progress tells you that bytes are leaving. XHR has an object just for upload events: xhr.upload.

The demo below sends a made-up text Blob to this page with POST. POST is the HTTP method for sending data. This website doesn't accept uploads, so the server may answer with an error after the upload. That is fine: we only want to watch the upload events.

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);

fetch() can show download progress, by reading the answer piece by piece. But it has no standard upload progress events like xhr.upload.onprogress. That is the main reason many upload bars still use XHR.

A progress event has three properties:

• loaded: the bytes sent so far.
• total: the full size in bytes, if it is known.
• lengthComputable: true when the full size is known, and false when it isn't.

function progressMessage(event) {
  if (!event.lengthComputable) return event.loaded + " bytes uploaded";
  return Math.round((event.loaded / event.total) * 100) + "% uploaded";
}

console.log(progressMessage({ loaded: 240, total: 400, lengthComputable: true }));
console.log(progressMessage({ loaded: 240, total: 0, lengthComputable: false }));

1. Line 2: if the total isn't known, return the bytes sent so far.
2. Line 3: otherwise, work out the percent and round it.
3. Line 6 passes 240 of 400 bytes with the total known, so it prints 60% uploaded.
4. Line 7 passes 240 bytes with no known total, so it prints 240 bytes uploaded.

Only work out a percent when lengthComputable is true. If you divide by an unknown total, you get a number that looks exact but is wrong. Show the bytes sent instead, or a bar that moves without a percent.

XHR is older than promises. A promise is an object that will later hold a result or an error. You read it with then, catch, or await.

You can put an XHR request inside a promise. Then the rest of your app uses await, while the inside still listens to XHR events. You saw this idea 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}

1. Line 2 makes a new promise. Calling resolve gives it a result. Calling reject gives it an error.
2. Lines 3 to 5 create the request, open it, and set its responseType.
3. Line 6: when load fires, the promise gets the status and the response.
4. Lines 7 to 9: when error, timeout, or abort fires, the promise gets an error.
5. Lines 10 to 12 add each header from options.headers.
6. Line 13 sends the request, with a body if there is one.

Look at what this wrapper does with a 404. It still calls resolve, because a 404 fires load. It only calls reject when no answer came: a network error, a timeout, or an abort. So your code still has to check status itself.

function isHttpSuccess(status) {
  return status >= 200 && status < 300;
}

console.log(isHttpSuccess(204));
console.log(isHttpSuccess(404));

A status from 200 to 299 means success. Line 5 prints true for 204. Line 6 prints false for 404.

So a 404 resolves the wrapper's promise, but fails this check. A network error rejects the promise, and there is no status to check.

All setup goes after open() and before send():

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" }));

1. Line 2 opens a POST request to /api/messages.
2. Line 3 asks for the answer as JSON.
3. Line 4 sets a time limit of 5000 milliseconds, which is 5 seconds.
4. Line 5 sends cookies and login details with the request, with withCredentials.
5. Line 6 adds a header that says the body is JSON.
6. Line 7 sends the body, a JSON string.

New request code usually starts with fetch(). Here is why:

• It returns a promise, so it works with await.
• It can be cancelled with an AbortSignal, an object that tells a request to stop.
• It can read an answer piece by piece. This is called a stream.

XHR is still useful in three places:

• Upload progress: use xhr.upload.onprogress for file upload bars.
• Older code: old jQuery request code and older libraries often use XHR inside.
• Finding bugs step by step: the ready states and events show each step of a request, so you can see where it went wrong.

Common misconceptions

• "XHR is gone." It is old, but not gone. Browsers still support it, so that old pages keep working.
• "A 404 fires error." No. A 404 is still an answer, so load fires. Check status to see if it worked.
• "Status 0 is a real HTTP status." No. It means no answer your code can read. Common causes are an abort, a timeout, a network failure, or CORS.
• "Progress always knows the total." No. lengthComputable can be false. Then show the bytes sent, without a percent.
• "responseText always works." No. It only works for text. For other response types, use response.
• "Synchronous XHR is a handy shortcut." No. It freezes the page, and browsers have deprecated it on the main page. Don't use it in new code.

Key takeaways

• XHR is old, but browsers still support it, and older code uses it a lot.
• The order is open(), then any setup and headers, then send().
• readyState goes from 0 to 4. loadend is always the last event, so clean up there.
• A 404 or 500 answer still fires load. A network failure, an abort, or a timeout fires its own event, and status usually stays 0.
• Use xhr.upload.onprogress when you need real upload progress.

Final definition: XMLHttpRequest is the browser's older object for sending HTTP requests. It tells you what happens through events. It's worth knowing for its ready states, its progress events, and the older code that still uses it.

Up next: Cookies.