XMLHttpRequest
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
XMLHttpRequest()
- The constructor initiates an XMLHttpRequest. It must be called before any other method calls.
Properties
This interface also inherits properties of XMLHttpRequestEventTarget
and of EventTarget
.
XMLHttpRequest.onreadystatechange
- An
EventHandler
that is called whenever thereadyState
attribute changes. XMLHttpRequest.readyState
Read only- Returns an
unsigned short
, the state of the request. XMLHttpRequest.response
Read only- Returns an
ArrayBuffer
,Blob
,Document
, JavaScript object, or aDOMString
, depending on the value ofXMLHttpRequest.responseType
. that contains the response entity body. XMLHttpRequest.responseText
Read only- Returns a
DOMString
that contains the response to the request as text, ornull
if the request was unsuccessful or has not yet been sent. XMLHttpRequest.responseType
- Is an enumerated value that defines the response type.
XMLHttpRequest.responseURL
Read only- Returns the serialized URL of the response or the empty string if the URL is null.
XMLHttpRequest.responseXML
Read only Not available to workers- Returns a
Document
containing the response to the request, ornull
if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML or HTML. XMLHttpRequest.status
Read only- Returns an
unsigned short
with the status of the response of the request. XMLHttpRequest.statusText
Read only- Returns a
DOMString
containing the response string returned by the HTTP server. UnlikeXMLHTTPRequest.status
, this includes the entire text of the response message ("200 OK
", for example). XMLHttpRequest.timeout
- Is an
unsigned long
representing the number of milliseconds a request can take before automatically being terminated. XMLHttpRequestEventTarget.ontimeout
- Is an
EventHandler
that is called whenever the request times out. XMLHttpRequest.upload
Read only- Is an
XMLHttpRequestUpload
, representing the upload process. XMLHttpRequest.withCredentials
- Is a
Boolean
that indicates whether or not cross-siteAccess-Control
requests should be made using credentials such as cookies or authorization headers.
Non-standard properties
XMLHttpRequest.channel
Read only- Is a
nsIChannel
. The channelused by the object when performing the request. XMLHttpRequest.mozAnon
Read only- Is a boolean. If true, the request will be sent without cookie and authentication headers.
XMLHttpRequest.mozSystem
Read only- Is a boolean. If true, the same origin policy will not be enforced on the request.
XMLHttpRequest.mozBackgroundRequest
- Is a boolean. It indicates whether or not the object represents a background service request.
XMLHttpRequest.mozResponseArrayBuffer
Obsolete since Gecko 6 Read only- Is an
ArrayBuffer
. The response to the request, as a JavaScript typed array. XMLHttpRequest.multipart
Obsolete since Gecko 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
XMLHttpRequest.abort()
- Aborts the request if it has already been sent.
XMLHttpRequest.getAllResponseHeaders()
- Returns all the response headers, separated by CRLF, as a string, or
null
if no response has been received. 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. XMLHttpRequest.open()
- Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use
openRequest()
instead. XMLHttpRequest.overrideMimeType()
- Overrides the MIME type returned by the server.
XMLHttpRequest.send()
- Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent.
XMLHttpRequest.setRequestHeader()
- Sets the value of an HTTP request header. You must call
setRequestHeader()
afteropen()
, but beforesend()
.
Non-standard methods
XMLHttpRequest.init()
- Initializes the object for use from C++ code.
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()
. XMLHttpRequest.sendAsBinary()
- A variant of the
send()
method that sends binary data.
Specifications
Specification | Status | Comment |
---|---|---|
XMLHttpRequest | Living Standard | Live standard, latest version |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support (XHR1) | 1 | 1.0 (1.7 or earlier) | 7 | (Yes) | 1.2 |
send(ArrayBuffer) |
9 | 9.0 (9.0) | 10 | 11.60 | ? |
send(ArrayBufferView) |
22 | 20.0 (20.0) | ? | ? | ? |
send(Blob) |
7 | 3.6 (1.9.2) | 10 | 12 | ? |
send(FormData) |
6 | 4.0 (2.0) | 10 | 12 | ? |
sendAsBinary(DOMString) |
No support[1] | 2.0 (1.8.1) | No support | No support | No support |
response |
10 | 6.0 (6.0) | 10 | 11.60 | (Yes) |
responseType = 'arraybuffer' |
10 | 6.0 (6.0) | 10 | 11.60 | (Yes) |
responseType = 'blob' |
19 | 6.0 (6.0) | 10 | 12 | (Yes) |
responseType = 'document' |
18 | 11.0 (11.0) | 10 | No support | 6.1 |
responseType = 'json' |
31 | 10.0 (10.0) | No support | 12[2] No support 16 17 |
(Yes) |
Progress Events | 7 | 3.5 (1.9.1) | 10 | 12 | (Yes) |
withCredentials |
3 | 3.5 (1.9.1) | 10 | 12 | 4 |
timeout |
29.0 | 12.0 (12.0) | 8 | 12 16 |
(Yes) |
responseType = 'moz-blob' |
No support | 12.0 (12.0) | No support | No support | No support |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | 1.0 | (Yes) | ? | ? | ? |
send(ArrayBuffer) |
? | ? | ? | ? | ? | |
send(ArrayBufferView) |
? | ? | ? | ? | ? | |
send(Blob) |
? | ? | ? | ? | ? | |
send(FormData) |
? | ? | ? | ? | ? | |
sendAsBinary(DOMString) |
? | ? | ? | ? | ? | |
response |
? | ? | ? | ? | ? | |
responseType = 'arraybuffer' |
? | ? | ? | ? | ? | |
responseType = 'blob' |
? | ? | ? | ? | ? | |
responseType = 'document' |
? | ? | ? | ? | ? | |
responseType = 'json' |
? | ? | ? | ? | ? | |
Progress Events | ? | ? | ? | ? | ? | |
withCredentials |
? | ? | ? | ? | ? | |
timeout |
? | ? | ? | ? | ? | |
responseType = 'moz-blob' |
? | ? | ? | ? | ? |
[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
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/xmlhttprequest