Control flow

For advanced usage, selections provide methods for custom control flow.

selection.each(function)

Source · Invokes the specified function for each selected element, in order, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This method can be used to invoke arbitrary code for each selected element, and is useful for creating a context to access parent and child data simultaneously, such as:

parent.each(function(p, j) {
  d3.select(this)
    .selectAll(".child")
      .text(d => `child ${d.name} of ${p.name}`);
});

See sized donut multiples for an example.

selection.call(function, ...arguments)

Source · Invokes the specified function exactly once, passing in this selection along with any optional arguments. Returns this selection. This is equivalent to invoking the function by hand but facilitates method chaining. For example, to set several styles in a reusable function:

function name(selection, first, last) {
  selection
      .attr("first-name", first)
      .attr("last-name", last);
}

Now say:

d3.selectAll("div").call(name, "John", "Snow");

This is roughly equivalent to:

name(d3.selectAll("div"), "John", "Snow");

The only difference is that selection.call always returns the selection and not the return value of the called function, name.

selection.empty()

Source · Returns true if this selection contains no (non-null) elements.

d3.selectAll("p").empty() // false, here

selection.nodes()

Source · Returns an array of all (non-null) elements in this selection.

d3.selectAll("p").nodes() // [p, p, p, …]

Equivalent to:

Array.from(selection)

selection[Symbol.iterator]()

Source · Returns an iterator over the selected (non-null) elements. For example, to iterate over the selected elements:

for (const element of selection) {
  console.log(element);
}

To flatten the selection to an array:

const elements = [...selection];

selection.node()

Source · Returns the first (non-null) element in this selection. If the selection is empty, returns null.

selection.size()

Source · Returns the total number of (non-null) elements in this selection.