Perform an asynchronous HTTP (Ajax) request.
jQuery.ajax( url [, settings ] )
depends on dataType
)true
)true
by default). If you need synchronous requests, set this option to false
. Cross-domain requests and dataType: "jsonp"
requests do not support synchronous operation. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active. As of jQuery 1.8, the use of async: false
with jqXHR ($.Deferred
) is deprecated; you must use the success/error/complete callback options instead of the corresponding methods of the jqXHR object such as jqXHR.done()
or the deprecated jqXHR.success()
.
false
in the beforeSend
function will cancel the request. As of jQuery 1.5, the beforeSend
option will be called regardless of the type of request.true, false for dataType 'script' and 'jsonp'
)false
, it will force requested pages not to be cached by the browser. Note: Setting cache
to false will only work correctly with HEAD and GET requests. It works by appending "_={timestamp}" to the GET parameters. The parameter is not needed for other types of requests, except in IE8 when a POST is made to a URL that has already been requested by a GET.success
and error
callbacks are executed). The function gets passed two arguments: The jqXHR (in jQuery 1.4.x, XMLHTTPRequest) object and a string categorizing the status of the request ("success"
, "notmodified"
, "error"
, "timeout"
, "abort"
, or "parsererror"
). As of jQuery 1.5, the complete
setting can accept an array of functions. Each function will be called in turn. This is an Ajax Event.'application/x-www-form-urlencoded; charset=UTF-8'
)$.ajax()
, then it is always sent to the server (even if no data is sent). The W3C XMLHttpRequest specification dictates that the charset is always UTF-8; specifying another charset will not force the browser to change the encoding.$.ajaxSettings
merged with the settings passed to $.ajax
). For example, specifying a DOM element as the context will make that the context for the complete
callback of a request, like so:
$.ajax({ url: "test.html", context: document.body }).done(function() { $( this ).addClass( "done" ); });
{"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}
)false for same-domain requests, true for cross-domain requests
)true
. This allows, for example, server-side redirection to another domain. (version added: 1.5)
processData
option to prevent this automatic processing. Object must be Key/Value pairs. If value is an Array, jQuery serializes multiple values with same key based on the value of the traditional
setting (described below).Intelligent Guess (xml, json, script, or html)
)cache
option is set to true
. Note: This will turn POSTs into GETs for remote-domain requests. null
or {}
instead. (See json.org for more information on proper JSON formatting.)cache
option is set to true
.null
) are "timeout"
, "error"
, "abort"
, and "parsererror"
. When an HTTP error occurs, errorThrown
receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." As of jQuery 1.5, the error
setting can accept an array of functions. Each function will be called in turn. Note: This handler is not called for cross-domain script and cross-domain JSONP requests. This is an Ajax Event. true
)true
. Set to false
to prevent the global handlers like ajaxStart
or ajaxStop
from being triggered. This can be used to control various Ajax Events.{}
)X-Requested-With: XMLHttpRequest
is always added, but its default XMLHttpRequest
value can be changed here. Values in the headers
setting can also be overwritten from within the beforeSend
function. (version added: 1.5)
false
)false
, ignoring the header. In jQuery 1.4 this technique also checks the 'etag' specified by the server to catch unmodified data.depends on current location protocol
)file
, *-extension
, and widget
. If the isLocal
setting needs modification, it is recommended to do so once in the $.ajaxSetup()
method. (version added: 1.5.1)
{jsonp:'onJSONPLoad'}
would result in 'onJSONPLoad=?'
passed to the server. As of jQuery 1.5, setting the jsonp
option to false
prevents jQuery from adding the "?callback" string to the URL or attempting to use "=?" for transformation. In this case, you should also explicitly set the jsonpCallback
setting. For example, { jsonp: false, jsonpCallback: "callbackName" }
jsonpCallback
is set to the return value of that function. true
)false
.charset
attribute on the script tag used in the request. Used when the character set on the local page is not the same as the one on the remote script.{}
)$.ajax({ statusCode: { 404: function() { alert( "page not found" ); } } });
error
callback.dataType
parameter; a string describing the status; and the jqXHR
(in jQuery 1.4.x, XMLHttpRequest) object. As of jQuery 1.5, the success setting can accept an array of functions. Each function will be called in turn. This is an Ajax Event.$.ajax
call is made; if several other requests are in progress and the browser has no connections available, it is possible for a request to time out before it can be sent. In jQuery 1.4.x and below, the XMLHttpRequest object will be in an invalid state if the request times out; accessing any object members may throw an exception. In Firefox 3.0+ only, script and JSONP requests cannot be cancelled by a timeout; the script will run even if it arrives after the timeout period.true
if you wish to use the traditional style of param serialization.'GET'
)The current page
)ActiveXObject when available (IE), the XMLHttpRequest otherwise
)XHR
object. For example, you can use it to set withCredentials
to true
for cross-domain requests if needed.$.ajax({ url: a_cross_domain_url, xhrFields: { withCredentials: true } });
withCredentials
property was not propagated to the native XHR
and thus CORS requests requiring it would ignore this flag. For this reason, we recommend using jQuery 1.5.1+ should you require the use of it.The $.ajax()
function underlies all Ajax requests sent by jQuery. It is often unnecessary to directly call this function, as several higher-level alternatives like $.get()
and .load()
are available and are easier to use. If less common options are required, though, $.ajax()
can be used more flexibly.
At its simplest, the $.ajax()
function can be called with no arguments:
$.ajax();
Note: Default settings can be set globally by using the $.ajaxSetup()
function.
This example, using no options, loads the contents of the current page, but does nothing with the result. To use the result, you can implement one of the callback functions.
Different types of response to $.ajax()
call are subjected to different kinds of pre-processing before being passed to the success handler. The type of pre-processing depends by default upon the Content-Type of the response, but can be set explicitly using the dataType
option. If the dataType
option is provided, the Content-Type header of the response will be disregarded.
The available data types are text
, html
, xml
, json
, jsonp
, and script
.
If text
or html
is specified, no pre-processing occurs. The data is simply passed on to the success handler, and made available through the responseText
property of the jqXHR
object.
If xml
is specified, the response is parsed using jQuery.parseXML
before being passed, as an XMLDocument
, to the success handler. The XML document is made available through the responseXML
property of the jqXHR
object.
If json
is specified, the response is parsed using jQuery.parseJSON
before being passed, as an object, to the success handler. The parsed JSON object is made available through the responseJSON
property of the jqXHR
object.
If script
is specified, $.ajax()
will execute the JavaScript that is received from the server before passing it on to the success handler as a string.
If jsonp
is specified, $.ajax()
will automatically append a query string parameter of (by default) callback=?
to the URL. The jsonp
and jsonpCallback
properties of the settings passed to $.ajax()
can be used to specify, respectively, the name of the query string parameter and the name of the JSONP callback function. The server should return valid JavaScript that passes the JSON response into the callback function. $.ajax()
will execute the returned JavaScript, calling the JSONP callback function, before passing the JSON object contained in the response to the $.ajax()
success handler.
For more information on JSONP, see the original post detailing its use.
By default, Ajax requests are sent using the GET HTTP method. If the POST method is required, the method can be specified by setting a value for the type
option. This option affects how the contents of the data
option are sent to the server. POST data will always be transmitted to the server using UTF-8 charset, per the W3C XMLHTTPRequest standard.
The data
option can contain either a query string of the form key1=value1&key2=value2
, or an object of the form {key1: 'value1', key2: 'value2'}
. If the latter form is used, the data is converted into a query string using jQuery.param()
before it is sent. This processing can be circumvented by setting processData
to false
. The processing might be undesirable if you wish to send an XML object to the server; in this case, change the contentType
option from application/x-www-form-urlencoded
to a more appropriate MIME type.