Table of contents
- 1. Method overview
- 2. Properties
- 3. Methods
- 4. Notes
- 4.1.1. Events
- 5. Browser compatibility
- 5.1. Gecko notes
- 6. See also
XMLHttpRequest can be used to retrieve any type of data, not just XML, and it supports protocols other than HTTP (including
To create an instance of
XMLHttpRequest, simply do this:
var req = new XMLHttpRequest();
For details about how to use
XMLHttpRequest, see Using XMLHttpRequest.
| || || |
Warning: This must not be used from native code. You should also not use this with synchronous requests.
| || || |
The state of the request:
| || ||The response to the request as text, or |
| || || |
Can be set to change the response type. This tells the server what format you want the response to be in.
Note: Starting with Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0) , as well as WebKit build 528, these browsers no longer let you use the
| || || |
The response to the request as a DOM
Note: If the server doesn't apply the
| || ||The status of the response to the request. This is the HTTP result code (for example, |
| || ||The response string returned by the HTTP server. Unlike |
| || || |
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.
| || ||The upload process can be tracked by adding an event listener to |
| || || |
Indicates whether or not cross-site
Note: This never affects same-site requests.
Note: Starting with Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0) , Gecko no longer lets you use the
| || ||The channel used by the object when performing the request. This is |
| || || |
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.
| || || |
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
Aborts the request if it has already been sent.
Returns all the response headers 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.
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.
openRequest()has already been called) is the equivalent of calling
void open( DOMString method, DOMString url, optional boolean async, optional DOMString user, optional DOMString password );
- The HTTP method to use, such as "GET", "POST", "PUT", "DELETE", etc. Ignored for non-HTTP(S) URLs.
- The URL to which to send the request.
- An optional boolean parameter, defaulting to
true, indicating whether or not to perform the operation asynchronously. If this value is
send()method does not return until the response is received. If
true, notification of a completed transaction is provided using event listeners. This must be true if the
true, or an exception will be thrown.
- The optional user name to use for authentication purposes; by default, this is an empty string.
- The optional password to use for authentication purposes; by default, this is an empty string.
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
void overrideMimeType(DOMString mimetype);
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.
void send(); void send(ArrayBuffer data); void send(Blob data); void send(Document data); void send(DOMString? data); void send(FormData data);
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
setUploadStream()method. In that case, a Content-Length header is added to the request, with its value obtained using
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
Sets the value of an HTTP request header.You must call
open() before using this method.
void setRequestHeader( DOMString header, DOMString value );
- The name of the header whose value is to be set.
- The value to set as the body of the header.
Initializes the object for use from C++code.
[noscript] void init( in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow );
- The principal to use for the request; must not be
- The script context to use for the request; must not be
- The window associated with the request; may be
open()instead. See the documentation for
A variant of the
send()method that sends binary data.
void sendAsBinary( in DOMString 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).
- By default, Firefox 3 limits the number of
XMLHttpRequestconnections per server to 6 (previous versions limit this to 2 per server). Some interactive web sites may keep an
XMLHttpRequestconnection 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 the
- From Gecko 7.0 headers set by
setRequestHeader()are sent with the request when following a redirect. Previously these headers would not be sent.
XMLHttpRequestis implemented in Gecko using the
onreadystatechange as a property on the xhr object is supported in all browsers.
Since then, a number of additional event handlers were implemented in various browsers (
onprogress, etc.). These are supported in Firefox. In particular, see
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.
|Feature||Chrome||Firefox (Gecko)||Internet Explorer||Opera||Safari (WebKit)|
|Basic support (XHR1)||1||1.0||5 (via ActiveXObject) |
|Feature||Android||Chrome for Android||Firefox Mobile (Gecko)||IE Phone||Opera Mobile||Safari Mobile|
Gecko 11.0 (Firefox 11.0 / Thunderbird 11.0)
removed support for using the
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)
and later support using
XMLHttpRequest to read from
- MDN articles about XMLHttpRequest:
- XMLHttpRequest references from W3C and browser vendors:
- "Using the XMLHttpRequest Object" (jibbering.com)
- XMLHttpRequest - REST and the Rich User Experience
- HTML5 Rocks - New Tricks in XMLHttpRequest2