jQuery ajaxTransport() Method

What You’ll Learn

$.ajaxTransport() is jQuery’s lowest-level Ajax extension point — a factory that returns custom { send, abort } objects to handle how bytes leave and enter the browser. This tutorial covers the factory pattern, returning undefined to fall through, the official image transport, a mock JSON transport without HTTP, cancelling with abort(), when standard $.ajax() is enough, and how transports fit after prefilters in the pipeline.

Introduction

Most Ajax tutorials stop at $.ajax({ url, dataType: "json" }) — and for everyday REST APIs, that is exactly where you should stop. jQuery already ships with transports for text, HTML, JSON, XML, and script over XMLHttpRequest. But when you need to load images through an Image object instead of XHR, simulate responses in unit tests, or talk to a non-HTTP data source, jQuery exposes jQuery.ajaxTransport( dataType, handler ).

A transport is not a global singleton. Each request gets its own instance because concurrent Ajax calls need isolated timers, DOM nodes, or sockets. You register a factory function that returns either a transport object { send, abort } or undefined to let jQuery try the next registered transport. The examples below walk from the skeleton pattern through jQuery’s official image transport, a beginner-friendly mock JSON demo, cancellable delayed responses, and when plain dataType: "json" beats custom code.

Understanding jQuery.ajaxTransport()

jQuery.ajaxTransport() does not send a network request by itself. It registers a handler jQuery invokes during transport selection — after $.ajaxSetup() merge and $.ajaxPrefilter() handlers, but before bytes move. The handler receives merged options, pristine originalOptions, and the per-request jqXHR object.

If your handler can handle the request (matching dataType, method, async flag, or custom URL scheme), return an object with two methods. send( headers, completeCallback ) starts transmission and eventually calls completeCallback( status, statusText, responses, headers ). abort() cancels an in-flight operation. If you cannot handle the request, return undefined — jQuery falls through to the default XMLHttpRequest transport or the next registered factory.

📝 Syntax

The official jQuery API accepts one signature:

1. Register a transport factory — jQuery.ajaxTransport( dataType, handler )

jQuery.ajaxTransport( dataType, handler )

dataType is a string identifying which requests invoke this factory — for example "image" or "mockjson". handler is a function function( options, originalOptions, jqXHR ) that returns a transport object or undefined.

2. Factory skeleton — fall through or return transport

$.ajaxTransport( dataType, function( options, originalOptions, jqXHR ) {
  if ( /* transportCanHandleRequest */ ) {
    return {
      send: function( headers, completeCallback ) {
        // Start transmission — call completeCallback when done
      },
      abort: function() {
        // Cancel in-flight work
      }
    };
  }
  // undefined → jQuery tries the next transport
});

3. completeCallback signature

function( status, statusText, responses, headers ) {}

Return value & registration behavior

• $.ajaxTransport() returns undefined — it only registers the factory; it does not perform a request.
• The factory runs during transport selection — after setup merge and prefilters, before beforeSend fires on the wire.
• Return undefined from the factory when your transport cannot handle the request — jQuery tries the next registered transport.
• Each request needs its own transport instance — the factory must return a new object every time, never a shared singleton.
• responses maps dataType keys to raw values — e.g. { image: imgElement } or { text: "...", json: {...} } for converters downstream.
• Like prefilters, registration can be scoped to a dataType string — only matching requests invoke your factory.

Examples Gallery

Five progressive examples from the factory skeleton through jQuery’s official image transport, an in-memory mock JSON transport, cancellable delayed responses, and a best-practice reminder that plain dataType: "json" needs no custom transport. Each links to a Try-it lab where you can edit and run the code in the browser.

$.ajaxTransport( "demo", function( options, originalOptions, jqXHR ) {
  // Only handle GET requests to URLs starting with "demo://"
  if ( options.type === "GET" && options.url.indexOf( "demo://" ) === 0 ) {
    return {
      send: function( headers, completeCallback ) {
        var payload = options.url.replace( "demo://", "" );
        completeCallback( 200, "success", { text: "Demo says: " + payload } );
      },
      abort: function() {
        // Nothing in-flight for this instant mock
      }
    };
  }
  // return undefined → jQuery tries the next transport (XHR)
} );

$( "#run-demo" ).on( "click", function() {
  $.ajax({
    url: "demo://Hello transport",
    dataType: "demo"
  }).done( function( text ) {
    $( "#log" ).text( text );
  } );
} );

Click #run-demo → factory matches demo:// URL + dataType "demo"

send() calls completeCallback immediately with status 200

#log shows "Demo says: Hello transport" — no HTTP request made

$.ajaxTransport( "image", function( s ) {
  if ( s.type === "GET" && s.async ) {
    var image;
    return {
      send: function( _, callback ) {
        image = new Image();
        function done( status ) {
          if ( image ) {
            var statusText = ( status === 200 ) ? "success" : "error",
                tmp = image;
            image = image.onreadystatechange = image.onerror = image.onload = null;
            callback( status, statusText, { image: tmp } );
          }
        }
        image.onreadystatechange = image.onload = function() {
          done( 200 );
        };
        image.onerror = function() {
          done( 404 );
        };
        image.src = s.url;
      },
      abort: function() {
        if ( image ) {
          image = image.onreadystatechange = image.onerror = image.onload = null;
        }
      }
    };
  }
} );

