XMLHttpRequest
is an API that provides client functionality for transferring data between a client and a server. It provides an easy way to retrieve data from a URL without having to do a full page refresh. This enables a Web page to update just a part of the page without disrupting what the user is doing. XMLHttpRequest
is used heavily in AJAX programming.
XMLHttpRequest was originally designed by Microsoft and adopted by Mozilla, Apple, and Google. It's now being standardized at the WHATWG. Despite its name, XMLHttpRequest
can be used to retrieve any type of data, not just XML, and it supports protocols other than HTTP (including file
and ftp
).
Constructor
- {{domxref("XMLHttpRequest.XMLHttpRequest", "XMLHttpRequest")}}
- The constructor initiates an XMLHttpRequest. It must be called before any other method calls.
Properties
This interface also inherits properties of {{domxref("XMLHttpRequestEventTarget")}} and of {{domxref("EventTarget")}}.
- {{domxref("XMLHttpRequest.onreadystatechange")}}
- An {{domxref("EventHandler")}} that is called whenever the
readyState
attribute changes. - {{domxref("XMLHttpRequest.readyState")}} {{readonlyinline}}
- Returns an
unsigned short
, the state of the request. - {{domxref("XMLHttpRequest.response")}} {{readonlyinline}}
- Returns an {{domxref("ArrayBuffer")}}, {{domxref("Blob")}}, {{domxref("Document")}}, JavaScript object, or a {{domxref("DOMString")}}, depending of the value of {{domxref("XMLHttpRequest.responseType")}}. that contains the response entity body.
- {{domxref("XMLHttpRequest.responseText")}} {{readonlyinline}}
- Returns a {{domxref("DOMString")}} that contains the response to the request as text, or
null
if the request was unsuccessful or has not yet been sent. - {{domxref("XMLHttpRequest.responseType")}}
- Is an enumerated value that defines the response type.
- {{domxref("XMLHttpRequest.responseURL")}} {{readonlyinline}}
- Returns the serialized URL of the response or the empty string if the URL is null.
- {{domxref("XMLHttpRequest.responseXML")}} {{readonlyinline}} {{NotAvailableInWorkerInline}}
- Returns a {{domxref("Document")}} containing the response to the request, or
null
if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML or HTML. - {{domxref("XMLHttpRequest.status")}} {{readonlyinline}}
- Returns an
unsigned short
with the status of the response of the request. - {{domxref("XMLHttpRequest.statusText")}} {{readonlyinline}}
- Returns a {{domxref("DOMString")}} containing the response string returned by the HTTP server. Unlike {{domxref("XMLHTTPRequest.status")}}, this includes the entire text of the response message ("
200 OK
", for example). - {{domxref("XMLHttpRequest.timeout")}}
- Is an
unsigned long
representing the number of milliseconds a request can take before automatically being terminated. - {{domxref("XMLHttpRequestEventTarget.ontimeout")}}
- Is an {{domxref("EventHandler")}} that is called whenever the request times out. {{gecko_minversion_inline("12.0")}}
- {{domxref("XMLHttpRequest.upload")}} {{readonlyinline}}
- Is an {{domxref("XMLHttpRequestUpload")}}, representing the upload process.
- {{domxref("XMLHttpRequest.withCredentials")}}
- Is a {{jsxref("Boolean")}} that indicates whether or not cross-site
Access-Control
requests should be made using credentials such as cookies or authorization headers.
Non-standard properties
- {{domxref("XMLHttpRequest.channel")}}{{ReadOnlyInline}}
- Is a {{Interface("nsIChannel")}}. The channelused by the object when performing the request.
- {{domxref("XMLHttpRequest.mozAnon")}}{{ReadOnlyInline}}
- Is a boolean. If true, the request will be sent without cookie and authentication headers.
- {{domxref("XMLHttpRequest.mozSystem")}}{{ReadOnlyInline}}
- Is a boolean. If true, the same origin policy will not be enforced on the request.
- {{domxref("XMLHttpRequest.mozBackgroundRequest")}}
- Is a boolean. It indicates whether or not the object represents a background service request.
- {{domxref("XMLHttpRequest.mozResponseArrayBuffer")}}{{gecko_minversion_inline("2.0")}} {{obsolete_inline("6")}} {{ReadOnlyInline}}
- Is an
ArrayBuffer
. The response to the request, as a JavaScript typed array. - {{domxref("XMLHttpRequest.multipart")}}{{obsolete_inline("22")}}
- This Gecko-only feature, a boolean, was removed in Firefox/Gecko 22. Please use Server-Sent Events, Web Sockets, or
responseText
from progress events instead.
Event handlers
onreadystatechange
as a property of the XMLHttpRequest
instance is supported in all browsers.
Since then, a number of additional event handlers were implemented in various browsers (onload
, onerror
, onprogress
, etc.). These are supported in Firefox. In particular, see nsIXMLHttpRequestEventTarget
and Using XMLHttpRequest.
More recent browsers, including Firefox, also support listening to the XMLHttpRequest
events via standard addEventListener
APIs in addition to setting on*
properties to a handler function.
Methods
- {{domxref("XMLHttpRequest.abort")}}
- Aborts the request if it has already been sent.
- {{domxref("XMLHttpRequest.getAllResponseHeaders")}}
- Returns all the response headers, separated by CRLF, as a string, or
null
if no response has been received. - {{domxref("XMLHttpRequest.getResponseHeader")}}
- Returns the string containing the text of the specified header, or
null
if either the response has not yet been received or the header doesn't exist in the response. - {{domxref("XMLHttpRequest.open")}}
- Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use
openRequest()
instead. - {{domxref("XMLHttpRequest.overrideMimeType")}}
- Overrides the MIME type returned by the server.
- {{domxref("XMLHttpRequest.send")}}
- Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent.
- {{domxref("XMLHttpRequest.setRequestHeader")}}
- Sets the value of an HTTP request header. You must call
setRequestHeader()
afteropen()
, but beforesend()
.
Non-standard methods
- {{domxref("XMLHttpRequest.init")}}
- Initializes the object for use from C++ code.
- {{domxref("XMLHttpRequest.openRequest")}}
- Initializes a request. This method is to be used from native code; to initialize a request from JavaScript code, use
open()
instead. See the documentation foropen()
. - {{domxref("XMLHttpRequest.sendAsBinary")}}{{deprecated_inline(31)}}
- A variant of the
send()
method that sends binary data.
Specifications
Specification | Status | Comment |
---|---|---|
{{SpecName('XMLHttpRequest')}} | {{Spec2('XMLHttpRequest')}} | WHATWG living standard |
Browser compatibility
{{CompatibilityTable}}
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support (XHR1) | 1 | {{CompatGeckoDesktop("1.0")}} | 7 | {{CompatVersionUnknown}} | 1.2 |
send(ArrayBuffer) |
9 | {{CompatGeckoDesktop("9.0")}} | 10 | 11.60 | {{compatUnknown}} |
send(ArrayBufferView) |
22 | {{CompatGeckoDesktop("20.0")}} | {{compatUnknown}} | {{compatUnknown}} | {{compatUnknown}} |
send(Blob) |
7 | {{CompatGeckoDesktop("1.9.2")}} | 10 | 12 | {{compatUnknown}} |
send(FormData) |
6 | {{CompatGeckoDesktop("2.0")}} | 10 | 12 | {{compatUnknown}} |
sendAsBinary(DOMString) {{non-standard_inline}} {{deprecated_inline}} |
{{compatNo}}[1] | {{CompatGeckoDesktop("1.8.1")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
response |
10 | {{CompatGeckoDesktop("6.0")}} | 10 | 11.60 | {{CompatVersionUnknown}} |
responseType = 'arraybuffer' |
10 | {{CompatGeckoDesktop("6.0")}} | 10 | 11.60 | {{CompatVersionUnknown}} |
responseType = 'blob' |
19 | {{CompatGeckoDesktop("6.0")}} | 10 | 12 | {{CompatVersionUnknown}} |
responseType = 'document' |
18 | {{CompatGeckoDesktop("11.0")}} | 10 | {{CompatNo}} | 6.1 |
responseType = 'json' |
31 | {{CompatGeckoDesktop("10.0")}} | {{CompatNo}} | 12[2] {{CompatNo}} 16 17 |
{{CompatVersionUnknown}} |
Progress Events | 7 | {{CompatGeckoDesktop("1.9.1")}} | 10 | 12 | {{CompatVersionUnknown}} |
withCredentials |
3 | {{CompatGeckoDesktop("1.9.1")}} | 10 | 12 | 4 |
timeout |
29.0 | {{CompatGeckoDesktop("12.0")}} | 8 | 12 16 |
{{CompatVersionUnknown}} |
responseType = 'moz-blob' |
{{CompatNo}} | {{CompatGeckoDesktop("12.0")}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | {{CompatUnknown}} | 1.0 | {{CompatVersionUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} |
send(ArrayBuffer) |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
send(ArrayBufferView) |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
send(Blob) |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
send(FormData) |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
sendAsBinary(DOMString) {{non-standard_inline}} {{deprecated_inline}} |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
response |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
responseType = 'arraybuffer' |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
responseType = 'blob' |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
responseType = 'document' |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
responseType = 'json' |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
Progress Events | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
withCredentials |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
timeout |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} | |
responseType = 'moz-blob' |
{{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{CompatUnknown}} | {{compatUnknown}} |
[1] There is a polyfill available to support sendAsBinary()
.
[2] Before switching to Blink/Chromium, Opera supported responseType=json
between Opera 12 and Opera 15. Support was added again in Opera 17.
See also
- MDN tutorials covering XMLHttpRequest:
- HTML5 Rocks — New Tricks in XMLHttpRequest2
Chrome scope availability
— how to access XMLHttpRequest from JSM modules etc., which do not have access to DOM