jQuery ajaxSetup() Method

Beginner
8 min read
Updated: Oct 2026
5 examples
Live preview
Definition

What Is ajaxSetup()?

jQuery.ajaxSetup(options) (since 1.1) sets default Ajax options merged into every future $.ajax(), $.get(), $.post(), and .load() call until the next setup. It returns a PlainObject of merged ajaxSettings.

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

// url omitted → uses ping.php from setup
$.ajax({ data: { name: "Dan" } });

// Per-call options override setup
// Do NOT put success/error/complete in ajaxSetup
// Prefer $(document).on("ajaxSuccess", …) instead
NeedUse
Shared defaults (legacy)$.ajaxSetup({ … })
Safe shared defaultsWrapper: apiGet(path) → $.ajax(…)
Per-request logic$.ajaxPrefilter()
Global response handlers$(document).on("ajaxSuccess", fn)
One request only$.ajax({ … }) options
Approach

How to Use ajaxSetup()

Call once at bootstrap if you must — then every Ajax helper inherits those defaults.

  1. Pass a PlainObject of the same keys as $.ajax() (url, type, dataType, global, …).
  2. Later Ajax calls merge those defaults automatically.
  3. Override any key on a single call by passing it explicitly.
  4. Bind global callbacks with $(document).on("ajaxSuccess") — not inside setup.
  5. For new code, skip setup and use a wrapper or explicit options instead.
PieceRequired?Role
optionsYesDefault key/value pairs (same as $.ajax())
Return value—Merged ajaxSettings PlainObject
Per-call optionsOptionalOverride matching setup keys for that request
Next $.ajaxSetup()—Merges new keys into ajaxSettings

Pseudocode

Pseudocode
$.ajaxSetup(defaults)
    store defaults into jQuery.ajaxSettings
    return merged ajaxSettings

when $.ajax / $.get / $.post / .load runs:
    settings = merge(ajaxSettings, callerOptions)
    // callerOptions win on conflicts
    run ajaxPrefilter handlers on settings
    send request with settings
Reference

Cheat Sheet

Keep these facts handy when reading or refactoring legacy Ajax setup.

TopicDetail
Call$.ajaxSetup({ url, type, dataType, global, … })
Affects$.ajax, $.get, $.post, .load
OverridePass the same key on the individual request
SincejQuery 1.1
ReturnPlainObject (ajaxSettings)
CallbacksUse $(document).on("ajaxSuccess|ajaxError|ajaxComplete")
PipelineSetup merge → prefilters → beforeSend → send
Safer altWrapper function with explicit $.ajax({ … })
Try it

Live Preview

Apply a temporary dataType: "json" default, then run a bare $.get() that inherits it.

Demo uses a public JSON API. Needs network access. Setup is applied only for this widget.

Result
Ready — pick an action and click Run.
Code

jQuery Examples

Short, copy-ready snippets. Open DevTools Console, or use Try It Yourself for a live editor.

Example 1 — Default url

Official idea: set a base URL once, then omit url on later calls.

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

$("#load").on("click", function () {
  // url not set here — uses ajaxSetup default
  $.ajax({
    data: { _: Date.now() }
  }).done(function (post) {
    $("#result").text("Loaded: " + post.title);
  });
});
Try It Yourself

How It Works

  1. Setup. $.ajaxSetup() stores default url and dataType.
  2. Click. The handler calls $.ajax() without a url.
  3. Merge. jQuery fills in the setup url for this request.
  4. Done. The parsed JSON post title is shown in #result.

Example 2 — Default dataType: "json"

Shorthands like $.get() also inherit setup defaults.

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

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

How It Works

  1. Default. Setup sets dataType: "json" globally.
  2. Shorthand. $.get() calls $.ajax() under the hood.
  3. Parse. jQuery parses the response as JSON automatically.
  4. Risk. Plugins expecting HTML/script may break — another reason to avoid setup.

Example 3 — Per-Call Override

Explicit options on one request always beat setup defaults.

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

$("#users").on("click", function () {
  $.ajax({}).done(function (user) {
    $("#log").text("Setup URL: " + user.name);
  });
});

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

How It Works

  1. Setup. Default URL points at users.
  2. Inherit. Empty $.ajax({}) uses that URL.
  3. Override. The second call passes its own url.
  4. Keep. Unspecified keys (like dataType) still come from setup.

Example 4 — global: false + type: "POST"

