jQuery.extend()

jQuery

previous page next page

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
      Type: Object
      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.
    • object1
      Type: Object
      An object containing additional properties to merge in.
    • objectN
      Type: Object
      Additional objects containing properties to merge in.

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

    • deep
      Type: Boolean
      If true, the merge becomes recursive (aka. deep copy).
    • target
      Type: Object
      The object to extend. It will receive the new properties.
    • object1
      Type: Object
      An object containing additional properties to merge in.
    • objectN
      Type: Object
      Additional objects containing properties to merge in.

When two or more objects are supplied 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, you 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, you want to preserve both of the original objects, you can do so by passing an empty object as the target:

1
 
                                

                                  

                                    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.

Warning: Passing false for the first argument is not supported.

Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over. Properties that are an object constructed via new MyCustomObject(args), or built-in JavaScript types such as Date or RegExp, are not re-constructed and will appear as plain Objects in the resulting object or array.

On a deep extend, Object and Array are extended, but object wrappers on primitive types such as String, Boolean, and Number are not.

For needs that fall outside of this behavior, write a custom extend method instead.

Examples:

Example: Merge two objects, modifying the first.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <div id="log">
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                      var object1 = {
                                    

                                  

                                  

                                    

                                        apple: 0,
                                    

                                  

                                  

                                    

                                        banana: {weight: 52, price: 100},
                                    

                                  

                                  

                                    

                                        cherry: 97
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                      var object2 = {
                                    

                                  

                                  

                                    

                                        banana: {price: 200},
                                    

                                  

                                  

                                    

                                        durian: 100
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        /* merge object2 into object1 */
                                      
                                    

                                  

                                  

                                    

                                      $.extend(object1, object2);
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      var printObj = typeof JSON != "undefined" ? JSON.stringify : function(obj) {
                                    

                                  

                                  

                                    

                                        var arr = [];
                                    

                                  

                                  

                                    

                                        $.each(obj, function(key, val) {
                                    

                                  

                                  

                                    

                                          var next = key + ": ";
                                    

                                  

                                  

                                    

                                          next += $.isPlainObject(val) ? printObj(val) : val;
                                    

                                  

                                  

                                    

                                          arr.push( next );
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                        return "{ " +  arr.join(", ") + " }";
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      $("#log").append( printObj(object1) );
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

Example: Merge two objects recursively, modifying the first.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <div id="log">
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                      var object1 = {
                                    

                                  

                                  

                                    

                                        apple: 0,
                                    

                                  

                                  

                                    

                                        banana: {weight: 52, price: 100},
                                    

                                  

                                  

                                    

                                        cherry: 97
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                      var object2 = {
                                    

                                  

                                  

                                    

                                        banana: {price: 200},
                                    

                                  

                                  

                                    

                                        durian: 100
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        /* merge object2 into object1, recursively */
                                      
                                    

                                  

                                  

                                    

                                      $.extend(true, object1, object2);
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      var printObj = typeof JSON != "undefined" ? JSON.stringify : function(obj) {
                                    

                                  

                                  

                                    

                                        var arr = [];
                                    

                                  

                                  

                                    

                                        $.each(obj, function(key, val) {
                                    

                                  

                                  

                                    

                                          var next = key + ": ";
                                    

                                  

                                  

                                    

                                          next += $.isPlainObject(val) ? printObj(val) : val;
                                    

                                  

                                  

                                    

                                          arr.push( next );
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                        return "{ " +  arr.join(", ") + " }";
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      $("#log").append( printObj(object1) );
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <div id="log">
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

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

                                  

                                  

                                    

                                      var options = { validate: true, name: "bar" };
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        /* merge defaults and options, without modifying defaults */
                                      
                                    

                                  

                                  

                                    

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

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      var printObj = typeof JSON != "undefined" ? JSON.stringify : function(obj) {
                                    

                                  

                                  

                                    

                                        var arr = [];
                                    

                                  

                                  

                                    

                                        $.each(obj, function(key, val) {
                                    

                                  

                                  

                                    

                                          var next = key + ": ";
                                    

                                  

                                  

                                    

                                          next += $.isPlainObject(val) ? printObj(val) : val;
                                    

                                  

                                  

                                    

                                          arr.push( next );
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                        return "{ " +  arr.join(", ") + " }";
                                    

                                  

                                  

                                    

                                      };
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      $("#log").append( "<div><b>defaults -- </b>" + printObj(defaults) + "</div>" );
                                    

                                  

                                  

                                    

                                      $("#log").append( "<div><b>options -- </b>" + printObj(options) + "</div>" );
                                    

                                  

                                  

                                    

                                      $("#log").append( "<div><b>settings -- </b>" + printObj(settings) + "</div>" );
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>
 POWERED BYHERONOTE
previous page start next page