How the jQuery .ajaxSend() Function Works

This article provides a comprehensive guide on jQuery's .ajaxSend() event handler, explaining how it operates, its syntax, and how developers can utilize it to inspect or modify outgoing HTTP requests. You will learn about the parameters it passes to its callback function, how it compares to local AJAX callbacks, and how to implement it for common development tasks such as attaching authentication tokens and displaying global UI loaders.

What is jQuery .ajaxSend()?

The .ajaxSend() method is a global AJAX event handler in jQuery. It registers a callback function that executes whenever an AJAX request is about to be dispatched to the server. Because it is a global handler, it listens to all jQuery-driven AJAX calls—such as $.ajax(), $.get(), and $.post()—across your entire application, provided those requests have not explicitly disabled global events.

Syntax and Parameters

To attach the .ajaxSend() listener, you bind it to the document object:

$(document).ajaxSend(function(event, jqXHR, ajaxOptions) {
  // Logic executed before sending the request
});

The callback function receives three arguments:

  1. event: The standard jQuery Event object.
  2. jqXHR: The jQuery XMLHttpRequest object. This object wraps the browser's native XMLHttpRequest and allows you to set custom HTTP request headers using methods like jqXHR.setRequestHeader().
  3. ajaxOptions: The configuration options object used in the AJAX request. It contains properties such as ajaxOptions.url, ajaxOptions.type (e.g., GET, POST), and ajaxOptions.data.

Practical Use Cases

1. Attaching Authorization and CSRF Headers

A common use case for .ajaxSend() is attaching authentication headers or CSRF tokens globally without repeating the logic in every individual $.ajax() call.

$(document).ajaxSend(function(event, jqXHR, ajaxOptions) {
  // Add a CSRF token to all POST and PUT requests
  if (ajaxOptions.type === "POST" || ajaxOptions.type === "PUT") {
    var csrfToken = $('meta[name="csrf-token"]').attr('content');
    jqXHR.setRequestHeader('X-CSRF-Token', csrfToken);
  }
});

2. Displaying Loading Indicators

You can use .ajaxSend() to trigger visual feedback whenever network activity begins.

$(document).ajaxSend(function() {
  $('#loading-spinner').show();
});

3. Conditional Request Logging

Because ajaxOptions contains request details, you can log or inspect requests before they leave the browser:

$(document).ajaxSend(function(event, jqXHR, ajaxOptions) {
  console.log(`Sending ${ajaxOptions.type} request to: ${ajaxOptions.url}`);
});

Important Considerations

  • Global Event Suppression: If an individual request specifies global: false inside its options, .ajaxSend() will not trigger for that specific call.
  • Execution Order: .ajaxSend() runs immediately after the local beforeSend callback defined inside an individual $.ajax() request.
  • Document Attachment: Starting with jQuery 1.8, global AJAX events must be attached strictly to the $(document) selector; binding to arbitrary DOM elements is deprecated.