Categories

jQuery.each()

Categories: Utilities

jQuery.each( collection, callback(indexInArray, valueOfElement) )Returns: Object

Description: A generic iterator function, which can be used to seamlessly iterate over both objects and arrays. Arrays and array-like objects with a length property (such as a function's arguments object) are iterated by numeric index, from 0 to length-1. Other objects are iterated via their named properties.

  • jQuery.each( collection, callback(indexInArray, valueOfElement) )

    version added: 1.0

    collection   The object or array to iterate over.

    callback(indexInArray, valueOfElement)   The function that will be executed on every object.

The $.each() function is not the same as $(selector).each(), which is used to iterate, exclusively, over a jQuery object. The $.each() function can be used to iterate over any collection, whether it is a map (JavaScript object) or an array. In the case of an array, the callback is passed an array index and a corresponding array value each time. (The value can also be accessed through the this keyword, but Javascript will always wrap the this value as an Object even if it is a simple string or number value.) The method returns its first argument, the object that was iterated.

$.each([52, 97], function(index, value) { 
  alert(index + ': ' + value); 
});

This produces two messages:

0: 52

1: 97

If a map is used as the collection, the callback is passed a key-value pair each time:

var map = { 
  'flammable': 'inflammable', 
  'duh': 'no duh' 
}; 
$.each(map, function(key, value) { 
  alert(key + ': ' + value); 
});

Once again, this produces two messages:

flammable: inflammable
duh: no duh

We can break the $.each() loop at a particular iteration by making the callback function return false. Returning non-false is the same as a continue statement in a for loop; it will skip immediately to the next iteration.

  • Iterates through the array displaying each number as both a word and numeral

    HTML:
    
      <div id="one"></div>
      <div id="two"></div>
      <div id="three"></div>
      <div id="four"></div>
      <div id="five"></div>
    CSS:
    
      div { color:blue; }
      div#five { color:red; }
      
    Code:
    
        var arr = [ "one", "two", "three", "four", "five" ];
        var obj = { one:1, two:2, three:3, four:4, five:5 };
    
        jQuery.each(arr, function() {
          $("#" + this).text("Mine is " + this + ".");
           return (this != "three"); // will stop running after "three"
       });
    
        jQuery.each(obj, function(i, val) {
          $("#" + i).append(document.createTextNode(" - " + val));
        });
    
  • Iterates over items in an array, accessing both the current item and its index.

    Code:
    $.each( ['a','b','c'], function(i, l){
       alert( "Index #" + i + ": " + l );
     });
  • Iterates over the properties in an object, accessing both the current item and its key.

    Code:
    $.each( { name: "John", lang: "JS" }, function(k, v){
       alert( "Key: " + k + ", Value: " + v );
     });

jQuery.each( collection, [ overwrite ], callback(indexInArray, valueOfElement) )Returns: Object

Plugin: jQuery.each

Description: A generic iterator function, which can be used to seamlessly iterate over both objects and arrays. Arrays and array-like objects with a length property (such as a function's arguments object) are iterated by numeric index, from 0 to length-1. Other objects are iterated via their named properties.

  • jQuery.each( collection, [ overwrite ], callback(indexInArray, valueOfElement) )

    version added: 1.0

    collection   The object or array to iterate over.

    overwrite   A boolean indication whether to overwrite every object by the return value.

    callback(indexInArray, valueOfElement)   The function that will be executed on every object.

The $.each() function is not the same as .each(), which is used to iterate, exclusively, over a jQuery object. The $.each() function can be used to iterate over any collection, whether it is a map (JavaScript object) or an array. In the case of an array, the callback is passed an array index and a corresponding array value each time. (The value can also be accessed through the this keyword, but Javascript will always wrap the this value as an Object even if it is a simple string or number value.) The method returns its first argument, the object that was iterated.

We can break the $.each() loop at a particular iteration by making the callback function return false. Returning non-false is the same as a continue statement in a for loop; it will skip immediately to the next iteration.

If we set the overwrite argument, returning non-false and non-undefined will set a new value to current item.

  • Iterates over the properties in an object, accessing both the current item and its key.

    Code:
    $.each( { a: 0, b: 1, c: 2, d: 3, e: 4 }, true, function(key, value){
        alert( "Key: " + key + ", Value: " + value );
    
        return value >= 2 ? value+1 : false;
    });
    Results:
    { a: 1, b: 2, c: 3, d: 3, e: 4 }