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
).
Syntax
var myRequest = new XMLHttpRequest();
For details about how to use XMLHttpRequest
, see Using XMLHttpRequest.
Methods
XMLHttpRequest(JSObject objParameters); |
void abort(); |
DOMString getAllResponseHeaders(); |
DOMString? getResponseHeader(DOMString header); |
void open(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password); |
void overrideMimeType(DOMString mime); |
void send(); void send(ArrayBuffer data); void send(ArrayBufferView data); void send(Blob data); void send(Document data); void send(DOMString? data); void send(FormData data); |
void setRequestHeader(DOMString header, DOMString value); |
Non-standard methods |
---|
[noscript] void init(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow); |
[noscript] void openRequest(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password); |
void sendAsBinary(in DOMString body); Deprecated since Gecko 31 |
Properties
This interface also inherits properties of XMLHttpRequestEventTarget
and of EventTarget
.
XMLHttpRequest.onreadystatechange
- An
EventHandler
that is called whenever thereadyState
attribute changes. The callback is called from the user interface thread.
Warning: This should not be used with synchronous requests and must not be used from native code. XMLHttpRequest.readyState
Read only- Returns an
unsigned short
, the state of the request:Value State Description 0
UNSENT
Client has been created. open()
not called yet.1
OPENED
open()
has been called.2
HEADERS_RECEIVED
send()
has been called, and headers and status are available.3
LOADING
Downloading; responseText
holds partial data.4
DONE
The operation is complete. XMLHttpRequest.response
Read only- Returns an
ArrayBuffer
,Blob
,Document
, JavaScript object, or aDOMString
, depending of the value ofXMLHttpRequest.responseType
. that contains the response entity body. This isnull
if the request is not complete or was not successful. 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. It can have the following values:
Value Data type of response
property""
DOMString
(this is the default value)"arraybuffer"
ArrayBuffer
"blob"
Blob
"document"
Document
"json"
JavaScript object, parsed from a JSON string returned by the server "text"
DOMString
"moz-blob"
Used by Firefox to allow retrieving partial Blob
data from progress events. This lets your progress event handler start processing data while it's still being received."moz-chunked-text"
Similar to
"text"
, but is streaming. This means that the value inresponse
is only available during dispatch of the"progress"
event and only contains the data received since the last"progress"
event.When
response
is accessed during a"progress"
event it contains a string with the data. Otherwise it returnsnull
.This mode currently only works in Firefox.
"moz-chunked-arraybuffer"
Similar to
"arraybuffer"
, but is streaming. This means that the value inresponse
is only available during dispatch of the"progress"
event and only contains the data received since the last"progress"
event.When
response
is accessed during a"progress"
event it contains a string with the data. Otherwise it returnsnull
.This mode currently only works in Firefox.
Note: Starting with Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8), as well as WebKit build 528, these browsers no longer let you use the
responseType
attribute when performing synchronous requests. Attempting to do so throws anNS_ERROR_DOM_INVALID_ACCESS_ERR
exception. This change has been proposed to the W3C for standardization. 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. The response is parsed as if it were atext/xml
stream. When theresponseType
is set to"document"
and the request has been made asynchronously, the response is parsed as atext/html
stream.responseXML
is null fordata:
URLs.Note: If the server doesn't apply thetext/xml
Content-Type header, you can useoverrideMimeType()
to forceXMLHttpRequest
to parse it as XML anyway. XMLHttpRequest.status
Read only- Returns an
unsigned short
with the status of the response of the request. This is the HTTP result code (for example,status
is 200 for a successful 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. A value of 0 (which is the default) means there is no timeout.Note: You may not use a timeout for synchronous requests with an owning window. - Using a timeout with an asynchronous request
XMLHttpRequestEventTarget.ontimeout
- Is an
EventHandler
that is called whenever the request times out. XMLHttpRequest.upload
Read only- Is an
XMLHttpRequestUpload
, representing the upload process. It is an opaque object, but being anXMLHttpRequestEventTarget
event listeners can be set on it to track its 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. - In addition, this flag is also used to indicate when cookies are to be ignored in the response.
- The default is
false
.Note: This never affects same-site requests.Note: Starting with Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8), Gecko no longer lets you use thewithCredentials
attribute when performing synchronous requests. Attempting to do so throws anNS_ERROR_DOM_INVALID_ACCESS_ERR
exception.Note:XmlHttpRequest
responses from a different domain cannot set cookie values for their own domain unlesswithCredentials
is set totrue
before making the request, regardless ofAccess-Control-
header values.
Non-standard properties
Attribute | Type | Description |
---|---|---|
channel Read only |
nsIChannel |
The channel used by the object when performing the request. This is null if the channel hasn't been created yet. In the case of a multi-part request, this is the initial channel, not the different parts in the multi-part request. Requires elevated privileges to access. |
mozAnon Read only |
boolean |
If true, the request will be sent without cookie and authentication headers. |
mozSystem Read only |
boolean |
If true, the same origin policy will not be enforced on the request. |
mozBackgroundRequest |
boolean |
This method is not available from Web content. It requires elevated privileges to access. Indicates whether or not the object represents a background service request. If In cases in which a security dialog (such as authentication or a bad certificate notification) would normally be shown, the request simply fails instead. Note: This property must be set before calling
open() . |
mozResponseArrayBuffer Obsolete since Gecko 6 Read only |
ArrayBuffer |
The response to the request, as a JavaScript typed array. This is NULL if the request was not successful, or if it hasn't been sent yet. |
multipart Obsolete since Gecko 22 |
boolean |
This Gecko-only feature was removed in Firefox/Gecko 22. Please use Server-Sent Events, Web Sockets, or Indicates whether or not the response is expected to be a stream of possibly multiple XML documents. If set to This enables support for server push; for each XML document that's written to this request, a new XML DOM document is created and the Note: When this is set, the
onload handler and other event handlers are not reset after the first XMLdocument is loaded, and the onload handler is called after each part of the response is received. |
Constructor
XMLHttpRequest()
The constructor initiates an XMLHttpRequest. It must be called before any other method calls.
Gecko/Firefox 16 adds a non-standard parameter to the constructor that can enable anonymous mode (see bug 692677). Setting the mozAnon
flag to true
effectively resembles the AnonXMLHttpRequest()
constructor described in the XMLHttpRequest specification which has not been implemented in any browser yet (as of September 2012).
XMLHttpRequest ( JSObject objParameters );
Parameters (non-standard)
objParameters
- There are two flags you can set:
mozAnon
- Boolean: Setting this flag to
true
will cause the browser not to expose the origin and user credentials when fetching resources. Most important, this means that cookies will not be sent unless explicitly added using setRequestHeader. mozSystem
- Boolean: Setting this flag to
true
allows making cross-site connections without requiring the server to opt-in using CORS. Requires settingmozAnon: true
, i.e. this can't be combined with sending cookies or other user credentials. This only works in privileged (reviewed) apps; it does not work on arbitrary webpages loaded in Firefox.
Methods
abort()
Aborts the request if it has already been sent.
getAllResponseHeaders()
DOMString getAllResponseHeaders();
Returns all the response headers, separated by CRLF, as a string, or null
if no response has been received. Note: For multipart requests, this returns the headers from the current part of the request, not from the original channel.
getResponseHeader()
DOMString? getResponseHeader(DOMString header);
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. If there are multiple response headers with the same name, then their values are returned as a single concatenated string, where each value is separated from the previous one by a pair of comma and space. The getResponseHeader()
method returns the value as a UTF byte sequence.
open()
Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use openRequest()
instead.
open()
or openRequest()
has already been called) is the equivalent of calling abort()
.void open( DOMString method, DOMString url, optional boolean async, optional DOMString user, optional DOMString password );
Parameters
method
- The HTTP method to use, such as "GET", "POST", "PUT", "DELETE", etc. Ignored for non-HTTP(S) URLs.
url
- The URL to send the request to.
async
- An optional boolean parameter, defaulting to
true
, indicating whether or not to perform the operation asynchronously. If this value isfalse
, thesend()
method does not return until the response is received. Iftrue
, notification of a completed transaction is provided using event listeners. This must be true if themultipart
attribute istrue
, or an exception will be thrown.Note: Starting with Gecko 30.0 (Firefox 30.0 / Thunderbird 30.0 / SeaMonkey 2.27), synchronous requests on the main thread have been deprecated due to the negative effects to the user experience. user
- The optional user name to use for authentication purposes; by default, this is an empty string.
password
- The optional password to use for authentication purposes; by default, this is an empty string.
overrideMimeType()
Overrides the MIME type returned by the server. This may be used, for example, to force a stream to be treated and parsed as text/xml, even if the server does not report it as such. This method must be called before send()
.
void overrideMimeType(DOMString mimetype);
send()
Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.
send()
.ArrayBuffer
as parameter. This is not part of the XMLHttpRequest
specification any longer. Use an ArrayBufferView
instead (see compatibility table for version information).void send();void send(ArrayBuffer data);void send(ArrayBufferView data); void send(Blob data); void send(Document data); void send(DOMString? data); void send(FormData data);
Notes
If the data is a Document
, it is serialized before being sent. When sending a Document, versions of Firefox prior to version 3 always send the request using UTF-8 encoding; Firefox 3 properly sends the document using the encoding specified by body.xmlEncoding
, or UTF-8 if no encoding is specified.
If it's an nsIInputStream
, it must be compatible with nsIUploadChannel
's setUploadStream()
method. In that case, a Content-Length header is added to the request, with its value obtained using nsIInputStream
's available()
method. Any headers included at the top of the stream are treated as part of the message body. The stream's MIMEtype should be specified by setting the Content-Type header using the setRequestHeader()
method prior to calling send()
.
The best way to send binary content (like in files upload) is using an ArrayBufferView or Blobs in conjuncton with the send()
method. However, if you want to send a stringifiable raw data, use the sendAsBinary()
method instead, or the StringView
Non native typed arrays superclass.
setRequestHeader()
Sets the value of an HTTP request header. You must call setRequestHeader()
after open()
, but before send()
. If this method is called several times with the same header, the values are merged into one single request header.
void setRequestHeader( DOMString header, DOMString value );
For security reasons, some headers can only be controlled by the user agent. These headers include the forbidden header names and forbidden response header names.
Parameters
header
- The name of the header whose value is to be set.
value
- The value to set as the body of the header.
Non-standard methods
init()
Initializes the object for use from C++ code.
[noscript] void init( in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsIGlobalObject globalObject, in nsIURI baseURI, [optional] in nsILoadGroup loadGroup );
Parameters
principal
- The principal to use for the request; must not be
null
. scriptContext
- The script context to use for the request; must not be
null
. globalObject
- The object to use as the global for the request. Most often, this is the outer
Window
, but it may also be a sandbox or backstage pass. This may benull
, but if it is, the request cannot create adocument
. Note that prior to Firefox 23, this was always aWindow
. baseURI
- The base URI to use when resolving relative URIs while handling the request. This may be
null
. loadGroup
Optional Requires Gecko 37- An optional load group to use when performing the request. If specified, this is used even if the global has a window with a load group already established.
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 for open()
.
sendAsBinary()
Deprecated since Gecko 31A variant of the send()
method that sends binary data.
send(Blob data)
method can be used instead.void sendAsBinary( in DOMString body );
This method, used in conjunction with the readAsBinaryString
method of the FileReader
API, makes it possible to read and upload any type of file and to stringify the raw data.
Parameters
body
- The request body as a DOMstring. This data is converted to a string of single-byte characters by truncation (removing the high-order byte of each character).
sendAsBinary()
polyfill
Since sendAsBinary()
is an experimental feature, here is a polyfill for browsers that don't support the sendAsBinary()
method but support typed arrays.
/*\ |*| |*| :: XMLHttpRequest.prototype.sendAsBinary() Polyfill :: |*| |*| https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary() |*| \*/ if (!XMLHttpRequest.prototype.sendAsBinary) { XMLHttpRequest.prototype.sendAsBinary = function (sData) { var nBytes = sData.length, ui8Data = new Uint8Array(nBytes); for (var nIdx = 0; nIdx < nBytes; nIdx++) { ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff; } /* send as ArrayBufferView...: */ this.send(ui8Data); /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */ }; }
send()
: an ArrayBuffer
(ui8Data.buffer
– the commented code) or an ArrayBufferView
(ui8Data
, which is a typed array of 8-bit unsigned integers – uncommented code). However, on Google Chrome, when you try to send an ArrayBuffer
, the following warning message will appear: ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead.
Another possible approach to send binary data is the StringView
Non native typed arrays superclass in conjunction with the send()
method.Notes
- By default, Firefox 3 limits the number of
XMLHttpRequest
connections per server to 6 (previous versions limit this to 2 per server). Some interactive web sites may keep anXMLHttpRequest
connection open, so opening multiple sessions to such sites may result in the browser hanging in such a way that the window no longer repaints and controls don't respond. This value can be changed by editing thenetwork.http.max-persistent-connections-per-server
preference inabout:config
. - From Gecko 7.0 headers set by
setRequestHeader()
are sent with the request when following a redirect. Previously these headers would not be sent. XMLHttpRequest
is implemented in Gecko using thensIXMLHttpRequest
,nsIXMLHttpRequestEventTarget
, andnsIJSXMLHttpRequest
interfaces.- When a request reaches its timeout value, a "timeout" event is raised.
Events
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.
Permissions
When using System XHR via the mozSystem
property, for example for Firefox OS apps, you need to be sure to add the systemXHR
permission into your manifest file. System XHR can be used in privileged or certified apps.
"permissions": { "systemXHR":{} }
Specifications
Specification | Status | Comment |
---|---|---|
XMLHttpRequest | Living Standard | WHATWG living standard |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support (XHR1) | 1 | 1.0 (1.7 or earlier)[1] | 5[2] 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[3] | 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[4] 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[5] | 12.0 (12.0) | 8 | 12[6] 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] Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0 / SeaMonkey 2.8) removed support for using the responseType
and withCredentials
attributes when performing synchronous requests. Attempting to do so throws an NS_ERROR_DOM_INVALID_ACCESS_ERR
exception. This change has been proposed to the W3C for standardization.
Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9) and later support using XMLHttpRequest
to read from data:
URLs.
Gecko 20.0 (Firefox 20.0 / Thunderbird 20.0 / SeaMonkey 2.17) adds the support of sending an ArrayBufferView
- sending a plain ArrayBuffer
is not part of the XMLHttpRequest
specification any longer and should be treated as deprecated.
[2] This feature was implemented via ActiveXObject()
. Since version 7 Internet Explorer implements the standard XMLHttpRequest
.
[3] There is a polyfill available to support sendAsBinary()
.
[4] Before switching to Blink/Chromium Opera supported responseType=json
between Opera 12 and Opera 15. Support is added again after it is implemented also in Blink (Opera 17).
[5] This feature was implemented in bug 231959.
[6] See how to set and handle timeouts.
See also
- MDN articles about XMLHttpRequest:
- XMLHttpRequest references from W3C and browser vendors:
- W3C: XMLHttpRequest (base features)
- W3C: XMLHttpRequest (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2
- Microsoft documentation
- Apple developers' reference
- "Using the XMLHttpRequest Object" (jibbering.com)
- XMLHttpRequest - REST and the Rich User Experience
- HTML5 Rocks - New Tricks in XMLHttpRequest2
- Thread on the naming convention of
XMLHttpRequest
Chrome scope availability
- how to access from JSM modules etc which do not have access to DOM