Official combo: default URL, silent globals, and POST — then send only data.

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

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

$("#send").on("click", function () {
  $.ajax({
    data: { title: "Setup demo", body: "via defaults", userId: 1 }
  }).done(function (created) {
    $("#status").text("Created id: " + created.id);
  });
});
Try It Yourself

How It Works

  1. Defaults. Setup supplies URL, POST, JSON, and global: false.
  2. Minimal call. Only data is passed to $.ajax().
  3. Silent. Global events like ajaxStart skip this request.
  4. Caution. A global global: false also silences plugin Ajax.

Example 5 — Safer Wrapper (Recommended)

jQuery’s preferred approach: defaults live in your helper, not in shared ajaxSettings.

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

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

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

How It Works

  1. Scope. Defaults live inside apiGet, not global setup.
  2. Call. Your code uses the helper; plugins still use normal jQuery defaults.
  3. Explicit. Each request still goes through $.ajax() with clear options.
  4. Prefer. This is the pattern jQuery recommends instead of $.ajaxSetup().

Edge Cases & Pitfalls

Check these before relying on global Ajax defaults.

plugins

Affects every Ajax caller

Third-party widgets and analytics may inherit your URL, method, or headers unexpectedly.

callbacks

No success/error in setup

Global response handlers belong on $(document).on("ajaxSuccess") (and related events), not in the setup object.

merge

Setup merges into ajaxSettings

Each $.ajaxSetup() call updates matching keys in shared defaults — unset keys keep their previous values.

global

global: false is site-wide

As a setup default it silences Ajax events for every inheriting request, including ones you did not write.

Compatibility

Browser Support

jQuery.ajaxSetup() has been part of jQuery since 1.1. It works wherever your loaded jQuery Ajax transport runs.

✓ Stable · jQuery 1.1+

jQuery.ajaxSetup()

Supported across jQuery 1.x, 2.x, and 3.x in every browser that runs your jQuery build. Prefer current jQuery 3.x for modern projects — and prefer wrappers over global setup.

100% jQuery Ajax API
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
$.ajaxSetup() Universal

Bottom line: Technically available everywhere jQuery Ajax works. Architecturally risky on plugin-heavy pages — prefer explicit options or a scoped helper.

Analysis

Performance Notes

ApproachCostBest for
Explicit $.ajax({ … })CheapClear, safe call sites
Small wrapper helperCheapShared defaults you control
$.ajaxSetup()Cheap CPU · high riskLegacy only — avoid in new code
$.ajaxPrefilter()CheapConditional per-request logic

Setup itself is inexpensive. The cost is correctness: hidden global state is harder to reason about than a small helper or explicit options.

Remember

Key Takeaways

  • Role: merges default Ajax options into future requests.
  • Override: per-call options always win for that request.
  • Events: bind globals with .on("ajaxSuccess") — not setup callbacks.
  • Prefer: a scoped wrapper over mutating shared ajaxSettings.

One line: $.ajaxSetup() sets page-wide Ajax defaults — useful to understand in legacy code, risky to rely on in new code.

Frequently Asked Questions

It sets default option values that jQuery merges into every future Ajax request — including $.ajax(), $.get(), $.post(), and .load() — until the next $.ajaxSetup() call. It returns a PlainObject of the merged ajaxSettings. Per-call options override matching defaults.
Global defaults affect every Ajax caller on the page, including plugins that expect jQuery’s normal defaults. A plugin’s internal $.get() might suddenly use your URL, method, or headers. Prefer explicit options per call or a small wrapper around $.ajax().
Yes. Any option you pass to $.ajax(), $.get(), $.post(), or .load() overrides the matching setup key for that call only.
$.ajaxSetup() sets static defaults merged into each request. $.ajaxPrefilter() runs per request after that merge and can change options dynamically, abort, or return a dataType. Use prefilters for conditional logic; avoid setup for new global config.
Putting success, error, or complete in $.ajaxSetup() attaches them to every Ajax call, including plugins. Bind global handlers with $(document).on("ajaxSuccess"), ajaxError, and ajaxComplete instead.
Call $.ajaxSetup() again with the keys you want to change — it merges into ajaxSettings. Prefer avoiding global setup so resets are rarely needed; use a wrapper helper instead.

Next: ajaxTransport() Method

Learn custom Ajax transports with send() and abort() when prefilters are not enough.

ajaxTransport() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

jQuery.ajaxPrefilter() Method jQuery.ajaxTransport() Method