jQuery ajax() Method

What You’ll Learn

$.ajax() is jQuery’s full-featured HTTP client. This tutorial covers the settings object, the jqXHR object it returns, chaining .done(), .fail(), and .always(), sending GET and POST data, parsing JSON with dataType, opting out of global events with global: false, and when to reach for shorthands like $.get() instead.

Introduction

Every jQuery Ajax call — whether you write $.ajax(), $.get(), $.post(), or .load() — ultimately goes through jQuery.ajax(). It is the configurable foundation: you pass a settings object describing the URL, HTTP method, payload, expected response type, and what to do when the server answers.

Unlike one-line shorthands, $.ajax() exposes the full surface area of jQuery’s Ajax transport. You get beforeSend for last-minute header tweaks, dataType to tell jQuery how to parse the body, and global: false to keep a request invisible to document-level Ajax event listeners. The method returns a jqXHR object — chain .done(), .fail(), and .always() for clean, composable callbacks.

Understanding jQuery.ajax()

jQuery.ajax() sends an asynchronous HTTP request and returns immediately with a jqXHR object. That object wraps the underlying XMLHttpRequest (or transport jQuery selects) and implements jQuery’s Deferred/Promise interface, so you can attach success and error handlers after the call returns.

Configure the request through a plain JavaScript settings object. Common keys include url, method (alias type), data, dataType, beforeSend, cache, and global. When global is true (the default), jQuery fires global Ajax events on document — ajaxStart, ajaxSend, ajaxSuccess, and the rest — which power site-wide loading spinners and analytics hooks.

📝 Syntax

The official jQuery API accepts two signatures:

1. Settings object — jQuery.ajax( settings )

jQuery.ajax( settings )

Pass a single object with at least url. All other options are optional.

2. URL + settings — jQuery.ajax( url [, settings ] )

jQuery.ajax( url [, settings ] )

Shorthand when the URL is the most important detail — settings merge on top.

Key settings options

• url — string; the endpoint to request (required unless set globally via $.ajaxSetup()).
• method (or type) — HTTP verb: "GET", "POST", "PUT", "DELETE", etc. Default is "GET".
• data — plain object, string, or array sent with the request. For GET, appended as query string; for POST, sent in the body (default application/x-www-form-urlencoded).
• dataType — expected response type: "json", "html", "text", "xml", or "script". jQuery parses the body accordingly before callbacks run.
• beforeSend — function(jqXHR, settings) invoked after the request is created but before it is sent — set headers or cancel with return false.
• global — boolean; when false, the request does not trigger global Ajax events on document. Default is true.
• cache — boolean; when false, jQuery appends a cache-busting query parameter on GET requests. Default is true for GET, false for script/dataType script.

3. Official demo — .done() / .fail() / .always()

$.ajax( {
  url: "https://jsonplaceholder.typicode.com/posts/1",
  dataType: "json"
} )
  .done( function( data ) {
    console.log( "Success:", data.title );
  } )
  .fail( function( jqXHR, textStatus, errorThrown ) {
    console.log( "Error:", textStatus, errorThrown );
  } )
  .always( function() {
    console.log( "Finished — success or failure" );
  } );

Return value

• $.ajax() returns a jqXHR object — a superset of XMLHttpRequest with Deferred methods.
• Chain .done(fn), .fail(fn), .always(fn), .then(fn) on the returned jqXHR.
• Call jqXHR.abort() to cancel an in-flight request.
• Read jqXHR.status, jqXHR.responseText, and jqXHR.getAllResponseHeaders() like a native XHR.

Examples Gallery

Five progressive examples from a basic GET with .done() through JSON parsing, the two-argument signature, and global: false. Each links to a Try-it lab where you can edit and run the code in the browser.

$( "#load" ).on( "click", function() {
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/posts/1",
    dataType: "json"
  } )
    .done( function( data ) {
      $( "#result" ).text( "Title: " + data.title );
    } )
    .fail( function() {
      $( "#result" ).text( "Request failed." );
    } );
} );

