jQuery ajaxSetup() Method

What You’ll Learn

$.ajaxSetup() configures default Ajax options merged into every future $.ajax(), $.get(), $.post(), and .load() call. This tutorial covers merge behavior, per-call overrides, jQuery’s official “not recommended” warning, why global success/error callbacks belong on $(document).on() instead, how setup fits before $.ajaxPrefilter() in the pipeline, and safer alternatives like explicit options or a small wrapper plugin.

Introduction

Before your app has dozens of $.ajax() calls, setting the same url prefix, dataType, or HTTP method on every line feels repetitive. jQuery offers jQuery.ajaxSetup( options ) to define those defaults once. Every subsequent Ajax call — including shorthands like $.get(), $.post(), and .load() — merges your setup object into its settings until the next $.ajaxSetup() invocation.

When you do encounter $.ajaxSetup() in the wild, understand that per-call options override setup defaults, that the method returns a merged PlainObject of ajaxSettings, and that global response handling belongs on $(document).on( "ajaxSuccess" ) — not in a success key inside setup. The examples below walk through official patterns adapted with JSONPlaceholder, plus a safer wrapper alternative for modern projects.

Understanding jQuery.ajaxSetup()

jQuery.ajaxSetup() does not send a network request. It mutates jQuery’s shared ajaxSettings defaults that every future Ajax helper merges into its per-request settings object. Call it once (or sparingly) at bootstrap — not inside click handlers. Options you set here apply page-wide until the next $.ajaxSetup() call replaces them entirely.

The same option keys documented for $.ajax() are valid — url, type / method, dataType, headers, global, cache, and more. After setup runs, a bare $.ajax({ data: { id: 1 } }) inherits whatever defaults you configured. Individual calls can still override any key by passing it explicitly in their own options object.

📝 Syntax

The official jQuery API accepts one signature:

1. Set defaults — jQuery.ajaxSetup( options )

jQuery.ajaxSetup( options )

options is a PlainObject of key/value pairs — the same settings available to $.ajax(). All keys are optional.

2. Official demo — default url

$.ajaxSetup({
  url: "ping.php"
});

// url not set here — uses ping.php from setup
$.ajax({
  data: { name: "Dan" }
});

3. Official demo — url, global: false, type: "POST"

$.ajaxSetup({
  url: "/xmlhttp/",
  global: false,
  type: "POST"
});

// Sends POST to /xmlhttp/ with myData — no extra options needed
$.ajax({ data: myData });

Return value & merge behavior

• $.ajaxSetup() returns a PlainObject — the merged ajaxSettings after your options are applied.
• Each new $.ajaxSetup() call replaces previous global defaults — it does not deep-stack multiple setup calls.
• Per-request options passed to $.ajax(), $.get(), $.post(), or .load() override matching setup keys for that call only.
• Setup merge happens before $.ajaxPrefilter() handlers and before the per-request beforeSend callback.
• Do not put success, error, or complete in setup — bind $(document).on( "ajaxSuccess" ), ajaxError, and ajaxComplete instead.

Examples Gallery

Five progressive examples from the official default-url pattern through dataType defaults, per-call overrides, the official global: false + POST combo, and a safer $.apiGet() wrapper that avoids global mutation. Each links to a Try-it lab where you can edit and run the code in the browser.

$.ajaxSetup({
  url: "https://jsonplaceholder.typicode.com/posts/"
});

$( "#load" ).on( "click", function() {
  // url not set here — setup supplies the base; we append the id
  $.ajax({
    url: "https://jsonplaceholder.typicode.com/posts/1",
    dataType: "json"
  }).done( function( post ) {
    $( "#result" ).text( "Loaded: " + post.title );
  } );
} );

Page loads → $.ajaxSetup registers base URL once

Click #load → $.ajax fetches /posts/1 (per-call url overrides setup base)

.done() shows post title in #result

$.ajaxSetup({
  dataType: "json"
});

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

$( "#load-posts" ).on( "click", function() {
  $.get( "https://jsonplaceholder.typicode.com/posts" )
    .done( function( posts ) {
      $( "#count" ).text( posts.length + " posts" );
    } );
} );

Both $.get() calls inherit dataType: "json" from setup

No manual dataType on each line → jQuery parses JSON automatically

