jQuery API

.each()

Categories: Miscellaneous > Collection Manipulation

.each( function(index, Element) ) Returns: jQuery

Description: Iterate over a jQuery object, executing a function for each matched element.

  • version added: 1.0.each( function(index, Element) )

    function(index, Element)A function to execute for each matched element.

The .each() method is designed to make DOM looping constructs concise and less error-prone. When called it iterates over the DOM elements that are part of the jQuery object. Each time the callback runs, it is passed the current loop iteration, beginning from 0. More importantly, the callback is fired in the context of the current DOM element, so the keyword this refers to the element.

Suppose we had a simple unordered list on the page:

<ul>
    <li>foo</li>
    <li>bar</li>
  </ul>

We can select the list items and iterate across them:

$('li').each(function(index) {
    alert(index + ': ' + $(this).text());
  });

A message is thus alerted for each item in the list:

0: foo
1: bar

We can stop the loop from within the callback function by returning false.

Examples:

Example: Iterates over three divs and sets their color property. 

<!DOCTYPE html>
<html>
<head>
  <style>
  div { color:red; text-align:center; cursor:pointer; 
        font-weight:bolder; width:300px; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<div>Click here</div>

  <div>to iterate through</div>
  <div>these divs.</div>
<script>
    $(document.body).click(function () {
      $("div").each(function (i) {
        if (this.style.color != "blue") {
          this.style.color = "blue";
        } else {
          this.style.color = "";
        }
      });
    });</script>
</body>
</html>

Demo:

Example: If you want to have the jQuery object instead of the regular DOM element, use the $(this) function, for example: 

<!DOCTYPE html>
<html>
<head>
  <style>
  ul { font-size:18px; margin:0; }
  span { color:blue; text-decoration:underline; cursor:pointer; }
  .example { font-style:italic; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	To do list: <span>(click here to change)</span>
  <ul>
    <li>Eat</li>
    <li>Sleep</li>

    <li>Be merry</li>
  </ul>
<script>
    $("span").click(function () {
      $("li").each(function(){
        $(this).toggleClass("example");
      });
    });

</script>
</body>
</html>

Demo:

Example: You can use 'return' to break out of each() loops early. 

<!DOCTYPE html>
<html>
<head>
  <style>
  div { width:40px; height:40px; margin:5px; float:left;
        border:2px blue solid; text-align:center; }
  span { color:red; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<button>Change colors</button> 
  <span></span>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div id="stop">Stop here</div>
  <div></div>

  <div></div>
  <div></div>
<script>
    $("button").click(function () {
      $("div").each(function (index, domEle) {
        // domEle == this
        $(domEle).css("backgroundColor", "yellow"); 
        if ($(this).is("#stop")) {
          $("span").text("Stopped at div index #" + index);
          return false;
        }
      });
    });

</script>
</body>
</html>

Demo:

Comments

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

  • Please do post corrections or additional examples for .each() 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.
  • analystz
    anyway to call a particular object in a collection directly? like: $("div").item(3) ??
  • Brian Scott
    Is there a callback function that can be used to execute another function after the each() has finished?
  • There is no need for a callback function. Any function that is placed after .each() will be executed after it.
    $('p').each(function() {
    // do something with paragraphs.
    });
    $('p').fadeOut(); // executes after .each() has finished
  • CB
    Is it possible to have "live" behavior using "each" ? Thanks.
  • does "continue" or "break" work?
  • No, they don't work here, because each() is not the same as a for loop. each() executes a callback function for each iteration, so you can return true to "continue" or return false to "break."

    As noted above, "We can stop the loop from within the callback function by returning false."
  • Szczepan2
    What does the second callback parameter do? If the callback is fired in the context of the current DOM element, then what is the purpose of the Element parameter for the callback? This is nowhere explained.