XMLHttpRequest
XMLHttpRequest
(XHR) objects are used to interact with servers. You can retrieve data from a URL without having to do a full page refresh. This enables a Web page to update just part of a page without disrupting what the user is doing.
XMLHttpRequest
is used heavily in AJAX programming.
Despite its name, XMLHttpRequest
can be used to retrieve any type of data, not just XML.
If your communication needs to involve receiving event data or message data from a server, consider using server-sent events through the EventSource
interface. For full-duplex communication, WebSockets may be a better choice.
Note: This feature is available in Web Workers, except for Service Workers
Constructor
XMLHttpRequest()
-
The constructor initializes an
XMLHttpRequest
. It must be called before any other method calls.
Instance properties
This interface also inherits properties of XMLHttpRequestEventTarget
and of EventTarget
.
XMLHttpRequest.readyState
Read only-
Returns a number representing the state of the request.
XMLHttpRequest.response
Read only-
Returns an
ArrayBuffer
, aBlob
, aDocument
, a JavaScript object, or a string, depending on the value ofXMLHttpRequest.responseType
, that contains the response entity body. XMLHttpRequest.responseText
Read only-
Returns a string that contains the response to the request as text, or
null
if the request was unsuccessful or has not yet been sent. XMLHttpRequest.responseType
-
Specifies the type of the response.
XMLHttpRequest.responseURL
Read only-
Returns the serialized URL of the response or the empty string if the URL is null.
XMLHttpRequest.responseXML
Read only-
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. Not available in Web Workers. XMLHttpRequest.status
Read only-
Returns the HTTP response status code of the request.
XMLHttpRequest.statusText
Read only-
Returns a string containing the response string returned by the HTTP server. Unlike
XMLHttpRequest.status
, this includes the entire text of the response message ("OK
", for example).Note: According to the HTTP/2 specification RFC 7540, section 8.1.2.4: Response Pseudo-Header Fields, HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.
XMLHttpRequest.timeout
-
The time in milliseconds a request can take before automatically being terminated.
XMLHttpRequest.upload
Read only-
A
XMLHttpRequestUpload
representing the upload process. XMLHttpRequest.withCredentials
-
Returns
true
if cross-siteAccess-Control
requests should be made using credentials such as cookies or authorization headers; otherwisefalse
.
Non-standard properties
XMLHttpRequest.channel
Read only-
The channel used by the object when performing the request.
XMLHttpRequest.mozAnon
Read only-
A boolean. If true, the request will be sent without cookie and authentication headers.
XMLHttpRequest.mozSystem
Read only-
A boolean. If true, the same origin policy will not be enforced on the request.
XMLHttpRequest.mozBackgroundRequest
-
A boolean. It indicates whether or not the object represents a background service request.
Instance 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.
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()
.
Events
abort
-
Fired when a request has been aborted, for example because the program called
XMLHttpRequest.abort()
. Also available via theonabort
event handler property. error
-
Fired when the request encountered an error. Also available via the
onerror
event handler property. load
-
Fired when an
XMLHttpRequest
transaction completes successfully. Also available via theonload
event handler property. loadend
-
Fired when a request has completed, whether successfully (after
load
) or unsuccessfully (afterabort
orerror
). Also available via theonloadend
event handler property. loadstart
-
Fired when a request has started to load data. Also available via the
onloadstart
event handler property. progress
-
Fired periodically when a request receives more data. Also available via the
onprogress
event handler property. readystatechange
-
Fired whenever the
readyState
property changes. Also available via theonreadystatechange
event handler property. timeout
-
Fired when progress is terminated due to preset time expiring. Also available via the
ontimeout
event handler property.
Specifications
Specification |
---|
XMLHttpRequest Standard # interface-xmlhttprequest |
Browser compatibility
BCD tables only load in the browser
See also
XMLSerializer
: Serializing a DOM tree into XML- MDN tutorials covering
XMLHttpRequest
: - New Tricks in XMLHttpRequest2 (2011)