XMLHttpRequest Standard XMLHttpRequest Living Standard — Last Updated 18 August 2026 Participate: GitHub whatwg/xhr (new issue, open issues) Chat on Matrix Commits: GitHub whatwg/xhr/commits Snapshot as of this commit Tests: web-platform-tests xhr/ (ongoing work) Translations (non-normative): 日本語 简体中文 한국어 Abstract The XMLHttpRequest Standard defines an API that provides scripted client functionality for transferring data between a client and a server. 1. Introduction This section is non-normative. The XMLHttpRequest object is an API for fetching resources. The name XMLHttpRequest is historical and has no bearing on its functionality. Some simple code to do something with data from an XML document fetched over the network: function processData(data) { // taking care of data } function handler() { if(this.status == 200 && this.responseXML != null && this.responseXML.getElementById('test').textContent) { // success! processData(this.responseXML.getElementById('test').textContent); } else { // something went wrong … } } var client = new XMLHttpRequest(); client.onload = handler; client.open("GET", "unicorn.xml"); client.send(); If you just want to log a message to the server: function log(message) { var client = new XMLHttpRequest(); client.open("POST", "/log"); client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8"); client.send(message); } Or if you want to check the status of a document on the server: function fetchStatus(address) { var client = new XMLHttpRequest(); client.onload = function() { // in case of network errors this might not give reliable results returnStatus(this.status); } client.open("HEAD", address); client.send(); } 1.1. Specification history The XMLHttpRequest object was initially defined as part of the WHATWG’s HTML effort. (Based on Microsoft’s implementation many years prior.) It moved to the W3C in 2006. Extensions (e.g., progress events and cross-origin requests) to XMLHttpRequest were developed in a separate draft (XMLHttpRequest Level 2) until end of 2011, at which point the two drafts were merged and XMLHttpRequest became a single entity again from a standards perspective. End of 2012 it moved back to the WHATWG. Discussion that led to the current draft can be found in the following mailing list archives: [email protected] [email protected] [email protected] [email protected] 2. Terminology This specification depends on the Infra Standard. [INFRA] This specification uses terminology from DOM, DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, URL, Web IDL, and XML. [DOM] [DOM-PARSING] [ENCODING] [FETCH] [FILEAPI] [HTML] [URL] [WEBIDL] [XML] [XML-NAMES] 3. Interface XMLHttpRequest [Exposed=(Window,DedicatedWorker,SharedWorker)] interface XMLHttpRequestEventTarget : EventTarget { // event handlers attribute EventHandler onloadstart; attribute EventHandler onprogress; attribute EventHandler onabort; attribute EventHandler onerror; attribute EventHandler onload; attribute EventHandler ontimeout; attribute EventHandler onloadend; }; [Exposed=(Window,DedicatedWorker,SharedWorker)] interface XMLHttpRequestUpload : XMLHttpRequestEventTarget { }; enum XMLHttpRequestResponseType { "", "arraybuffer", "blob", "document", "json", "text" }; [Exposed=(Window,DedicatedWorker,SharedWorker)] interface XMLHttpRequest : XMLHttpRequestEventTarget { constructor(); // event handler attribute EventHandler onreadystatechange; // states const unsigned short UNSENT = 0; const unsigned short OPENED = 1; const unsigned short HEADERS_RECEIVED = 2; const unsigned short LOADING = 3; const unsigned short DONE = 4; readonly attribute unsigned short readyState; // request undefined open(ByteString method, USVString url); undefined open(ByteString method, USVString url, boolean async, optional USVString? username = null, optional USVString? password = null); undefined setRequestHeader(ByteString name, ByteString value); attribute unsigned long timeout; attribute boolean withCredentials; [SameObject] readonly attribute XMLHttpRequestUpload upload; undefined send(optional (Document or XMLHttpRequestBodyInit)? body = null); undefined abort(); // response readonly attribute USVString responseURL; readonly attribute unsigned short status; readonly attribute ByteString statusText; ByteString? getResponseHeader(ByteString name); ByteString getAllResponseHeaders(); undefined overrideMimeType(DOMString mime); attribute XMLHttpRequestResponseType responseType; readonly attribute any response; readonly attribute USVString responseText; [Exposed=Window] readonly attribute Document? responseXML; }; An XMLHttpRequest object has an associated: upload object An XMLHttpRequestUpload object. state One of unsent, opened, headers received, loading, and done; initially unsent. send() invoked A boolean, initially false. timeout An unsigned integer, initially 0. cross-origin credentials A boolean, initially false. request method A method. request URL A URL. author request headers A header list, initially empty. request body Initially null. synchronous A boolean, initially false. upload complete A boolean, initially false. upload listener A boolean, initially false. timed out A boolean, initially false. response A response, initially a network error. received bytes A byte sequence, initially the empty byte sequence. response type One of the empty string, "arraybuffer", "blob", "document", "json", and "text"; initially the empty string. response object An object, failure, or null, initially null. fetch controller A fetch controller, initially a new fetch controller. The send() method sets it to a useful fetch controller, but for simplicity it always holds a fetch controller. override MIME type A MIME type or null, initially null. Can get a value when overrideMimeType() is invoked. 3.1. Constructors client = new XMLHttpRequest() Returns a new XMLHttpRequest object. The new XMLHttpRequest() constructor steps are: Set this’s upload object to a new XMLHttpRequestUpload object. 3.2. Garbage collection An XMLHttpRequest object must not be garbage collected if its state is either opened with send() invoked being true, headers received, or loading, and it has one or more event listeners registered whose type is one of readystatechange, progress, abort, error, load, timeout, and loadend. If an XMLHttpRequest object is garbage collected while its connection is still open, the user agent must terminate the XMLHttpRequest object’s fetch controller. 3.3. Event handlers The following are the event handlers (and their corresponding event handler event types) that must be supported on objects implementing an interface that inherits from XMLHttpRequestEventTarget as attributes: event handler event handler event type onloadstart loadstart onprogress progress onabort abort onerror error onload load ontimeout timeout onloadend loadend The following is the event handler (and its corresponding event handler event type) that must be supported as attribute solely by the XMLHttpRequest object: event handler event handler event type onreadystatechange readystatechange 3.4. States client . readyState Returns client’s state. The readyState getter steps are to return the value from the table below in the cell of the second column, from the row where the value in the cell in the first column is this’s state: unsent UNSENT (numeric value 0) The object has been constructed. opened OPENED (numeric value 1) The open() method has been successfully invoked. During this state request headers can be set using setRequestHeader() and the fetch can be initiated using the send() method. headers received HEADERS_RECEIVED (numeric value 2) All redirects (if any) have been followed and all headers of a response have been received. loading LOADING (numeric value 3) The response body is being received. done DONE (numeric value 4) The data transfer has been completed or something went wrong during the transfer (e.g., infinite redirects). 3.5. Request Registering one or more event listeners on an XMLHttpRequestUpload object will result in a CORS-preflight request. (That is because registering an event listener causes upload listener to be set to true, which in turn causes the use-CORS-preflight flag to be set.) 3.5.1. The open() method client . open(method, url [, async = true [, username = null [, password = null]]]) Sets the request method, request URL, and whether the request is synchronous. Throws a "SyntaxError" DOMException if either method is not a valid method or url cannot be parsed. Throws a "SecurityError" DOMException if method is a case-insensitive match for `CONNECT`, `TRACE`, or `TRACK`. Throws an "InvalidAccessError" DOMException if async is false, the current global object is a Window object, and the timeout attribute is not zero or the responseType attribute is not the empty string. Synchronous XMLHttpRequest outside of workers is in the process of being removed from the web platform as it has detrimental effects to the end user’s experience. (This is a long process that takes many years.) Developers must not pass false for the async argument when the current global object is a Window object. User agents are strongly encouraged to warn about such usage in developer tools and may experiment with throwing an "InvalidAccessError" DOMException when it occurs. The open(method, url) and open(method, url, async, username, password) method steps are: If this’s relevant global object is a Window object and its associated Document is not fully active, then throw an "InvalidStateError" DOMException. If method is not a method, then throw a "SyntaxError" DOMException. If method is a forbidden method, then throw a "SecurityError" DOMException. Normalize method. Let parsedURL be the result of encoding-parsing a URL url, relative to this’s relevant settings object. If parsedURL is failure, then throw a "SyntaxError" DOMException. If the async argument is omitted, set async to true, and set username and password to null. Unfortunately legacy content prevents treating the async argument being undefined identical from it being omitted. If parsedURL’s host is non-null: If the username argument is not null, set the username given parsedURL and username. If the password argument is not null, set the password given parsedURL and password. If async is false, the current global object is a Window object, and either this’s timeout is not 0 or this’s response type is not the empty string, then throw an "InvalidAccessError" DOMException. Terminate this’s fetch controller. A fetch can be ongoing at this point. Set variables associated with the object as follows: Set this’s send() invoked to false. Set this’s request method to method. Set this’s request URL to parsedURL. Empty this’s author request headers. Set this’s request body to null. Set this’s synchronous to the inverse of async. Set this’s upload listener to false. Set this’s response to a network error. Set this’s received bytes to the empty byte sequence. Set this’s response object to null. Override MIME type is not overridden here as the overrideMimeType() method can be invoked before the open() method. If this’s state is not opened: Set this’s state to opened. Fire an event named readystatechange at this. The reason there are two open() methods defined is due to a limitation of the editing software used to write the XMLHttpRequest Standard. 3.5.2. The setRequestHeader() method client . setRequestHeader(name, value) Appends a value to an existing request header or adds a new request header. Throws an "InvalidStateError" DOMException if either state is not opened or send() invoked is true. Throws a "SyntaxError" DOMException if name is not a header name or if value is not a header value. The setRequestHeader(name, value) method steps are: If this’s state is not opened, then throw an "InvalidStateError" DOMException. If this’s send() invoked is true, then throw an "InvalidStateError" DOMEx…