#name and #count update from parsed objects

$.ajaxSetup({
  url: "https://jsonplaceholder.typicode.com/users/",
  dataType: "json"
});

$( "#same-base" ).on( "click", function() {
  // Uses setup url + appends id in the path via full url override pattern
  $.ajax({
    url: "https://jsonplaceholder.typicode.com/users/1"
  }).done( function( user ) {
    $( "#log" ).text( "Default base: " + user.name );
  } );
} );

$( "#different-url" ).on( "click", function() {
  $.ajax({
    url: "https://jsonplaceholder.typicode.com/posts/1",
    dataType: "json"
  }).done( function( post ) {
    $( "#log" ).text( "Override URL: " + post.title );
  } );
} );

Click #same-base → fetches /users/1 → #log shows user name

Click #different-url → explicit url overrides setup → #log shows post title

Per-call options always win over ajaxSetup defaults

$.ajaxSetup({
  url: "https://jsonplaceholder.typicode.com/posts",
  global: false,
  type: "POST",
  dataType: "json"
});

$(document).on( "ajaxStart", function() {
  $( "#global-log" ).append( "ajaxStart fired\n" );
} );

$( "#send" ).on( "click", function() {
  var myData = { title: "Setup demo", body: "Posted via defaults", userId: 1 };

  $.ajax({ data: myData })
    .done( function( created ) {
      $( "#status" ).text( "Created post id: " + created.id );
    } );
} );

Click #send → POST to /posts with myData (from setup defaults)

global: false → ajaxStart does NOT fire → #global-log stays empty

JSONPlaceholder returns fake created post → #status shows new id

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

function apiGet( path, data ) {
  return $.ajax({
    url: API_BASE + path,
    dataType: "json",
    data: data
  });
}

function apiPost( path, data ) {
  return $.ajax({
    url: API_BASE + path,
    type: "POST",
    dataType: "json",
    contentType: "application/json",
    data: JSON.stringify( data )
  });
}

$( "#fetch" ).on( "click", function() {
  apiGet( "/users/1" ).done( function( user ) {
    $( "#out" ).text( "Wrapper GET: " + user.email );
  } );
} );

$( "#create" ).on( "click", function() {
  apiPost( "/posts", { title: "Hi", body: "Safe defaults", userId: 1 } )
    .done( function( post ) {
      $( "#out" ).text( "Wrapper POST id: " + post.id );
    } );
} );

Click #fetch → apiGet("/users/1") with explicit defaults inside wrapper

Click #create → apiPost("/posts", ...) sends JSON POST

Plugins using raw $.get() unaffected — best practice for new code

🚀 Common Use Cases

• Legacy base URL — old apps that call $.ajaxSetup({ url: "/api/" }) once at startup — understand before refactoring.
• Default JSON dataType — API-heavy pages that assumed all responses are JSON — risky when plugins load HTML fragments.
• Silent Ajax module — global: false defaults to suppress ajaxStart / ajaxStop for background polling.
• Default POST for forms — official pattern sets type: "POST" so bare $.ajax({ data }) sends POST bodies.
• Reading merged settings — capture the PlainObject return value to inspect effective defaults after setup.
• Maintaining plugin-heavy pages — audit whether existing $.ajaxSetup() breaks widget or analytics plugin traffic.
• Migrating away from setup — replace globals with explicit options or apiGet() / apiPost() wrappers module by module.

📝 Notes

• Not recommended — jQuery’s official docs warn that $.ajaxSetup() can break plugins and other callers expecting default settings.
• $.ajaxSetup() was added in jQuery 1.1; it returns a merged PlainObject of ajaxSettings.
• Defaults apply to $.ajax(), $.get(), $.post(), and .load() until the next $.ajaxSetup() call.
• Per-call options override setup defaults for that request — explicit url, type, or dataType on the call wins.
• Do not put success, error, or complete in setup — use $(document).on( "ajaxSuccess" ), ajaxError, and ajaxComplete.
• Each $.ajaxSetup() invocation replaces prior global defaults — it does not accumulate layered setups.
• Setup merge runs before $.ajaxPrefilter() — prefilters see merged options including setup values.
• For new code, prefer explicit per-call options or a small wrapper plugin over mutating shared ajaxSettings.

💡 Best Practices