$( "#load-img" ).on( "click", function() {
  $.ajax({
    url: "https://picsum.photos/200",
    dataType: "image"
  }).done( function( img ) {
    $( "#preview" ).empty().append( img );
  } );
} );

Click #load-img → Image transport loads https://picsum.photos/200

onload fires → completeCallback(200, "success", { image: imgElement })

.done() receives the Image node → #preview shows the photo

$.ajaxTransport( "mockjson", function( options ) {
  if ( options.url.indexOf( "mockjson://" ) === 0 ) {
    return {
      send: function( headers, completeCallback ) {
        var id = options.url.replace( "mockjson://user/", "" );
        var fakeUser = {
          id: parseInt( id, 10 ) || 1,
          name: "Mock User " + id,
          email: "user" + id + "@example.test"
        };
        var jsonText = JSON.stringify( fakeUser );
        completeCallback( 200, "success", {
          text: jsonText,
          json: fakeUser
        } );
      },
      abort: function() {}
    };
  }
} );

$( "#fetch-mock" ).on( "click", function() {
  $.ajax({
    url: "mockjson://user/42",
    dataType: "mockjson"
  }).done( function( user ) {
    $( "#user" ).text( user.name + " — " + user.email );
  } );
} );

Click #fetch-mock → mockjson transport parses mockjson://user/42

completeCallback passes both text and json in responses

.done() receives parsed object → #user shows "Mock User 42 — user42@example.test"

$.ajaxTransport( "slowmock", function( options ) {
  if ( options.url.indexOf( "slowmock://" ) === 0 ) {
    var timerId;
    return {
      send: function( headers, completeCallback ) {
        timerId = setTimeout( function() {
          timerId = null;
          completeCallback( 200, "success", { text: "Slow response arrived" } );
        }, 3000 );
      },
      abort: function() {
        if ( timerId ) {
          clearTimeout( timerId );
          timerId = null;
        }
      }
    };
  }
} );

var pending;

$( "#start-slow" ).on( "click", function() {
  pending = $.ajax({
    url: "slowmock://wait",
    dataType: "slowmock"
  }).done( function( text ) {
    $( "#status" ).text( text );
  }).fail( function( _jqXHR, textStatus ) {
    $( "#status" ).text( "Request " + textStatus );
  } );
} );

$( "#cancel-slow" ).on( "click", function() {
  if ( pending ) {
    pending.abort();
    pending = null;
  }
} );

Click #start-slow → 3s timer starts in send()

Click #cancel-slow within 3s → abort() clears timer → .fail() → "Request aborted"

Wait full 3s without cancel → #status shows "Slow response arrived"

// No $.ajaxTransport needed — this is the right tool for HTTP JSON

$( "#load-json" ).on( "click", function() {
  $.ajax({
    url: "https://jsonplaceholder.typicode.com/users/1",
    dataType: "json"
  }).done( function( user ) {
    $( "#result" ).text( "Standard JSON: " + user.name + " (" + user.email + ")" );
  } ).fail( function() {
    $( "#result" ).text( "Request failed — no custom transport required to debug" );
  } );
} );

// Anti-pattern (do not do this for normal APIs):
// $.ajaxTransport("json", function() { ... reimplement XHR ... });

Click #load-json → default XHR transport fetches JSONPlaceholder

Built-in converter parses JSON → .done() receives user object

Zero custom transport code — simpler, tested, maintainable

🚀 Common Use Cases

• Image preloading — official pattern loads images via Image when dataType: "image" — lighter than XHR for pixel data.
• Custom URL schemes — handle app:// or mockjson:// URLs that never hit the network.
• Unit test mocks — return fake responses synchronously or after setTimeout without stubbing global XHR.
• Non-HTTP protocols — WebSocket, IndexedDB, or File API reads wrapped as Ajax for uniform .done() / .fail() chains.
• Binary or proprietary formats — populate responses with raw ArrayBuffer before converters run.
• Cancellable long polls — implement abort() to tear down connections when the user navigates away.
• Progressive enhancement fallback — register a transport for legacy environments where XHR cannot handle a specific dataType.

📝 Notes

• Last resort — jQuery docs rank transports after prefilters and converters — use only when those APIs are insufficient.
• $.ajaxTransport() was added in jQuery 1.5 alongside $.ajaxPrefilter(); it returns undefined.
• Each request requires its own transport instance — register a factory function, never a shared singleton object.
• Return undefined from the factory when your transport cannot handle the request — jQuery tries the next transport (usually XHR).
• completeCallback( status, statusText, responses, headers ) — responses keys must match formats your converters expect.
• abort() must cancel all async work and prevent late completeCallback invocations after jqXHR.abort().
• dataType-scoped registration works like prefilters — $.ajaxTransport("image", fn) runs only for dataType: "image" requests.
• For standard HTTP JSON, HTML, or script, the built-in XMLHttpRequest transport needs no custom registration.

💡 Best Practices