User clicks #load → $.ajax GET runs

Server returns JSON → .done() fires → #result shows "Title: ..."

Network or server error → .fail() runs instead

$( "#save" ).on( "click", function() {
  var title = $( "#title" ).val();

  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/posts",
    method: "POST",
    data: {
      title: title,
      body: "Created from jQuery.ajax()",
      userId: 1
    }
  } )
    .done( function( response ) {
      $( "#log" ).text( "Created post id: " + response.id );
    } );
} );

User enters title and clicks #save

jQuery serializes data object → POST body

Server responds 201 → .done() shows "Created post id: 101" (demo API)

function loadUser( userId ) {
  return $.ajax( {
    url: "https://jsonplaceholder.typicode.com/users/" + userId,
    dataType: "json"
  } )
    .done( function( user ) {
      $( "#name" ).text( user.name );
      $( "#email" ).text( user.email );
    } )
    .fail( function( jqXHR, textStatus ) {
      $( "#name" ).text( "Could not load user (" + textStatus + ")" );
    } )
    .always( function() {
      $( "#spinner" ).hide();
    } );
}

loadUser( 1 );

Valid user id → .done() fills #name and #email

404 or network error → .fail() shows error message

Either outcome → .always() hides #spinner

var apiBase = "https://jsonplaceholder.typicode.com";

$( "#fetch-comments" ).on( "click", function() {
  $.ajax( apiBase + "/posts/1/comments", {
    dataType: "json",
    cache: false
  } )
    .done( function( comments ) {
      var html = comments.map( function( c ) {
        return "<li>" + c.email + ": " + c.body + "</li>";
      } ).join( "" );
      $( "#list" ).html( html );
    } );
} );

Click #fetch-comments → GET /posts/1/comments

.done() receives parsed JSON array → builds <li> list in #list

cache: false adds _=timestamp to avoid stale GET cache

$( document ).on( "ajaxStart", function() {
  $( "#overlay" ).show();
} ).on( "ajaxStop", function() {
  $( "#overlay" ).hide();
} );

// Visible request — triggers global events
$( "#load-main" ).on( "click", function() {
  $.ajax( { url: "https://jsonplaceholder.typicode.com/posts/1" } );
} );

// Silent prefetch — no overlay
$( "#prefetch" ).on( "click", function() {
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/posts/2",
    global: false
  } ).done( function( data ) {
    console.log( "Prefetched:", data.id );
  } );
} );

Click #load-main → #overlay appears (ajaxStart) then hides (ajaxStop)

Click #prefetch → request completes but overlay never shows

.done() on the prefetch still runs — only global events are skipped

🚀 Common Use Cases

• REST API calls — CRUD operations against JSON backends with dataType: "json" and method-specific verbs.
• Form submission — POST serialized form fields without a full page reload; update a message area in .done().
• Partial page updates — fetch HTML fragments with dataType: "html" and inject into a container with .html().
• Autocomplete / search — debounced GET requests; abort the previous jqXHR when the user types the next character.
• File uploads — combine with FormData, processData: false, and contentType: false for multipart uploads.
• Silent background sync — global: false prefetch so global loading indicators stay hidden.

📝 Notes

• $.ajax() is asynchronous — code after the call runs before the response arrives.
• Prefer .done() / .fail() / .always() over legacy success / error / complete settings properties.
• The return value is a jqXHR — store it to call .abort() or chain additional handlers.
• dataType: "json" parses the body; invalid JSON triggers .fail() even on HTTP 200.
• method is the modern name; type is an alias kept for backward compatibility.
• global: false skips document Ajax events but not per-request jqXHR callbacks.
• $.get(), $.post(), and .load() are thin wrappers around $.ajax().
• Set defaults for all requests with $.ajaxSetup({ ... }) — override per call in the settings object.

💡 Best Practices