visualisation with d3 Selections and Selecting Elements

Preamble

Let's get access to the D3.js library so that we can begin. In this case, we'll be including the library using the HTML <script> tag.

<script src="https://d3js.org/d3.v7.js"></script>

Introduction

Selections are a D3.js concept that enables easy manipulation of the document object model (DOM), including attributes, styles, properties, HTML, and more. These manipulations can also be bound to data using data join¹.

In this section, we're going to look at a few D3.js functions that return selections.

A Container for the Output

This is where you will see the output of the code cells that follow it, provided they are referencing the corresponding id.

<div id="container"></div>

Creating an Empty SVG and Storing the Selection

In previous sections, we've created a new and detached <svg> element and then used the returned selection throughout the remainder of the section itself.

Let's do the same again but discuss a few things that are happening when this function is invoked.

svg = d3.create("svg");

The create(name) function expects the name parameter, so to create our <svg> element we'll need to pass in "svg" as our argument. We can see something is being returned and stored in our variable that we have also named svg. The something that's being returned is a single-element selection.

With this selection stored in svg we can start invoking the many supported functions that can manipulate the element itself.

For example, let's change the width of our <svg> element to 500. We can do this by using the selection stored in our svg variable, and invoking the .attr() function.

svg.attr("width", 500);

We'll come back to the .attr() function in more detail in future sections.

Appending an Element

The d3.append(name) function can be invoked on an existing selection to append a new element as the last child of that selection.

For example, we could use our selection stored in the svg variable and append a <circle> element.

var circle = svg
    .append("circle")
    .attr("cx", 250)
    .attr("cy", 75)
    .attr("r", 50);

The d3.append() function returns a selection referring to itself, which is how we can start changing the <circle> element's attributes by chaining the attr() function immediately aftwards. We've also stored the <circle> element's selection in our new variable, circle.

Selecting using CSS Selectors

Besides the d3.create() and d3.append() functions which return selections, we can use the d3.select() and d3.selectAll() functions to return selections by matching a CSS selector.

For example, we could select all <h2> elements in the current document with

allHeader2 = d3.selectAll("h2");

or we could select an element where id=container

container = d3.select("#container");

As we know that we've just appended a single <circle> element as a child of our <svg> element, we can safely use .select("circle") to get its selection. Although we already have its selection stored in the circle variable, let's use the .selection() function to demonstrate its usage, and change the circle's fill colour to purple.

svg
    .select("circle")
    .attr("fill", "#420a91");

Appending to the Container

Finally, let's append everything to our container.

d3
    .select("#container")
    .append(() => svg.node());

We can see the output by checking on our container with the corresponding id, which in this case is where id=container.

Conclusion

If we inspect the HTML, we will see the <svg> and <circle> elements have been added to the <div> where the id=container. We can also see that the <svg> element's width attribute has been modified, as has the <circle> element's fill colour attribute.

<div id="container">
  <svg width="500">
    <circle cx="250" cy="250" r="50" fill="#420a91"></circle>
  </svg>
</div>

In this section, we've already demonstrated how useful selections can be, and we haven't even touched on the manipulation of styles, properties, HTML, etc. We also haven't mentioned the things you can do with selections and data joins. We'll cover these in the following sections.