Open your local copy of the following file in your web browser:

https://github.com/NickQiZhu/d3-cookbook/blob/master/src/chapter2/selection-iteration.html

D3 selection object provides simple iterator interface to perform iteration in a similar fashion as how you will iterate through a JavaScript array. In this example we will iterate through three selected div elements we worked with in the previous recipe and annotate them with an index number.

<div></div>
<div></div>
<div></div>

<script type="text/javascript">
d3.selectAll("div") // <-- A
            .attr("class", "red box") // <-- B
            .each(function (d, i) { // <-- C
            d3.select(this).append("h1").text(i); // <-- D
         });
</script>

The preceding code snippet produces the following visual:

Selection iteration

This example is built on top of what we have already seen in the previous section. Additional to selecting all the div elements on the page at line A and setting their class attributes at line B, in this example we call the each function on the selection to demonstrate how you can iterate through a multi-element selection and process each element respectively.

The selection.each(function) function: The each function takes an iterator function as its parameter. The given iterator function can receive two optional parameters d and i with one more hidden parameter passed in as the this reference which points to the current DOM element object. The first parameter d represents the datum bound to this particular element (if this sounds confusing to you, don't worry we will cover data binding in depth in the next chapter). The second parameter i is the index number for the current element object being iterated through. This index is zero-based meaning it starts from zero and increments each time a new element is encountered.

The selection.append(name) function: Another new function introduced in this example is the append function. This function creates a new element with the given name and appends it as the last child of each element in the current selection. It returns a new selection containing the newly appended element. Now with this knowledge, let's take a closer look at the code example in this recipe.

d3.selectAll("div") // <-- A
    .attr("class", "red box") // <-- B
    .each(function (d, i) { // <-- C
        d3.select(this).append("h1").text(i); // <-- D
    });

The iterator function is defined on line C with both d and i parameters. Line D is a little bit more interesting. At the beginning of line D, the this reference is wrapped by the d3.select function. This wrapping essentially produces a single element selection containing the current DOM Element. Once wrapped, the standard D3 selection manipulation API can then be used on d3.select(this). After that the append("h1") function is called on the current element selection which appends a newly created h1 element to the current element. Then it simply sets the textual content of this newly created h1 element to the index number of the current element. This produces the visual of numbered boxes as shown in this recipe. Again you should notice that the index starts from 0 and increments 1 for each element.