jQuery ajaxPrefilter() Method

What You’ll Learn

$.ajaxPrefilter() is jQuery’s extension point for intercepting every Ajax request before it leaves the browser. This tutorial covers registering global prefilters, the difference between merged options and caller-supplied originalOptions, scoping handlers with a dataTypes filter, modifying settings (headers, cache, custom flags), the official abortOnRetry pattern, returning a dataType string to redirect processing, and how prefilters fit between $.ajaxSetup() and beforeSend.

Introduction

When your app grows beyond a handful of $.ajax() calls, you often need the same cross-cutting behavior everywhere: attach an auth token, bust GET caches during development, abort stale autocomplete requests, or log traffic for debugging. Copy-pasting that logic into every call is brittle. jQuery solves this with jQuery.ajaxPrefilter() — a registration API that runs a handler before each Ajax request is processed and sent.

Prefilters sit in the pipeline after $.ajaxSetup() defaults are merged but before the per-request beforeSend callback and the actual network transport. That timing matters: you can rewrite URLs, inject headers, wrap beforeSend, store the returned jqXHR for later abort, or even return a dataType string to tell jQuery to treat the request differently. Every shorthand — $.get(), $.post(), .load() — flows through the same prefilter chain.

Understanding jQuery.ajaxPrefilter()

jQuery.ajaxPrefilter() does not send a request itself. It registers a function jQuery invokes for qualifying Ajax calls. Inside the handler you receive three arguments: the merged options object (what jQuery will use), the unmodified originalOptions from the caller, and the jqXHR object for this request. Mutate options to change behavior; inspect originalOptions when you need to know what the caller explicitly passed versus what came from global defaults.

Register prefilters once — typically when your application bootstraps — not inside every click handler. Multiple prefilters stack in registration order. Optional custom properties (like the documented abortOnRetry example) can live on the options object; your prefilter reads them and acts accordingly. Returning a string such as "script" or "json" from the handler redirects the request to that dataType and triggers any dataType-specific prefilters registered for it.

📝 Syntax

The official jQuery API accepts two signatures:

1. Global prefilter — jQuery.ajaxPrefilter( handler )

jQuery.ajaxPrefilter( handler )

Runs the handler before every Ajax request (all dataTypes).

2. dataTypes-scoped — jQuery.ajaxPrefilter( dataTypes, handler )

jQuery.ajaxPrefilter( dataTypes, handler )

dataTypes is a space-separated string such as "json" or "json script". The handler runs only when the request matches one of those types.

Handler arguments

• options — merged settings jQuery will use (includes $.ajaxSetup() defaults).
• originalOptions — the object passed to $.ajax() before defaults were applied.
• jqXHR — the jqXHR object for this request; store it to call .abort() later.

3. Official demo — typical registration

$.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
  // Modify options, inspect originalOptions, store jqXHR, etc.
  console.log( "Prefilter:", options.url );
} );

Return value

• $.ajaxPrefilter() returns undefined — it only registers handlers.
• Return a dataType string (e.g. "script") from the handler to redirect the request to that type.
• Mutating options affects the current request; registration is permanent until page unload.
• Prefilters run for shorthands too — $.get() and $.post() internally call $.ajax().

Examples Gallery

Five progressive examples from a basic log-and-modify prefilter through the official abort-on-retry pattern, JSON-scoped prefilters, forced GET cache busting, and global Authorization headers. Each links to a Try-it lab where you can edit and run the code in the browser.

$.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
  console.log( "Ajax prefilter:", options.url );

  // Merged options — safe to mutate for this request
  options.headers = $.extend( {}, options.headers, {
    "X-App-Client": "CodeToFun-Demo"
  } );
} );

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

Page loads → prefilter registered once

Click #load → console logs "Ajax prefilter: https://jsonplaceholder..."

Request includes X-App-Client header → .done() shows post title

var currentRequests = {};

$.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
  if ( options.abortOnRetry ) {
    if ( currentRequests[ options.url ] ) {
      currentRequests[ options.url ].abort();
    }
    currentRequests[ options.url ] = jqXHR;
  }
} );

