jQuery jQuery.extend() Method

What You’ll Learn

The jQuery.extend() utility merges properties from one or more objects into a target object. This tutorial covers shallow vs deep merge, the plugin defaults pattern, extending the jQuery namespace, five worked examples, comparisons with Object.assign(), and security notes for untrusted input.

Introduction

Real-world JavaScript often needs to combine configuration objects — default settings with user options, partial API responses with cached data, or feature flags spread across several sources. jQuery provides jQuery.extend() (also written $.extend()) as a battle-tested merge utility that has been part of the library since jQuery 1.0.

Unlike spread syntax or Object.assign(), which only perform shallow copies, $.extend(true, target, source) can recursively merge nested plain objects and arrays — a pattern plugin authors rely on every day.

Understanding the jQuery.extend() Method

jQuery.extend(target, object1 [, objectN]) copies enumerable properties from each source object into target. Later sources overwrite earlier ones for the same key. The method returns the modified target reference. Arguments that are null or undefined are skipped.

When the first argument is the boolean true, the merge becomes deep: nested plain objects and arrays are merged recursively instead of being replaced wholesale. Properties with value undefined are never copied.

📝 Syntax

Three common forms of jQuery.extend:

// Shallow merge into target
jQuery.extend( target, object1 [, objectN ] )

// Deep (recursive) merge
jQuery.extend( true, target, object1 [, objectN ] )

// Add properties to the jQuery namespace (single argument)
jQuery.extend( object )

Parameters

• target — the object that receives merged properties. It is modified in place.
• object1 … objectN — one or more source objects whose properties are copied into the target.
• true (optional first flag) — enables deep recursive merge. Passing false explicitly is not supported.

Return value

• Returns the target object (same reference, now containing merged properties).

Minimal workflow

var defaults = { limit: 5, debug: false };
var options  = { debug: true };

var settings = $.extend({}, defaults, options);
// settings → { limit: 5, debug: true }
// defaults → { limit: 5, debug: false }  (unchanged)

Examples Gallery

Each example uses $.extend(). Open DevTools or use the Try-it links to run them interactively.

var object1 = {
  apple: 0,
  banana: { weight: 52, price: 100 },
  cherry: 97
};
var object2 = {
  banana: { price: 200 },
  durian: 100
};

$.extend(object1, object2);

console.log(object1.banana);
// { price: 200 }  — weight: 52 is gone!

{ price: 200 }

var object1 = {
  apple: 0,
  banana: { weight: 52, price: 100 },
  cherry: 97
};
var object2 = {
  banana: { price: 200 },
  durian: 100
};

$.extend(true, object1, object2);

console.log(object1.banana);
// { weight: 52, price: 200 }  — weight preserved!

{ weight: 52, price: 200 }

var defaults = { validate: false, limit: 5, name: "foo" };
var options  = { validate: true, name: "bar" };

var settings = $.extend({}, defaults, options);

console.log("defaults:", JSON.stringify(defaults));
console.log("options:", JSON.stringify(options));
console.log("settings:", JSON.stringify(settings));

defaults: {"validate":false,"limit":5,"name":"foo"}
options: {"validate":true,"name":"bar"}
settings: {"validate":true,"limit":5,"name":"bar"}

var base   = { theme: "light", timeout: 5000, retries: 3 };
var env    = { timeout: 8000 };
var runtime = { retries: 1, debug: true };

var config = $.extend({}, base, env, runtime);

console.log(JSON.stringify(config));
// {"theme":"light","timeout":8000,"retries":1,"debug":true}

{"theme":"light","timeout":8000,"retries":1,"debug":true}

$.extend({
  greet: function (name) {
    return "Hello, " + name + "!";
  }
});

console.log($.greet("World"));  // "Hello, World!"

Hello, World!

🚀 Common Use Cases

• Plugin configuration — merge default options with caller-supplied settings.
• Layered config — combine base, environment, and runtime objects into one settings blob.
• Partial API merge — overlay a fresh response onto cached data without losing unrelated keys (use deep extend for nested fields).
• Register utilities — add functions to $ or $.fn via the single-argument or $.fn.extend forms.
• Clone with overrides — $.extend({}, original, patch) for immutable-style updates.
• Legacy codebases — consistent merge semantics predating native Object.assign and spread syntax.

📝 Notes

• Available since jQuery 1.0; deep merge since jQuery 1.1.4.
• Passing false as the deep flag is not supported — omit it or pass true.
• Deep-extending cyclical (circular) structures throws an error.
• Date, RegExp, and custom class instances are not reconstructed — they become plain objects in deep merge results.
• jQuery versions before 3.4 had a __proto__ pollution risk with deep extend on untrusted input — sanitize user objects in security-sensitive apps.
• For DOM plugin methods, use $.fn.extend() to add methods to jQuery selections, not the single-arg $.extend() form.

💡 Best Practices