function makeRequest() { var url = 'data.json'; var onLoadHandler = function(event){ // Parse the JSON and build a list. } var onTimeOutHandler = function(event){ var content = document.getElementById('content'), p = document.createElement('p'), msg = document.createTextNode('Just a little bit longer!'); p.appendChild(msg); content.appendChild(p); // Restarts the request. event.target.open('GET',url); // Optionally, set a longer timeout to override the original. event.target.timeout = 6000; event.target.send(); } var xhr = new XMLHttpRequest(); xhr.open('GET',url); xhr.timeout = 3000; xhr.onload = onLoadHandler; xhr.ontimeout = onTimeOutHandler; xhr.send(); } window.addEventListener('DOMContentLoaded', makeRequest, false);

If more than three seconds pass before response data is received, we'll notify the user that the request is taking too long. Then we'll initiate a new request with a longer timeout limit (view an XHR timeouts demo). Resetting the timeout limit within the timeout event handler isn't strictly necessary. We've done so for this URL to avoid a loop since its response will always exceed the initial timeout value.

To date, Chrome and Safari do not support XHR timeouts. Opera, Firefox, and Internet Explorer 10 do. Internet Explorer 8 and 9 also support timeouts on the XDomainRequest object.

Requesting data from another domain

One limitation of early XHR was the same-origin policy. Both the requesting document and the requested document had to originate from the same scheme, host, and port. A request from http://www.foo.example to http://www.foo.example:5050 — a cross-port request — would cause a security exception (except in older versions of Internet Explorer, which allowed cross-port requests).

Now XMLHttpRequest supports cross-origin requests, provided cross-origin resource sharing (CORS) is enabled.

Internet Explorer 8 and 9 do not support cross-domain XMLHttpRequest , though IE10 does. Instead, Internet Explorer 8 and 9 use the XDomainRequest object, which works similarly.

Cross-origin requests look just like same-origin requests, but use a full URL instead of a relative one:

var xhr = new XMLHttpRequest(); var onLoadHandler = function(event) { /* do something with the response */ } xhr.open('GET','http://other.server/and/path/to/script'); xhr.onload = onLoadHandler; xhr.send();

The critical difference is that the target URL must permit access from the requesting origin by sending an Access-Control-Allow-Origin response header.

An overview of cross-origin resource sharing

For an in-depth look at CORS, read DOM access control using cross-origin resource sharing. Here we'll just cover two headers: the Origin request header, and the Access-Control-Allow-Origin response header.

The origin header

When making a cross-origin XHR request, Opera and other browsers will automatically include an Origin header — see below for an example:

GET /data.xml HTTP/1.1 User-Agent: Opera/9.80 (Macintosh; Intel Mac OS X 10.6.8; U; en) Presto/2.10.289 Version/12.00 Host: datahost.example Accept: text/html, application/xml;q=0.9, application/xhtml+xml, image/png, image/webp, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1 Accept-Language: en,en-US Accept-Encoding: gzip, deflate Referer: http://requestingserver.example/path/to/askingdocument.html Connection: Keep-Alive Origin: http://requestingserver.example

Origin typically contains the scheme, host name, and port of the requesting document. It is not an author request header, meaning it can’t be set or modified using the setRequestHeader() method; user agents will ignore it if you try. Its entire purpose is to inform the target server about the origins of this request. Bear in mind that there is no trailing slash.

The Access-Control-Allow-Origin response header

The Access-Control-Allow-Origin header is sent by the target server in response to a cross-origin request. It tells the user agent whether access should be granted to the requesting origin. DOM operations involving a cross-origin XHR request will not be completed unless the requested URL allows it. An example follows:

HTTP/1.1 200 OK Date: Fri, 27 May 2011 21:27:14 GMT Server: Apache/2 Last-Modified: Fri, 27 May 2011 19:29:00 GMT Accept-Ranges: bytes Content-Length: 1830 Keep-Alive: timeout=15, max=97 Connection: Keep-Alive Content-Type: application/xml; charset=UTF-8 Access-Control-Allow-Origin: *

In this case, we’re using a wild card (*) to allow access from any origin. This is fine if you are offering a public-facing API . For most other uses, you'll want to set a more specific origin value.

Sending user credentials with cross-domain requests

There may be occasions when you will want to send cookie data along with your cross-domain request. That’s where the withCredentials attribute comes in handy. It is a boolean attribute that alerts the browser that it should send user credentials along with the request. By default, the credentials flag is false . In the code below, let’s assume that our request is going from http://foo.example to http://other.server:

var xhr = new XMLHttpRequest(); var onLoadHandler = function(event) { doSomething(event.target.responseText); } xhr.open('GET','http://other.server/and/path/to/script'); xhr.withCredentials = true; xhr.onload = onLoadHandler; xhr.send();

In our XHR credentials demo, we are using a counter cookie to track the number of visits. If you examine the request and response data (you can do this with Dragonfly' Network panel), you will see that the browser is sending request cookies and receiving response cookies. Our server-side script will return text containing the new visit count, and update the value of the cookie.

Keep the following in mind when making requests with credentials:

withCredentials is only necessary for cross-origin requests.

is only necessary for cross-origin requests. The Access-Control-Allow-Origin header of the requested URI can not contain a wildcard (*).

header of the requested URI can not contain a wildcard (*). The Access-Control-Allow-Credentials header of the requested URI must be set to true .

header of the requested URI must be set to . Only a subset of response headers will be available to getAllRequestHeaders() , unless the Access-Control-Expose-Headers header has been set.

Same-origin requests will ignore the credentials flag. A wildcard Access-Control-Allow-Origin header value will cause an exception. If the value of Access-Control-Allow-Credentials is false , cookies will still be sent and received, however they will not be available to the DOM.

Sending data as key-value pairs with FormData objects

In previous implementations, data sent via XHR had to be submitted as a string, either using URL-encoding, or JSON (with JSON.stringify() ). The example below uses URL-encoding:

var msg = 'field1=foo&field2=bar'; var xhr = new XMLHttpRequest(); xhr.open('POST','/processing_script'); xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded"); xhr.send(msg);

Now, we can use the FormData object, and its ordered, key-value pairs. The syntax offers three benefits:

Scripts are more readable

Data is sent in key-value pairs, as with regular HTML forms

FormData objects are sent with multipart/form-data encoding, making it possible to use XHR for sending binary data.

If you've ever worked with URLVariables in ActionScript 3.0, FormData will feel familiar. First create a FormData object, then add data using the append() method. The append() method requires two parameters: key and value . Each FormData key becomes a variable name available to your server-side script. An example follows:

var xhr = new XMLHttpRequest(); var dataToSend = new FormData(); // create a new FormData object xhr.open('POST','/processing_script'); dataToSend.append('name','Joseph Q. Public'); // add data to the object dataToSend.append('age','52'); dataToSend.append('hobby','knitting'); xhr.send(dataToSend); // send the object

We’ve passed the FormData object as the argument of the send() method: xhr.send(dataToSend) . We did not set a Content-Type header on our XMLHttpRequest object. Let's take a look at the request headers sent by Opera:

POST /processing_script HTTP/1.1 User-Agent: Opera/9.80 (Macintosh; Intel Mac OS X 10.6.8) Presto/2.10.289 Version/12.00 Host: datahost.example Accept: text/html, application/xml;q=0.9, application/xhtml+xml, image/png, image/webp, image/jpeg, image/gif, image/x-xbitmap, */*;q=0.1 Accept-Language: en,en-US Accept-Encoding: gzip, deflate Expect: 100-continue Referer: http://datahost.example/upload/ Connection: Keep-Alive Content-Length: 4281507 Content-Type: multipart/form-data; boundary=----------J2GMKTyAkjRjNgFzKv3VBJ

Opera has added the Content-Type header for us because we are using a FormData object. Other browsers do the same.

Using FormData with an HTML form

You can also send the values from a form with FormData , by passing the form to the FormData object as shown below (view an XHR FormData demo).

var submitHandler = function(event) { var dataToSend = new FormData(event.target), xhr = new XMLHttpRequest(); xhr.open('POST','/processing_script'); xhr.send(dataToSend); } var form = document.getElementById('myform'); form.addEventListener('submit',submitHandler,false);

FormData is still untrusted data. Treat input from a FormData object as you would any other kind of form submission.

Monitoring data transfers with progress events

XMLHttpRequest now provides progress event attributes that allow us to monitor data transfers. Previously, we would listen to the readystatechange event, as in the example below:

var xhr = new XMLHttpRequest(); var onReadyStateHandler = function(event) { if( event.target.readyState == 4 && event.target.status == 200){ /* handle the response */ } } xhr.open('GET','/path_to_data'); xhr.onreadystatechange = onReadyStateHandler; xhr.send();

Though it works well for alerting us that all of our data has downloaded, readystatechange doesn’t tell us anything about how much data has been received. For backward compatibility, it remains a part of the specification. The ProgressEvent interface, however, is far more robust. It adds seven events that are available to both the XMLHttpRequest and the XMLHttpRequestUpload objects.

The different XMLHttpRequest Progress Events are as follows:

attribute type Explanation onloadstart loadstart When the request starts. onprogress progress While loading and sending data. onabort abort When the request has been aborted, either by invoking the abort() method or navigating away from the page. onerror error When the request has failed. onload load When the request has successfully completed. ontimeout timeout When the author specified timeout has passed before the request could complete. onloadend loadend When the request has completed, regardless of whether or not it was successful.

ProgressEvent inherits from the DOM, Level 2 EventTarget interface so we can either use event attributes such as onload , or the addEventListener method in our code. In the examples above, we've used event attributes. In our next example, we’ll use addEventListener .

Monitoring uploads

All XMLHttpRequest -based file uploads create an XMLHttpRequestUpload object, which we can reference with the upload attribute of XMLHttpRequest . To monitor upload progress, we’ll need to listen for events on the XMLHttpRequestUpload object.

In the code below, we’re listening for the progress , load and error events:

var onProgressHandler = function(event) { if(event.lengthComputable) { var howmuch = (event.loaded / event.total) * 100; document.querySelector('progress').value = Math.ceil(howmuch); } else { console.log("Can't determine the size of the file."); } } var onLoadHandler = function() { displayLoadedMessage(); } var onErrorHandler = function() { displayErrorMesssage(); } xhr.upload.addEventListener('progress', onProgressHandler, false); xhr.upload.addEventListener('load', onLoadHandler, false); xhr.upload.addEventListener('error', onErrorHandler, false);

Pay special attention to the lengthComputable , loaded and total properties used in the onProgressHandler function. Each of these are properties of the progress event object. The lengthComputable property reveals whether or not the browser can detect the input file size, while loaded and total reveal how many bytes have been uploaded and the total size of the file. You can view an XHR progress events demo.

These events only monitor the browser’s progress in sending data to or receiving data from the server. When uploading, you may experience a lag between when the load event is fired and when the server sends a response. How long of a lag will depend on the size of the file, the server’s resources, and network speeds.

In the example above, we’re setting event listeners on the XMLHttpRequestUpload object. To monitor file downloads, add event listeners to the XMLHttpRequest object instead.

Enforcing a response MIME type

MIME-type mismatches are pretty common on the web. Sometimes XML data will have a Content-type: text/html response header, which will cause the value of xhr.responseXML to be null .

To ensure that the browser handles such responses in the way we’d like, we can use the overrideMimeType() method. In the example below, data.xml returns the following response headers:

Date: Sat, 04 Jun 2011 03:11:31 GMT Server: Apache/2.2.17 Access-Control-Allow-Origin: * Keep-Alive: timeout=5, max=100 Connection: Keep-Alive Content-Type: text/html; charset=UTF-8

That’s the wrong content type for an XML document. So let’s guarantee that the browser treats data.xml as XML, and populates the responseXML attribute:

var xhr = new XMLHttpRequest(); xhr.open('GET','data.xml'); xhr.overrideMimeType('application/xml'); xhr.send(); xhr.addEventListener('load', function(event) { console.log( event.target.responseXML ); }, false);

Now the value of xhr.responseXML is a Document object, which means we can parse the data as we would any other XML document. View an XHR override MIME type demo.

Enforcing a response type

It's also possible to tell the browser to handle a response as text , json , an arraybuffer , a blob or and document using the responseType property.

As with overrideMimeType , the responseType property must be set before the request is sent. In the example below, we are telling Opera to treat the response as a document , and write the firstChild to the console (view an enforcing response type demo):

var xhr = new XMLHttpRequest(); xhr.open('GET','data.xml'); xhr.responseType = 'document'; xhr.send(); xhr.addEventListener('load', function(e) { console.log( event.target.response.firstChild ); } false);

Though responseType allows developers to, say, handle image data as a byte array instead of a binary string, it does not work miracles. Changing document to json in the example above would cause our response property to be null because XML is not JSON. Similarly, invalid JSON data will also cause response to be null . When setting a responseType , you still need to ensure that your data is both valid and compatible with the specified type.

Note: As of publication, Opera does not support blob as a value, and only supports XML and not HTML for the document type. Chrome and Safari do not yet support json as a value.

Learn more

These XMLHttpRequest improvements are a leap forward for client-side interactivity. For more on XMLHttpRequest, CORS, and related APIs, see the following resources: