jQuery.extend() JQ Home  <<  Utilities  <<  jQuery.extend()

Object merge.

Description

The jQuery.extend() jQuery General utility method, merges the contents of two or more objects into the first specified object, optionally making the merge recursive.

Shorthand version $.extend()

  • When only one argument is passed to the jQuery.extend() jQuery General utility method, the jQuery object itself is assumed to be the target. This use of the signature allows us to add new functions to the jQuery namespace which may be useful for adding new methods to plugins as an example.
  • When two or more arguments are passed to the jQuery.extend() jQuery General utility method, all objects will be merged into the target (first) argument. The original objects can be kept in their original states by passing an empty object as the target.
  • When a property of the target object is itself an object or array, it will be completely overwritten by a property with the same key in the second object unless the deep parameter is set to true.
  • Bespoke objects and built-in JavaScript types are not re-constructed and will appear as plain Objects in the resulting object or array:
    • If the deep parameter is set to true, Array and Object are extended, but object wrappers on other primitive types are not.
  • Undefined properties are not re-constructed but properties inherited from the object's prototype will be.

Syntax

Signature Description
jQuery.extend( target [, object1] [, objectN] )Merge the contents of two or more objects into the first specified object.
jQuery.extend( [deep], target, object1 [, objectN] )Merge the contents of two or more objects into the first specified object, optionally making the merge recursive.

Parameters

Parameter Description Type
targetAn object that will receive the new properties from additional objects passed in, or that will extend the jQuery namespace if it is the sole argument.Object
object1An object containing additional properties to merge into the target object.Object
objectNAdditional object containing properties to merge into the target object.Object
deepUse true as the first argument to the signature to make the merge recursive. Passing a value of false is not supported.Boolean

Return

An Array object.

jQuery.extend( target [, object1] [, objectN] ) ExamplesUtilities  <<  Top

Merge the contents of two or more objects into the first specified object.

In the example below when we press left button below we create two objects obj1 and obj2 and then merge them together using jQuery.extend(). We then output a message displaying the new merged map for obj1. If you look at the output map displayed you will notice how the object map for the skills key gets overwritten and we lose some data as described under the Description heading for the method.

When we press right button we create two objects obj1 and obj2 and then merge them together using jQuery.extend(). The difference here with the signature is the target; what we are doing is passing an empty object which will then get passed to the target object on return as described under the Description heading for the method. We then output a message displaying the new merged map for target. Once again if you look at the output map displayed you will notice how the object map for the skills key gets overwritten and we lose some data because we are not doing a recursive merge of the objects.


$(function(){
  $('#btn12').one('click', function(){
    var obj1 = {species: 'penguin', skills: {flight: 'no', swim: 'yes'}, climate: 'cold'};
    var obj2 = {skills: {lactates: 'no'}, eats: 'fish'};
    $.extend(obj1, obj2);
    $('#div11').append('<pre>' + JSON.stringify(obj1) + ''</pre>'<br>');
  });
  $('#btn13').one('click', function(){
    var obj1 = {species: 'penguin', skills: {flight: 'no', swim: 'yes'}, climate: 'cold'};
    var obj2 = {skills: {lactates: 'no'}, eats: 'fish'};
    var target = $.extend({}, obj1, obj2);
    $('#div11').append('<pre>' + JSON.stringify(target));
  });
});

div11. Some initial text.

Press the button below to action the above code:

            

jQuery.extend( [deep], target, object1 [, objectN] ) ExamplesUtilities  <<  Top

Merge the contents of two or more objects into the first specified object, optionally making the merge recursive.

In the example below when we press left button we create two objects obj1 and obj2 and then merge them together using jQuery.extend(). In this signature the first parameter is set to true to allow for deep recursion. We then output a message displaying the new merged map for obj1. If you look at the output map displayed you will notice how the object map for the skills has been expanded to include all keys as we have used a 'deep' recursive merge of the objects.


$(function(){
  $('#btn14').one('click', function(){
    var obj1 = {species: 'dog', skill: {fly: 'no', swim: 'yes'}, climate: 'any'};
    var obj2 = {skill: {sing: 'no'}, eats: 'all'};
    $.extend(true, obj1, obj2);
    $('#div12').append('<pre>' + JSON.stringify(obj1));
  });
});

div12. Some initial text.

Press the button below to action the above code:

Related Tutorials

jQuery Intermediate Tutorials - Lesson 9 - jQuery General Utilities