$( "#search" ).on( "input", function() {
  var q = $( this ).val();
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/posts?q=" + encodeURIComponent( q ),
    abortOnRetry: true,
    dataType: "json"
  } ).done( function( posts ) {
    $( "#count" ).text( posts.length + " results" );
  } );
} );

User types quickly in #search

Each keystroke starts $.ajax with abortOnRetry: true

Prefilter aborts previous jqXHR to same URL → only latest .done() updates #count

$.ajaxPrefilter( "json", function( options, originalOptions, jqXHR ) {
  console.log( "JSON prefilter:", options.url );
  options.headers = $.extend( {}, options.headers, {
    "Accept": "application/json"
  } );
} );

$( "#load-user" ).on( "click", function() {
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/users/1",
    dataType: "json"
  } ).done( function( user ) {
    $( "#name" ).text( user.name );
  } );
} );

$( "#load-html" ).on( "click", function() {
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/posts/1",
    dataType: "html"
  } ).done( function() {
    $( "#name" ).text( "HTML request — JSON prefilter skipped" );
  } );
} );

Click #load-user → "JSON prefilter:" logged → user name shown

Click #load-html → JSON prefilter does NOT run → different message in #name

$.ajaxPrefilter( function( options ) {
  var method = ( options.type || options.method || "GET" ).toUpperCase();

  if ( method === "GET" && options.cache !== true ) {
    options.cache = false;
  }
} );

$( "#refresh" ).on( "click", function() {
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/posts/1"
  } ).done( function( post ) {
    $( "#log" ).text( "Fetched at " + new Date().toLocaleTimeString() + " — " + post.title );
  } );
} );

Each click on #refresh → fresh GET with _=timestamp query param

Prefilter sets cache: false → browser does not serve stale cached JSON

#log timestamp updates every click

var apiToken = "demo-token-abc123";

$.ajaxPrefilter( function( options, originalOptions, jqXHR ) {
  var previousBeforeSend = options.beforeSend;

  options.beforeSend = function( xhr, settings ) {
    xhr.setRequestHeader( "Authorization", "Bearer " + apiToken );

    if ( $.isFunction( previousBeforeSend ) ) {
      return previousBeforeSend.call( this, xhr, settings );
    }
  };
} );

$( "#fetch" ).on( "click", function() {
  $.ajax( {
    url: "https://jsonplaceholder.typicode.com/users/1",
    dataType: "json"
  } ).done( function( user ) {
    $( "#status" ).text( "Authorized fetch OK: " + user.email );
  } );
} );

Click #fetch → prefilter wraps beforeSend

Authorization: Bearer demo-token-abc123 sent on the wire

Public API ignores token but request succeeds → #status shows email

🚀 Common Use Cases

• Global auth headers — attach API tokens or session cookies via prefilter instead of repeating beforeSend on every call.
• Abort stale requests — autocomplete, typeahead, and fast-click scenarios — store jqXHR by URL or key and abort on retry.
• Development cache busting — force cache: false on GET during local testing without touching each endpoint call.
• Cross-domain proxy rewrite — detect crossDomain and rewrite options.url through your server proxy (official jQuery doc pattern).
• JSON-only instrumentation — register $.ajaxPrefilter("json", ...) to log or transform API traffic separately from HTML loads.
• Custom option flags — define app-specific properties (abortOnRetry, retryCount) read only by your prefilters.
• dataType redirection — return "script" from a prefilter when URL patterns imply script execution instead of HTML.

📝 Notes

• $.ajaxPrefilter() was added in jQuery 1.5 alongside Deferred-backed jqXHR — the same release that introduced .done() / .fail().
• Register prefilters once at application startup — not inside event handlers that fire repeatedly.
• options includes merged defaults; originalOptions is what the caller passed before merge.
• Returning a dataType string from a handler redirects processing and runs dataType-specific prefilters for that type.
• Custom properties on the options object (e.g. abortOnRetry) are for your code — jQuery ignores unknown keys.
• Prefilters run before beforeSend — ideal for wrapping or replacing beforeSend globally.
• Scoped prefilters use a space-separated dataTypes string: "json script" matches either type.
• There is no built-in $.ajaxUnprefilter() — avoid registering duplicate handlers on SPA re-init.

💡 Best Practices