This page is Ready to Use

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

XMLHttpRequest

Summary

XMLHttpRequest allows JavaScript to make HTTP requests, and is the most basic part of AJAX. It allows a website to dynamically request more content, without reloading the entire page.

Overview

The XMLHttpRequest property is available on the window object.

var xhr = new XMLHttpRequest();

With the XMLHttpRequest object, clients can make HTTP requests to a URL without reloading the entire page. Despite the term “XML” in the name, this object can be used to retrieve any type of data.

Properties

readyState
Returns the current state of the XMLHttpRequest.
response
Returns the response entity body, which is the fragment of the entity body of the response received so far (if LOADING) or the complete entity body of the response (if DONE).
responseText
Returns the text response entity body, a string representing the response entity body, which is the fragment of the entity body of the response received so far (if LOADING) or the complete entity body of the response (if DONE).
responseType
Returns or sets the format the response will be returned in.
responseXML
Returns the response to the request as a DOM Document object, or null if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML or HTML.
status
Returns the HTTP result code (status) of the response to the request.
statusText
Returns the HTTP status text.
timeout
Returns or sets the number of milliseconds a request can take before automatically being terminated.
upload
Returns the associated XMLHttpRequestUpload object. It can be used to gather transmission information when data is transferred to a server.
withCredentials
Returns or sets whether cross-site Access-Control requests should be made using credentials such as cookies or authorization headers.

Methods

abort
Stops an asynchronous XMLHttpRequest in progress.
getAllResponseHeaders
Returns all the response headers as a string, or null if no response has been received.
getResponseHeader
Returns the string containing the text of the specified header, or null if the response has not been received or the header does not exist.
open
Initializes an XMLHttpRequest.
overrideMimeType
Overrides the MIME type returned by the server.
send
Initiates the request defined by the XMLHttpRequest.
setRequestHeader
Sets the value of an XMLHttpRequest header.

Events

abort
When the request has been aborted. For instance, by invoking the abort() method.
error
When the request has failed.
load
When the request has successfully completed.
loadend
When the request has completed (either in success or failure).
loadstart
When the request starts.
progress
While sending and loading data.
readystatechange
Fires whenever the readyState of the request changes. Mostly used to determine whether the body of the response is available for handling.
timeout
When the author specified timeout has passed before the request could complete.

Examples

The following script demonstrates how to create and use the XMLHttpRequest object. For best client-side performance, the request is asynchronous and uses an onreadystatechange event handler to process the data returned by the call.

function handler() {
  if (xhr.readyState === 4 /* complete */) {
    if (xhr.status === 200) {
            console.log(xhr.responseText);
        }
    }
}
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://localhost/test.xml", true);
xhr.onreadystatechange = handler;
xhr.send();

This script demonstrates how to access resources that sits on a different domain. Example: siteA.com gets resource from siteB.com

// Create the XHR object.
function createCORSRequest(method, url) {
  var xhr = new XMLHttpRequest();
  if ("withCredentials" in xhr) {
    // XHR for Chrome/Firefox/Opera/Safari.
    xhr.open(method, url, true);
  } else if (typeof XDomainRequest != "undefined") {
    // XDomainRequest for IE 9 and earlier.
    xhr = new XDomainRequest();
    xhr.open(method, url);
  } else {
    // CORS not supported.
    xhr = null;
  }
  return xhr;
}

// Helper method to parse the title tag from the response.
function getTitle(text) {
  return text.match('<title>(.*)?</title>')[1];
}

// Make the actual CORS request.
function makeCorsRequest() {
  // All HTML5 Rocks properties support CORS.
  var url = 'http://updates.html5rocks.com';

  var xhr = createCORSRequest('GET', url);
  if (!xhr) {
    alert('CORS not supported');
    return;
  }

  // Response handlers.
  xhr.onload = function() {
    var text = xhr.responseText;
    var title = getTitle(text);
    alert('Response from CORS request to ' + url + ': ' + title);
  };

  xhr.onerror = function() {
    alert('Woops, there was an error making the request.');
  };

  xhr.send();
}

Usage

 The XMLHttpRequest object can be used to make either same-origin or cross-origin requests.

Same-origin requests are subject to the browser’s same-origin policy: http://en.wikipedia.org/wiki/Same_origin_policy This basically says that an XMLHttpRequest instance can make a request to a resource that lives on the same origin as the calling page.

Requests that go across origins (for example, a request from originA.com to originB.com) can also be made. But in order for them to work, the destination server must support Cross-Origin Resource Sharing (CORS, http://www.w3.org/TR/cors/). These are a set of headers included in the response that indicate how a resource can be accessed across domains.

Related specifications

W3C XMLHttpRequest Specification
W3C Working Draft
Cross-Origin Resource Sharing
W3C Candidate Recommendation 29 January 2013

See also

Related articles

XHR

Attributions