jQuery API

jQuery.extend()

Categories: Utilities

jQuery.extend( target, [ object1 ], [ objectN ] ) Returns: Object

Description: Merge the contents of two or more objects together into the first object.

  • version added: 1.0jQuery.extend( target, [ object1 ], [ objectN ] )

    target An object that will receive the new properties if additional objects are passed in or that will extend the jQuery namespace if it is the sole argument.

    object1An object containing additional properties to merge in.

    objectNAdditional objects containing properties to merge in.

  • version added: 1.1.4jQuery.extend( [ deep ], target, object1, [ objectN ] )

    deepIf true, the merge becomes recursive (aka. deep copy).

    targetThe object to extend. It will receive the new properties.

    object1An object containing additional properties to merge in.

    objectNAdditional objects containing properties to merge in.

When we supply two or more objects to $.extend(), properties from all of the objects are added to the target object.

If only one argument is supplied to $.extend(), this means the target argument was omitted. In this case, the jQuery object itself is assumed to be the target. By doing this, we can add new functions to the jQuery namespace. This can be useful for plugin authors wishing to add new methods to JQuery.

Keep in mind that the target object (first argument) will be modified, and will also be returned from $.extend(). If, however, we want to preserve both of the original objects, we can do so by passing an empty object as the target:

var object = $.extend({}, object1, object2);

The merge performed by $.extend() is not recursive by default; if a property of the first object is itself an object or array, it will be completely overwritten by a property with the same key in the second object. The values are not merged. This can be seen in the example below by examining the value of banana. However, by passing true for the first function argument, objects will be recursively merged.

Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over.

Examples:

Example: Merge two objects, modifying the first. 


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

$.extend(object1, object2);

Result:

object1 === {apple: 0, banana: {price: 200}, cherry: 97, durian: 100}

Example: Merge two objects recursively, modifying the first. 


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

$.extend(true, object1, object2);

Result:

object1 === {apple: 0, banana: {weight: 52, price: 200}, cherry: 97, lime: 100}

Example: Merge settings and options, modifying settings. 

var settings = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
jQuery.extend(settings, options);

Result:

settings == { validate: true, limit: 5, name: "bar" }

Example: Merge defaults and options, without modifying the defaults. This is a common plugin development pattern. 

var empty = {}
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
var settings = $.extend(empty, defaults, options);

Result:

settings == { validate: true, limit: 5, name: "bar" }
empty == { validate: true, limit: 5, name: "bar" }

Comments

  • Support requests, bug reports, and off-topic comments will be deleted without warning.

  • Please do post corrections or additional examples for jQuery.extend() below. We aim to quickly move corrections into the documentation.
  • If you need help, post at the forums or in the #jquery IRC channel.
  • Report bugs on the bug tracker or the jQuery Forum.
  • Discussions about the API specifically should be addressed in the Developing jQuery Core forum.
  • What happens if you do the following?
    - That is deep copy a jQuery selector.

    myObj = {
    someProp:"myProp",
    selector: {
    start: $("#myStart"),
    stop: $("#myStop")
    }
    };

    myCopy = $.extend(true,{},myObj);

    I'm concerned whether the myObj.selector object will deep copy the whole of jQuery as part of the process. My initial tests did not show any obvious speed hit, but it is rather a basic test right now.
  • using extend with deep set to true seems to have some quirks for RegExp. specifically, in my case, it clones the object perfectly except for my /regex/ which it stores as an empty object.

    ^-- this has been fixed in jQuery 1.4
  • alexboese
    I think that PHP array merge concepts are more in line with that of mainstream developers. I was looking at extend for about an hour trying to figure out why only one array populated into an array of arrays because both were zero indexed. While this is probably a great tool for combining config files, it's lousy at combining recordsets from disparate sources. You're better off renumbering the indexes yourself and merging, if that is your goal.
  • Property that is an array of objects doesn't seem to fit into these examples. Bump what John said.

    http://stackoverflow.com/questions/2731202/jquery-extend-not-giving-deep-copy-of-object-formed-by-constructor
  • John
    Could you please document the behavior for array values with 'deep'?
  • myguest
    is there any function which does exactly the opposite of the $.extend method ?
    looked through api, but couldn't find anything!
    Thanks for any advice!
  • Nope. You'll have to manually iterate over an object (with $.each) extracting the values you want and `delete`ing them as you go.
  • var copy = $.extend({}, "aString")
    returns an object like this
    copy = {
    0: "a",
    1: "S",
    2: "t",...
    }
    Wouldn't it be nice to return the same string?
  • You can use $.extend({}, {"aString"}) instead.