DEV Community: Pierre Le Bras

D3 + Tippy = Easy Tooltips on Your Visualisations

Pierre Le Bras — Mon, 15 Mar 2021 11:51:00 +0000

In my previous post, I went over the basics of D3.js and explained how to build a simple bar chart with this tool. I also quickly introduced the event handling system to use interactivity on your chart. But while D3 is quite the comprehensive chart and data manipulation library, it falls short on a point that I think can be important with interactive visualisations: tooltips.

If you are unaware, tooltips are the small bubbles displayed next to your page's elements when you mouse over them. They are often used to provide additional information or guidance while keeping a clean interface.

So D3 doesn't provide resources for those yet. You could create your own very clever way of manipulating the DOM and inserting a new <div> floating around where you need it. For example, I have used Justin Palmer's solution for years, until it became outdated. Recently though, I have discovered Tippy.js and started using it in all of my D3 projects. Today I will show you how.

I will reuse my previous code as an example, so feel free to check out this post for more details. This code displays a simple bar chart, including update transitions and mouse over interactivity.

The Basic Idea

Our first task is to load Tippy and its dependency Popper (which deals with the tooltip placement) into our code. As recommended on Tippy's documentation, we will add it just before our own scripts:

<body>
    <h1>D3 Bar Chart Example</h1>
    <div id="barContainer"></div>

    <script src="https://unpkg.com/@popperjs/core@2"></script>
    <script src="https://unpkg.com/tippy.js@6"></script>

    <script type="text/javascript">
        // ...
    </script>
</body>

We will then create a function that will do the tooltip setup. You could easily just integrate it within our D3 update function (check the conclusion for a full code listing), this is purely to keep things clean for our example here:

// ...
function setTooltips(){

}
// ...

This function needs to accomplish two things:

set the tooltip content based on the bar data; and
tell tippy where our tooltips should originate from. For both steps, we need to grab our bar selection:

// ...
function setTooltips(){
    // select the bars
    bars = chart.selectAll('rect.bar');
}
// ...

To set the content of Tippy tooltips, you simply need to fill in the data-tippy-content attribute of your elements, which we can easily do and customise with each bar data using D3's .attr() method:

// ...
function setTooltips(){
    // select the bars
    bars = chart.selectAll('rect.bar');
    // set the tooltip content
    bars.attr('data-tippy-content', (d,i)=>{
        return `Key: ${d.key}, Value: ${d.value}`;
    });
}
// ...

Now each bar has an attribute that describes exactly what to put in the bar's tooltip. Here we simply want to see the element's key and value, for example: "Key: C, Value: 90"

For the next part, we will actually use Tippy to show and hide the tooltips when prompted (mouse over/out). For that, we simply need to call the function named ... tippy(). We just have to pass the DOM nodes that need to have a tooltip. The way to get these is by using D3's .nodes() function, which returns the DOM nodes associated with a selection:

// ...
function setTooltips(){
    // select the bars
    bars = chart.selectAll('rect.bar');
    // set the tooltip content
    bars.attr('data-tippy-content', (d,i)=>{
        return `Key: ${d.key}, Value: ${d.value}`;
    });
    // call tippy on the bars
    tippy(bars.nodes());
}
// ...

All that is left now is to actually call setTooltips() at the end of our update function:

// ...
function updateData(dataset){
    // ...
    setTooltips();
}
function setTooltips(){
    // ...
}
// ...

Et voilà:

Customising Tooltips

There are many ways you can customise your Tippy tooltips.

The first approach is to use CSS styles. Afterall, our tooltips are essentially div elements injected in the DOM, and can therefore be styled with your usual CSS:

.tippy-box{
    color: #fefefe;
    font-family: sans-serif;
    padding: 5px 8px;
    border-radius: 2px;
    opacity: 0.9;
    font-weight: bold;
}

The other approach is to use Tippy's props.

Props can be set in two ways. First, globally, for all the tooltips created with one tippy() call, by passing a props object as the second argument. Here, we just introduce some timing when showing and hiding tooltips:

// ...
function setTooltips(){
    bars = chart.selectAll('rect.bar');
    bars.attr('data-tippy-content', (d,i)=>{
        return `Key: ${d.key}, Value: ${d.value}`;
    })
    tippy(bars.nodes(),{
        delay: [400, 100],
        duration: [500, 200]
    })
}
// ...

The second way is to set props specifically on each element that will trigger a tooltip. In fact, we have already used this approach when setting the content of the tooltips. All you have to do is set an attribute data-tippy-<prop_name> on the elements. For example, we can set tooltip themes based on our data:

// ...
function setTooltips(){
    bars = chart.selectAll('rect.bar');
    bars.attr('data-tippy-content', (d,i)=>{
        return `Key: ${d.key}, Value: ${d.value}`;
    }).attr('data-tippy-theme', d=>{
        return d.value <= 30 ? 'red' : 'dark';
    })
    tippy(bars.nodes(),{
        delay: [400, 100],
        duration: [500, 200]
    })
}
// ...

Of course, this means we have to augment our styles a bit in the CSS:

.tippy-box{ /* ... */ }
.tippy-box[data-theme~='dark']{
    background-color: #222;
}
.tippy-box[data-theme~='red']{
    background-color: tomato;
}
/* styling the tooltip arrow */
.tippy-box[data-theme~='red'] > .tippy-arrow::before{
    /* make sure you match the border (top, bottom, ...)
       with the tooltip position */
    border-top-color: tomato;
}

For more details on styling tooltips with themes, check Tippy's documentation.

Now, we have tooltips turning red when the value of the bar is less than 30:

As you might have guessed, since we can set props globally and/or locally, it means you can also set a content prop for all tooltips if you wish: no need to set the same data-tippy-content repeatedly.

Removing Tooltips

One last thing about Tippy's tooltips. Because we called our setTooltips() function in our chart update process, removing bars that are no longer needed means that their attached tooltips are technically gone too.

But, there are a variety of reasons you might want to make sure these tooltips are gone forever even if only to avoid the classic animation/transition timing exceptions:

Fortunately, the tippy() actually returns instances of the tooltip objects created. What we can therefore do is:

save those in a global list (i.e. not declared in our setTooltips() scope); and
delete the previous tooltips whenever we want to draw new ones, using the .destroy() method.

// ...
let barTooltips = [];
function updateData(dataset){
    // ...
    setTooltips();
}
function setTooltips(){
    barTooltips.forEach(t=>t.destroy());
    // ...
    barTooltips = tippy(bars.nodes(),{
        // ...
    })
}

Conclusion

Tippy takes care of all the positioning and life-cycle issues you would normally have to handle when dealing with tooltips. And it also provides us with a lot of customisable options: placement, style, timing, etc.

But what I find fascinating, is that, at its bare-minimum and even with a little bit of customisation, it is so simple to use and incorporate into your existing projects. Even the ones that already make a lot of DOM manipulation, like data visualisations with D3.

Setting Up a JavaScript Build Process using Rollup

Pierre Le Bras — Sat, 16 Jan 2021 12:48:54 +0000

Notes:

The following instructions were inspired and updated from this blog post;
Since these instructions where written, some package might have been deprecated or moved, make sure to check their status, on their website or GitHub/npm pages;
This setup will use Node.js and npm (node package manager). Follow this link for installation instructions.

Content:

Goals
Getting Started
Rollup
- Testing the Configuration
Babel
ESLint
Third-Party and Non-ES Modules Support
Enabling the ENV Variable
Terser
Less and PostCSS
Automating Builds
Building Multiple Modules
Final Notes
- Using Builds
- Managing Warnings
- Final Project Structure

Goals

The goal of this setup is to allow the development and build of multiple JavaScript front-end modules and associated stylesheets using Rollup.
The idea is to have a src folder where scripts and styles can be developed. These sources would then be processed and bundled together in an app folder, ready to be used in the browser:

-- project/
   |-- app/
   |   |-- dist/
   |   |   | // build modules (scripts and styles) go here
   |   |-- [main.js]
   |   |-- [main.css]
   |   |-- index.html
   |-- src/
   |   |-- scripts/
   |   |   | // JavaScript source code goes here
   |   |-- styles/
   |   |   | // Less stylesheet sources go here

While setting up this process, we will explore many aspects of the modern JavaScript ecosystem: bundling, transpiling, linting, and minifying.

Getting Started

First, we are going to create a project directory, add the above project structure, and enter the project directory:

mkdir -p project/{app/dist, src/{scripts,styles}} 
touch project/app/index.html
cd project

We can then initialise a node project by typing the next command and following the instructions:

npm init

It will create a package.json file for us, which describes the scope and dependencies of the project.

Rollup

Rollup.js is a module bundler for JavaScript: it gets pieces of code that are dependent on each other to create a larger, self-contained module. It uses the standardized module format introduced in ES6. Rollup also uses a tree-shaking approach to bundling, removing unused pieces of code which could bulk your module unnecessarily.

To add it to the project, we type in the following command:

npm install --save-dev rollup

--save-dev is an option that tells npm we want this library to be saved as a project dependency, in particular for development purposes (as opposed to dependencies for the code itself). If you check the package.json file, you will see the following added:

// package.json
"devDependencies": {
    "rollup": "^2.36.1"
}

Although the version number might be different.

Next, we are going to create a configuration file for Rollup, rollup.config.js:

// rollup.config.js
export default {
  input: 'src/scripts/foo.js',
  output: {
    file: 'app/dist/foo.js',
    format: 'iife',
    name: 'Foo',
    sourcemap: 'inline'
  }
}

input is the file we want Rollup to process and bundle sources from;
output contains the options for our built module:
- file is where we want the bundle saved;
- format lets us choose one of the many JavaScript flavor our bundle will have, check the options list there. Here we choose iife which will wrap the module in a self-executed function (immediately-invoked function expression), making the module declare itself in its own scope to avoid clashing with other scripts;
- name is the name we want to use when referring to the module in the front-end app, e.g. const bar = Foo.bar();, note that it is only useful if the script we build has an export statement;
- sourcemap lets us describe how we want the module sourcemap to be generated, a sourcemap is extremely useful when debugging code. Here chose inline to have it contained in the generated bundled module file.

Testing the Configuration

Let's give a quick test to Rollup and our configuration. Inside src/scripts we will create a directory utils and add an operations.js file in it:

mkdir src/scripts/utils
touch src/scripts/utils/operations.js

operations.js will contain two functions, sum and prod, both returning the sum and the product of two arguments respectively. These two functions are exported by the operations module:

// src/scripts/operations.js
const sum = (a,b)=>{ return a+b; }
const prod = (a,b)=>{ return a*b; }
export {sum, prod};

Inside src/scripts we will create the module foo.js:

touch src/scripts/foo.js

Which will load the functions from operations.js and log the result of a sum on two variables:

// src/scripts/foo.js
import {sum, prod} from './utils/operations.js';
const A = 4;
const B = 5;
export default function(){
    console.log(sum(A,B));
}

We can then run Rollup on src/scripts/foo.js, note the option -c which tells Rollup to use the configuration file we have made earlier:

./node_modules/.bin/rollup -c

And then check the resulting module in app/dist/foo.js:

// app/dist/foo.js
var Foo = (function () {
    'use strict';

    const sum = (a,b)=>{
        return a+b;
    };

    const A = 4;
    const B = 5;

    function foo () {
      console.log(sum(A, B));
    }

    return foo;

}());
//# sourceMappingURL= ...

Right then we can note a few things:

the content of operations.js and foo.js have been bundled together;
only the function sum was extracted from operations, that the tree-shaking from Rollup: because foo.js does not use prod, there is no need to bundle it;
the sourcemap has been added to the file

Babel

Babel is a JavaScript transpiler, taking code following modern JavaScript standards and producing the corresponding code in earlier versions of JavaScript with more browser support. We are first going to add two packages from Babel:

 npm install --save-dev @babel/core @babel/preset-env

And then one Rollup plugin to integrate Babel:

 npm install --save-dev @rollup/plugin-babel

Next, we can create the configuration file for Babel, .babelrc, telling it which preset to use when transpiling:

// .babelrc
{
    "presets": [
        ["@babel/preset-env", {
            "modules": false
        }]
    ]
}

The env preset is a smart preset that uses Browserlist under the hood to determine which syntax is best to transpile to.
The final step is to let Rollup know that it should call babel during the bundling process. To do so we are going to update the Rollup configuration file:

// rollup.config.js
import babel from '@rollup/plugin-babel';

export default {
    input: 'src/scripts/foo.js',
    output: { ... },
    plugins: [
        babel({
            exclude:'node_modules/**',
            babelHelpers: 'bundled'
        })
    ]
}

After importing the babel plugin, we call it in the plugins list and instruct it to ignore the code from dependencies
Now, when running Rollup:

./node_modules/.bin/rollup -c

We get the following result in app/dist/foo.js:

// app/dist/foo.js
var Foo = (function () {
    'use strict';

    var sum = function sum(a, b) {
      return a + b;
    };

    var A = 8;
    var B = 9;

    function foo () {
      console.log(sum(A, B));
    }

    return foo;

}());
//# sourceMappingURL=

Because we used the defaults browserslist configuration, the sum function has been changed from an arrow definition to a normal function statement, and const has been replaced with var.

If we were to enter "browserslist": ["last 2 Chrome versions"] in our package.json (meaning we are targeting an environment limited to the last 2 versions of Chrome), there would not be any changes to the bundle, given that the last versions of Chrome are fully compatible with ES6 features.

ESLint

ESLint is a linter, a program that will analyse our code to correct syntax and detect problems (missing brackets/parentheses, unused variables, etc.) during the build process. We are first going to add it to our project:

npm install --save-dev eslint

As well as a Rollup plugin for it:

npm install --save-dev @rollup/plugin-eslint

Next, we need to configure ESLint, using the .eslintrc.json file, which can be done by using the following command:

./node_modules/.bin/eslint --init

ESLint will then prompt a series of questions to initialise the configuration file:

? How would you like to use ESLint?
  > To check syntax and find problems
? What type of modules does your project use?
  > JavaScript modules (import/export)
? Which framework does your project use?
  > None of these
? Does your project use TypeScript?
  > No
? Where does your code run?
  > Browser
? What format do you want your config file to be in?
  > JSON

Our project should then include a new .eslintrc.json file, with this content:

// .eslintrc.json
{
    "env": {
        "browser": true,
        "es2021": true
    },
    "extends": "eslint:recommended",
    "parserOptions": {
        "ecmaVersion": 12,
        "sourceType": "module"
    },
    "rules": {
    }
}

We can then add more the list of rules, for example, having indents set to 4 spaces, using Unix linebreaks, using single quotes, enforcing semicolons at the end of each statement, and warning us of unused variables:

// .eslintrc.json
{ ...
    "rules":{
        "indent": ["warn", 4],
        "linebreak-style": ["warn", "unix"],
        "quotes": ["warn", "single"],
        "semi": ["warn", "always"],
        "no-unused-vars": ["warn"]
    }
}

Next, we can update rollup.config.js to include ESLint in the process:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';

export default {
    input: 'src/scripts/foo.js',
    output: { ... },
    plugins: [
        eslint({
            fix: true,
            exclude: ['./node_modules/**', './src/styles/**'],
        }),
        babel({ ... })
    ]
}

As with Babel, we have first imported it, before including it in the list of plugins. We have instructed it to ignore our styles files, and let fix some of the simpler issues silently (e.g. semicolons, indentation, etc.).
Now, when we run:

./node_modules/.bin/rollup -c

We can notice the following terminal output, informing us that foo.js defines (or imports) prod but does not use it.

/.../project/src/scripts/foo.js
  1:14  warning  'prod' is defined but never used  no-unused-vars

✖ 1 problem (0 errors, 1 warning)

And ESLint has fixed some of the trivial syntax issues for us:

// src/scripts/operations.js before build
const sum = (a,b)=>{
    return a+b;
};
const prod = (a,b)=>{
return a*b
}

export {sum, prod};

// src/scripts/operations.js after build
const sum = (a,b)=>{
    return a+b;
};
const prod = (a,b)=>{
    return a*b;
};

export {sum, prod};

Third-Party and Non-ES Modules Support

By default, Rollup does not load third party libraries from node_modules properly. To enable that we need to use another Rollup plugin, node-resolve:

npm install --save-dev @rollup/plugin-node-resolve

Then, while we are developing ES modules, some of our code dependencies in node_modules would have been developed in a non-ES module format: CommonJS. Trying to load these in our bundle will ultimately fail, but Rollup has a plugin to help with that, commonjs:

npm install --save-dev @rollup/plugin-commonjs

Once we have added those plugins to the project, we can add them the Rollup configuration:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
    input: 'src/scripts/foo.js',
    output: { ... },
    plugins: [
        resolve(),
        commonjs(),
        eslint({ ... }),
        babel({ ... })
    ]
}

Enabling the ENV Variable

Using environment variables can be helpful in the development process, for example turning logging on and off depending on the type of build we are doing, for development or production.
Let's add the following to src/scripts/foo.js:

// src/scripts/foo.js
...
if(ENV != 'production'){
    console.log('not in production');
}
...

A piece of code that logs a message when the build is not for production. However, the variable ENV is undefined there. To fix that we can add the Rollup plugin replace:

npm install --save-dev @rollup/plugin-replace

And use it in the configuration file:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import replace from '@rollup/plugin-replace';

export default {
    input: 'src/scripts/foo.js',
    output: { ... },
    plugins: [
        resolve(),
        commonjs(),
        eslint({ ... }),
        babel({ ... }),
        replace({
            exclude: 'node_modules/**',
            ENV: JSON.stringify(process.env.NODE_ENV || 'development'),
        })
    ]
}

What it will do is replace, in our bundle (excluding code that comes from third-party libraries in node_modules), the occurrences of ENV with the value of NODE_ENV or development by default. What we must remember is to update .eslintrc.json to let ESLint know that ENV is a global variable and not undeclared:

// .eslintrc.json
{
    "env": { ... },
    "globals": {
        "ENV": true
    },
    "extends": "eslint:recommended",
    "parserOptions": { ... },
    "rules": { ... }
}

Then when building normally:

./node_modules/.bin/rollup -c

app/dist/foo.js will include the following:

// app/dist/foo.js
...
{
    console.log('not in production');
}
...

However, building for production:

NODE_ENV=production ./node_modules/.bin/rollup -c

Will remove the code above from app/dist/foo.js.

Terser

Generating a bundle that has many dependencies, from our code or third-party packages, will result in a large JavaScript file. To optimize the bundle it is useful to integrate Terser into our build process. What Terser does is it removes comments, shorten variables names, cut whitespaces and minify our code to make it the shortest possible.
Again Terser can be integrated with Rollup using a plugin:

npm install --save-dev rollup-plugin-terser

And configure it in rollup.config.js:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import replace from '@rollup/plugin-replace';
import {terser} from 'rollup-plugin-terser';

export default {
    input: 'src/scripts/foo.js',
    output: {
        file: 'app/dist/foo.js',
        format: 'iife',
        name: 'Foo',
        sourcemap: (process.env.NODE_ENV === 'production' ? false : 'inline')
    },
    plugins: [
        resolve(),
        commonjs(),
        eslint({ ... }),
        babel({ ... }),
        replace({ ... }),
        (process.env.NODE_ENV === 'production' && terser())
    ]
}

Because it is useful to be able to inspect and see our code during development, we are only letting terser execute if NODE_ENV is set to production. Similarly, we have turned off the sourcemap in production to reduce the bundle size.
If we now build our module for production:

NODE_ENV=production ./node_modules/.bin/rollup -c

Here is how it looks:

// app/dist/foo.js
var Foo=function(){"use strict";return function(){console.log(8+9)}}();

Less and PostCSS

Now that we have addressed our scripts, we can focus on our styles. In this setup, we will look at the CSS preprocessor Less which lets us write CSS simpler, use variables and mixins. We can add it to the project with the following command:

npm install --save-dev less

To process Less files we will use PostCSS, which is a JavaScript build tool for CSS, Less, and other CSS preprocessors. It also comes with a built-in minifier. We can add it to the project with a Rollup plugin:

npm install --save-dev rollup-plugin-postcss

One of the most interesting features of PostCSS is Autoprefixer. Much like Babel, it checks our browserslist requirement to add prefixes to CSS rules, ensuring cross-browser compatibilities. We can add it to the project with the following command:

npm install --save-dev autoprefixer

We can now set this up with Rollup, in the configuration file:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import replace from '@rollup/plugin-replace';
import {terser} from 'rollup-plugin-terser';
import postcss from 'rollup-plugin-postcss';
import autoprefixer from 'autoprefixer';

export default {
    input: 'src/scripts/foo.js',
    output: { ... },
    plugins: [
        resolve(),
        commonjs(),
        eslint({ ... }),
        babel({ ... }),
        replace({ ... }),
        (process.env.NODE_ENV === 'production' && terser()),
        postcss({
            plugins: [autoprefixer()],
            inject: false,
            extract: true,
            sourceMap: (process.env.NODE_ENV === 'production' ? false : 'inline'),
            minimize: (process.env.NODE_ENV === 'production')
        })
    ]
}

As we can see, PostCSS calls Autoprefixer as a plugin, it uses Less in the background automatically when detecting Less files. The inject option lets us define whether the JavaScript module will inject styles in the <head> of our page (true) or not (false). Similarly, the extract option lets us define whether a separate stylesheet will be generated next to the JavaScript module (true) or not (false). This stylesheet will have the same filename as the JavaScript module, with a .css extension instead. Then, we set the sourcemap and minimize options depending on NODE_ENV as we did with the JavaScript module.
Processing a stylesheet can then be done by simply importing it in our JavaScript module:

/* src/styles/foo.less */
@clr: red;
h1{
  color: @clr;
}

// src/scripts/foo.js
import '../styles/foo.less';
...

NODE_ENV=production ./node_modules/.bin/rollup -c

/* app/dist/foo.css */
h1{color:red}

Automating Builds

The next step of this setup is to make use of node scripts to automate the build process.
First, we are going to install reload, an HTTP server program that comes with a live-reload functionality:

npm install --save-dev reload

Reload can then serve app/ to localhost and reload anytime it detects a change.
Meanwhile, Rollup comes with a watch option, -w, that keeps it listening to any changes in our source file to automatically re-build them. We can therefore combine the two in one Node script in our package.json:

// package.json
...
"scripts": {
    "serve": "./node_modules/.bin/reload -b -d ./app -p 8000 | ./node_modules/.bin/rollup -c -w"
}
...

Then, running:

npm run server

Will launch both Reload and Rollup: Rollup listening to any changes on the source file and re-building them, and Reload detecting changes in the build files and re-serving them on our test webpage localhost:8000.
We can then add a second script for production build:

// package.json
...
"scripts": {
    "serve": "./node_modules/.bin/reload -b -d ./app -p 8000 | ./node_modules/.bin/rollup -c -w",
    "build": "NODE_ENV=production ./node_modules/.bin/rollup -c"
}
...

Then, we can run the following to simply build our production application:

npm run build

Building Multiple Modules

Finally, we can setup rollup.config.js to allow multiple modules to be bundled separatley:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import replace from '@rollup/plugin-replace';
import {terser} from 'rollup-plugin-terser';
import postcss from 'rollup-plugin-postcss';
import autoprefixer from 'autoprefixer';

const srcDir = 'src/scripts/',
    distDir = 'app/dist/';

const plugins = () => [
    resolve(),
    commonjs(),
    eslint({ ... }),
    babel({ ... }),
    replace({ ... }),
    (process.env.NODE_ENV === 'production' && terser()),
    postcss({ ... })
];

function setupBuild(src, dist, name){
    return {
        input: srcDir+src,
        output: {
            file: distDir+dist,
            format: 'iife',
            name,
            sourcemap: (process.env.NODE_ENV === 'production' ? false : 'inline')
        },
        plugins:plugins()
    }
}

export default [
    setupBuild('foo.js', 'foo.js', 'Foo'),
    setupBuild('bar.js', 'bar.js', 'Bar')
]

Additional modules can be added using setupBuild. Note that we use a function to return plugins to "clean" their buffers.

Final Notes

Using Builds

The built modules can be simply loaded into an HTML page:

<!-- app.index.html -->
<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" href="dist/foo.css">
        <script src="dist/foo.js"></script>
    </head>
    <body>
        <h1>Hello World</h1>
        <script>
            Foo();
        </script>
    </body>
</html>

As any other JavaScript code, it will get executed upon loading. If the module exports a value (object or function), it can be accessed using the name given in the Rollup configuration (third parameter of setupBuild). For example: Foo(), Foo[...] or Foo.bar.

Managing Warnings

Some third-party libraries like d3.js will have circular dependencies within them, which Rollup will warn us about when building the module. To avoid getting many warning messages, we can add a warning filter to in the Rollup configuration:

// rollup.config.js
...
function setupBuild(src, dist, name){
    return {
        input: srcDir+src,
        output: { ... },
        plugins:plugins(),
        onwarn: function(warning, warner){
            // if circular dependency warning
            if (warning.code === 'CIRCULAR_DEPENDENCY'){
                // if comming from a third-party
                if(warning.importer && warning.importer.startsWith('node_modules/')){
                    // ignore warning
                    return;
                }
            }
            // Use default for everything else
            warner(warning);
        }
    }
}
...

Final Project Structure

This how the project directory should look like now:

-- project/
   |-- app/
   |   |-- dist/
   |   |   |-- foo.js
   |   |   |-- foo.css
   |   |-- index.html
   |-- src/
   |   |-- scripts/
   |   |   |-- utils/
   |   |   |   |-- operations.js
   |   |   |-- foo.js
   |   |-- styles/
   |   |   |-- foo.less
   |-- .babelrc
   |-- .eslintrc.json
   |-- package-lock.json
   |-- package.json
   |-- rollup.config.js

The package.json file should contain the following:

// package.json
{
  ...
  "scripts": {
    "serve": "./node_modules/.bin/reload -b -d ./app -p 8000 | ./node_modules/.bin/rollup -c -w",
    "build": "NODE_ENV=production ./node_modules/.bin/rollup -c"
  },
  ...
  "devDependencies": {
    "@babel/core": "^7.12.10",
    "@babel/preset-env": "^7.12.11",
    "@rollup/plugin-babel": "^5.2.2",
    "@rollup/plugin-commonjs": "^17.0.0",
    "@rollup/plugin-eslint": "^8.0.1",
    "@rollup/plugin-node-resolve": "^11.1.0",
    "@rollup/plugin-replace": "^2.3.4",
    "autoprefixer": "^10.2.1",
    "eslint": "^7.17.0",
    "less": "^4.1.0",
    "reload": "^3.1.1",
    "rollup": "^2.36.1",
    "rollup-plugin-postcss": "^4.0.0",
    "rollup-plugin-terser": "^7.0.2"
  },
  "browserslist": [
    "defaults"
  ]
  ...
}

.babelrc should look like this:

// .babelrc
{
    "presets": [
        ["@babel/preset-env", {
            "modules": false
        }]
    ]
}

.eslintrc.json should look like this:

// .eslintrc.json
{
    "env": {
        "browser": true,
        "es2021": true
    },
    "globals": {
        "ENV": true
    },
    "extends": "eslint:recommended",
    "parserOptions": {
        "ecmaVersion": 12,
        "sourceType": "module"
    },
    "rules": {
        "indent": ["warn", 4],
        "linebreak-style": ["warn", "unix"],
        "quotes": ["warn", "single"],
        "semi": ["warn", "always"],
        "no-unused-vars": ["warn"]
    }
}

And finally, rollup.config.js should have the following:

// rollup.config.js
import babel from '@rollup/plugin-babel';
import eslint from '@rollup/plugin-eslint';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import replace from '@rollup/plugin-replace';
import {terser} from 'rollup-plugin-terser';
import postcss from 'rollup-plugin-postcss';
import autoprefixer from 'autoprefixer';

const srcDir = 'src/scripts/',
    distDir = 'app/dist/';

const plugins = () => [
    resolve(),
    commonjs(),
    eslint({
        fix: true,
        exclude: ['./node_modules/**', './src/styles/**']
    }),
    babel({
        exclude: 'node_modules/**',
        babelHelpers: 'bundled'
    }),
    replace({
        exclude: 'node_modules/**',
        ENV: JSON.stringify(process.env.NODE_ENV || 'development')
    }),
    (process.env.NODE_ENV === 'production' && terser()),
    postcss({
        plugins: [autoprefixer()],
        inject: false,
        extract: true,
        sourceMap: (process.env.NODE_ENV === 'production' ? false : 'inline'),
        minimize: (process.env.NODE_ENV === 'production')
    })
]

function setupBuild(src, dist, name){
    return {
        input: srcDir+src,
        output: {
            file: distDir+dist,
            format: 'iife',
            name,
            sourcemap: (process.env.NODE_ENV === 'production' ? false : 'inline')
        },
        plugins:plugins(),
        onwarn: function(warning, warner){
            if (warning.code === 'CIRCULAR_DEPENDENCY'){
                if(warning.importer && warning.importer.startsWith('node_modules/')){
                    return;
                }
            }
            warner(warning);
        }
    }
}

export default[
    setupBuild('foo.js', 'foo.js', 'Foo')
]

Want to learn D3? Let's make a bar chart!

Pierre Le Bras — Mon, 28 Dec 2020 14:11:07 +0000

D3 is one of the most widely used JavaScript chart library out there. It is free, open-source, and while it may be daunting at first, it provides unlimited customisation for your interactive data visualisations.

I have taught it for many years now. We usually have to accommodate for a variety of experiences from students and teach using examples they have to complete, but some of the more hands-on learners sometimes need to do things by themselves from start to finish.

While I was not too sure what to tell them at first, I realise over time that a great way to play with D3 for beginners is to make bar charts.

It may seem trivial at first (and compared to other charts, it is), but making a bar chart in D3 actually lets you explore quite the number of key concepts for you to progress further. So let's get started.

What we want to achieve

Normally we would match the chart to the type of data we are given, not the other way around. But this is a tutorial about bar charts so we will have to work in reverse just for now.

Bar charts typically show elements with two attributes: a category, or key, and a value used to compare categories (check this post from the Data Visualisation Catalogue).

So let's imagine you are given this data:



const data1 = [{key: 'A', value: 30},{key: 'B', value: 20},
               {key: 'E', value: 50},{key: 'F', value: 80},
               {key: 'G', value: 30},{key: 'H', value: 70},
               {key: 'J', value: 60},{key: 'L', value: 40}];

Our goal is to map it onto a set of rectangles, spread across vertically, with their width scaling to the value attribute.

Setup

We will start by making a simple HTML page, where we load D3's library and add one title and a div:



<!DOCTYPE html>
<html>
<head>
    <title>D3 Bar Chart</title>
    <script type="text/javascript" src="https://d3js.org/d3.v6.min.js"></script>

    <style type="text/css">
    /* our custom styles */
    </style>
</head>
<body>
    <h1>D3 Bar Chart Example</h1>
    <div id="barContainer"></div>

    <script type="text/javascript">

        const data1 = [{key: 'A', value: 30},{key: 'B', value: 20},
                       {key: 'C', value: 60},{key: 'D', value: 40},
                       {key: 'E', value: 50},{key: 'F', value: 80},
                       {key: 'G', value: 30},{key: 'H', value: 70}];

        const width = 600, height = 400, margin = {t:10,b:30,l:30,r:10};
    </script>
</body>
</html>

Note: We are working with version 6 of D3.

We have also added our data and a set of values for our chart's dimensions. We will reuse these values multiple times, so we better save them in constants.

We are all set up here, and we know what we want to do. Let's create our bar chart with D3 now.

Selections

To understand what D3 is, it is always useful to remind ourselves of what it stands for:
Data Driven Documents.

The title says it all, it is a library that lets us manipulate the Document Object Model (DOM) of HTML pages using data. And the D3 way to do that is with Selections. To make it simple, selections are like wrappers for DOM elements, giving us an API to program these elements (there is more to it, but we will get there in a bit).

Say we want to add an SVG element to our div using D3. The way to do this is to select the parent (the div element) and append an svg element to it. And because the append method returns the newly created element selection, we can use it to set our chart's dimensions and save that selection into a variable.



const svg = d3.select('div#barContainer') // use the same css selectors to target your selections
    .append('svg')                        // our selection now maps to a newly created svg
    .attr('width', width)                 // the .attr() method lets you set the attribute value of your element
    .attr('height', height)
    .style('border', 'solid 1px #222');   // the .style() method lets you set the style of you element

The code above does just that, select our container adds an SVG to it, and saves the new selection in a variable svg. It does two additional things. With the .attr() method, we set the SVG's width and height using the values we defined previously and with the .style() method, we give a style to the SVG's border.

In fact, if we run our code in a browser, it displays the following:

And inspecting our DOM, here is what you should get:

I recommend using a local server to that, for example, python's or a node server

Logically, this new SVG is the root element of our bar chart and saving its selection in a variable means we can access it across our code easily. For example, let's define a chart area, where we will later draw our bars:



const chart = svg.append('g') // add a group to the svg
    .classed('chart', true)   // give our svg group a class name
    .attr('transform', `translate(${margin.l},${margin.t})`); // set the transform attribute to translate the chart area and set margins

Here we use a new method, .classed() as a way to set a class name for this SVG group. You use the same method to remove a class from an element, by putting false as your second parameter. You could technically use .attr('class', ...), but beware of this, since it will replace the whole value for the attribute class. The method .classed() remains the safest way to add/remove classes from elements.

We have also translated this group, using the margin values. Now, any element appended to this group will be drawn from a new reference point.

Quick Summary of selection methods
There are many methods you can use with selections, and I encourage you to take a look at the API for more details. But for now, here is a quick summary of what we have seen so far.

Method	Description
`d3.select(selector)`	Creates a selection with the first element matching the selector's criteria
`selection.select(selector)`	Creates a new selection with the first child element matching the selector's criteria
`selection.append(element)`	Adds a child element and returns it as a new selection
`selection.attr(name, value)`	Sets the attribute `name` for the elements mapped in the selection
`selection.style(name, value)`	Sets the style `name` for the elements mapped in the selection
`selection.classed(name, bool)`	Adds or remove a class `name` to the elements mapped in the selection

Bind, Enter, Exit, Update: the General Update Pattern

So far, what we have seen about selections is pretty basic, and you might be thinking that it is probably not worth using a whole library for that.

But we have only just scratch the surface. Remember that D3 stands for Data Driven Documents.

Binding data

Where D3's selections become truly useful is with data binding. In essence, this makes the selection a bridge between your data and the DOM.

We do so by calling the .data() selection method:


 javascript
let bars = chart.selectAll('rect.bar'); // from chart, select all rect element with class bar in 
bars = bars.data(data1, d=>d.key);      // bind data to the bars and save the selection

The .selectAll() method is similar to the .select() we have seen before. But instead of selecting the first DOM element matched by the selector, .selectAll() selects all the elements that matched. In this instance, it is all the SVG rectangles, with the class bar, children of our chart SVG group.

Then, the .data() method binds our data to the selection. The method's second parameter is what we call the key function, it is used to identify the data entry and create a unique link with the selection entry.

At this stage however, you might be wondering: where are all this SVG rectangles?. And you would be right, we have not created them yet. But we will use D3 to build exactly what we need.

Updating the DOM to match the dataset

When you bind data to a selection, the .data() method returns a new version of the selection, where its entries are separate in three categories: the new, the old, and the obsolete.

The new

The new are data entries the selection has no DOM element to match with (according to the key function). This is referred to as the enter selection and is accessed with the .enter() method.



// the new, create the element from scratch
bars.enter().append('rect')
    .classed('bar', true)
    .attr('x', 0)
    .attr('y', (d,i)=>i*35)
    .attr('height', 30)
    .attr('width', d=>d.value*6);

Because these rectangles are new, we have to create them (.append()) and set all of their attributes/style.

For some of these attributes, you will notice we did not use a fixed value as we did before. Because we bound our data to them, we can customise their look to fit with the data. That is where we can drive our document from the data and create awesome charts! Essentially you can now use functions to decide on the value of your attributes (or style). These functions have three parameters: the element's datum d, the element's index i, and the group the element is part of nodes.

Here we set the rectangles' positions to align them on the left (x = 0) and distribute them vertically using the elements' indices (y(d,i) = i*35). We also set the rectangles' sizes to a fixed height (height = 30) and a width function of the data value (width(d) = d.value*6).

And like that, we have bars, straight from the data we were "given" earlier.

The old

But let's finish touring our sub-selection. While we have not faced such case yet, it could be that the chart's elements you are currently drawing already exist, and used an older version of the data.

The second sub-selection, the old, are data-DOM links the selection used to have and which are still there (again, according to the key function), but with possibly new values. This is sometimes referred to as the update selection. You do not need a specific method to access it, just the selection variable.



// the old, just update the bar position and length
bars.attr('y', (d,i)=>i*35)
    .attr('width', d=>d.value*6);

Here, we just change what is dependent on the data: the vertical position of the bar and its length.

The obsolete

Finally, the obsolete are DOM elements the selection has no data to attach to anymore (you guessed it, according to the key function). This is referred to as the exit selection and is accessed with the .exit() method.



bars.exit().remove();

Here, we simply use the .remove() method to delete the rectangles which are not needed anymore.

The General Update Pattern

What we have just seen constitutes D3's General Update Pattern. It is a process typically followed when updating your charts:

Bind the data
Create the enter selection
Remove the exit selection
Update the selection's old entries

It is often a good idea to wrap it in a function, where you just need to give a dataset, and your script will draw the new or updated chart:



function updateData(dataset){
    // make our selection
    let bars = chart.selectAll('rect.bar');
    // bind data
    bars = bars.data(dataset, d=>d.key);
    // create the new    
    bars.enter().append('rect')
        .classed('bar new', true)
        .attr('x', 0)
        .attr('y', (d,i)=>i*35)
        .attr('height', 30)
        .attr('width', d=>d.value*6);
    // remove the obsolete
    bars.exit()
        .classed('obs', true)
        .remove();
    // update the old
    bars.classed('new', false)
        .attr('y', (d,i)=>i*35)
        .attr('width', d=>d.value*6);
}

Notice how I added a class new to the new elements, obs to the obsolete elements, and removed the new class for old ones. We can use it to see which rectangles are new when the chart updates:



svg > g.chart > rect.bar{
    fill: steelblue;
    stroke-width: 1px;
    stroke: #444;
}
svg > g.chart > rect.bar.new{
    fill: seagreen;
}
svg > g.chart > rect.bar.obs{
    fill: tomato;
}

Now, we are repeating ourselves with the enter and update selections, and from a programming point of view, this is not quite right. Since they will be the same for both selections, we should be setting the rectangles' position and width all at once, which is possible thanks to the .merge() method:



function updateData(dataset){
    // make our selection
    let bars = chart.selectAll('rect.bar');
    // bind data
    bars = bars.data(dataset, d=>d.key);
    // create the new and save it
    let barsEnter = bars.enter().append('rect')
        .classed('bar new', true)
        .attr('x', 0)
        .attr('height', 30);
    // remove the obsolete
    bars.exit()
        .classed('obs', true)
        .remove();
    // update old alone
    bars.classed('new', false);
    // merge old and new and update together
    bars.merge(barsEnter)
        .attr('y', (d,i)=>i*35)
        .attr('width', d=>d.value*6);
}

Setting attributes for the enter and update selection is actually the 5th optional step of the General Update Pattern. We can now use this update function to render and update our bar chart:



// assume a second set of data, updating data1
const data2 = [{key: 'A', value: 40},{key: 'C', value: 20},
               {key: 'D', value: 10},{key: 'F', value: 50},
               {key: 'G', value: 60},{key: 'H', value: 90},
               {key: 'I', value: 10},{key: 'J', value: 30},
               {key: 'K', value: 50},{key: 'L', value: 80}];

// calling our update function
setTimeout(()=>{updateData(data1)}, 1000);
setTimeout(()=>{updateData(data2)}, 5000);

It's alive!! However, the update is not really salient. But do not worry, we can use transitions for this.

Quick Summary of selection methods
Again, here is a recap of the methods we have seen in this section.

Method	Description
`d3.selectAll(selector)`	Creates a new selection with all the elements matching the selector's criteria
`selection.selectAll(selector)`	Creates a new selection with all the children elements matching the selector's criteria
`selection.data(dataset, keyFunction)`	Binds data to the selection
`selection.enter()`	Accesses the enter selection
`selection.exit()`	Accesses the exit selection
`selection.remove()`	Removes elements of the selection from the DOM
`selection.merge(selection2)`	Merges selections together

Animating your chart

You would have guessed it, D3 also provides us with means to add animations to our chart. They are particularly useful to transition between your charts' updates to check what is exactly happening. As such, D3 conveniently named this concept Transitions.

Now, back to our update function. We will need three different transitions in the following order:

removing the exit selection;
positioning the enter and update selections;
adjusting the length of the enter and update selections.



const tRemove = d3.transition();
const tPosition = d3.transition();
const tSize = d3.transition();

The API of transitions is quite similar to the selections one. One difference however, is that it provides methods for timing the animations. The most important ones being .duration() to set the animation span, and .delay() to postpone the animation start. Using these methods, we can customise our transitions:



const d = 500;                    // our base time in milliseconds
const tRemove = d3.transition()
    .duration(d);                 // 500ms duration for this animation
const tPosition = d3.transition()
    .duration(d)
    .delay(d);                    // 500ms wait time before this animation starts
const tSize = d3.transition()
    .duration(d)
    .delay(d*2);                  // 1000ms wait time before this animation starts

In the code above we are essentially creating 3 transitions that will animate our selections for 500ms, but should be launched one after the other. Note that the default value for durations is 250ms and 0ms for delays.

Next, we need to add these transition in our update pattern:



// ...
// remove the obsolete
bars.exit()
    .classed('obs', true)
    .transition(tRemove)          // remove transition
    .attr('width', 0)             // animate the length to bars to 0
    .remove();                    // delete the rectangles when finished
// ...
// merge old and new and update together
bars.merge(barsEnter)
    .transition(tPosition)        // position transtition
    .attr('y', (d,i)=>i*35)       // align all rectangles to their vertical position
    .transition(tSize)            // size transition
    .attr('width', d=>d.value*6); // set the rectanble sizes

As you can see we use the .transition() method to apply the predefined transitions to our selections. Note that once a transition applied, the chained methods (.attr() for example) are transition methods. As such, they may behave differently: .remove(), for example, only deletes elements when the transition ends.

For the same reason, transitions do not work with the .classed() method. And since we are using classes to style your chart (which I strongly recommend for global styles), it is best to add the appropriate CSS transitions:



svg > g.chart > rect.bar{
    fill: steelblue;
    stroke-width: 1px;
    stroke: #444;
    transition: fill 300ms;
}

And then call the .classed() method outside of transitions, using a timeout. Adding the following at the end of our function will return the bars to their default style once the update is complete:



setTimeout(()=>{bars.merge(barsEnter).classed('new', false)}, d*4)

And just like that, we have got a complete update transition, which makes it easier to follow what is happening.

Next, we will see how to better manage our chart area.

Quick Summary of transition methods
Here are the transition methods we have seen in this section, and what are probably the most common ones.

Method	Description
`d3.transition()`	Creates a new transition
`transition.duration(value)`	Sets the duration (in milliseconds) of the transition
`transition.delay(value)`	Sets the delay (in milliseconds) before the transition can start
`selection.transition(t)`	Applies transition `t` to your selection

Scaling our charts to the view

So far, we have been setting our bar height with an arbitrary value (30), from which we had to infer the space between the bars (35 = 30 bar height + 5 spacing). Similarly, we have arbitrarily decided that the bars' length will be a product of 6. All of that worked okay so far, but as we have seen, any data update could suddenly change the number of entries or the maximum value, which makes our arbitrary decisions impractical.

We could be all fancy and come up with ways to automatically compute, with every new dataset, what value we should use. Or we could use D3's Scales.

These scales have one simple task, mapping a domain to a range, but come with a lot of perks. Typically, you would use them to map from your data domain to your view range, which is what we will do now. They are many scales available, but we will look at two in particular: the continuous-linear scale, and the ordinal-band scale.

Getting the correct length of bars

The first scale we will look at is the continuous linear scale. This is the most forward scale, as the name suggests, it simply maps, linearly, a continuous domain to a continuous range.

It is the perfect tool to ensure that our bars are always contained within our chart view while keeping the ratio between bar lengths correct, after all, that is the point of bar charts.

To use it, we will simply create an instance of linear scale, and set the boundaries of its domain and range:



const xScale = d3.scaleLinear()
    .domain([0, d3.max(dataset, d=>d.value)])
    .range([0, width-margin.l-margin.r]);

With this scale, we keep the same origin 0, however, we match the maximum value from our dataset with the maximum length possible (the width minus horizontal margins). To get the maximum dataset value, I have used one D3's Array methods, .max(), by providing it with the appropriate accessor function.

We can now use this scale to scale our bars so that they always fit in length:



// ...
// create the new and save it
let barsEnter = bars.enter().append('rect')
    .classed('bar new', true)
    .attr('x', xScale(0))               // in case we change our origin later
    .attr('height', 30); 
// ...
// merge old and new and update together
bars.merge(barsEnter)
    .transition(tPosition)
    .attr('y', (d,i)=>i*35)
    .transition(tSize)
    .attr('width', d=>xScale(d.value)); // scaling the bar length
}

Spreading the bars evenly

The second scale we will look at is an ordinal band scale: our domain is categorical (no longer continuous) but our range remains continuous. Essentially it divides our range into even bands and map them to the categories in our domain.

It will allow us to always position the bars vertically and given the appropriate height, no matter the number of entries in the data.

Like linear scales, we just need to create an instance of it and define its range boundaries. Unlike linear scales, we have to provide the whole domain:



const yScale = d3.scaleBand()
    .domain(dataset.map(d=>d.key))
    .range([0, height-margin.t-margin.b])
    .padding(0.2);

This scale's range goes from 0 to the height of the chart minus vertical margins. The .padding() method lets us define the space (in proportion) between the bands.

Next, we can add it to our update process:



// ...
// create the new and save it
let barsEnter = bars.enter().append('rect')
    .classed('bar new', true)
    .attr('x', xScale(0));              // in case we change our origin later
// ...
// merge old and new and update together
bars.merge(barsEnter)
    .transition(tPosition)
    .attr('y', d=>yScale(d.key))        // scaling the bar position
    .attr('height', yScale.bandwidth()) // using the computed band height
    .transition(tSize)
    .attr('width', d=>xScale(d.value)); // scaling the bar length

Note that we have moved the height definition to the position animation and used the .bandwidth() method to get the computed height from the scale.

And that is all there is to it. Just a few lines of code and we have got bars that are perfectly fitted within their chart.

There are two important components missing to finish our bar chart: axes! But since we have used D3's scales, you will see that axes are going to be a piece of cake.

Quick Summary of scale methods
I have recap below the scale methods we saw in this section. But I encourage you to have a look at D3's API and see how much you can do with scales.

Method	Description
`d3.scaleLinear()`	Creates a new linear scale
`linearScale.domain([min, max])`	Sets the domain boundaries of a linear scale
`linearScale.range([min, max])`	Sets the range boundaries of a linear scale
`d3.scaleBand()`	Creates a new band scale
`bandScale.domain(array)`	Sets the domain of a band scale
`bandScale.range([min, max])`	Sets the range boundaries of a band scale
`bandScale.padding(value)`	Sets the padding between bands for a band scale
`bandScale.bandwidth()`	Returns the computed band size of a band scale
`d3.max(data,accessor)`	Returns the maximum value of a dataset according to the accessor function

Don't forget the axes!

Axes and labels are ones of the most crucial elements of data visualisations. Without them, your visualisation loses all its context, making it essentially useless. That is why D3 has an integrated an Axis module which works seamlessly with scales.

To include these, we first need to define a space for them, adding two groups to our svg:



const xAxis = svg.append('g')
    .classed('axis', true)
    .attr('transform', `translate(${margin.l},${height-margin.b})`);
const yAxis = svg.append('g')
    .classed('axis', true)
    .attr('transform', `translate(${margin.l},${margin.t})`);

Next, in our update process, we need to change these group selections to render an updated axis:



d3.axisBottom(xScale)(xAxis.transition(tSize));
d3.axisLeft(yScale)(yAxis.transition(tPosition));

And that is it. D3 axes were made to render D3 scales, and that is what the code above does. To break it down, d3.axisBottom(xScale) creates a new axis, based on xScale, to be rendered with its ticks downwards. We then directly call this axis on the xAxis selection defined before. And the same goes with d3.axisLeft(yScale) (the ticks are directed towards the left). Note that we also applied our transitions to sync the axis change with the bar change.

Quick Summary of axes methods
Like scales, there is a lot more in D3's API, but here are the methods we have used in this section.

Method	Description
`d3.axisBottom(scale)`	Creates a new bottom axis based on `scale`
`d3.axisLeft(scale)`	Creates a new left axis based on `scale`
`axis(selection)`	Renders the axis within the provided selection

Bonus: Adding interactivity

Interactivity is one of the greatest advantages of browser-based data visualisations. Mousing over the element of one chart can highlight the corresponding element(s) in a second coordinated chart or display a tooltip with more information for context, you can also use clicks on one view to filter data in another view, etc.

It is no surprise then, that D3 added event listeners to its selections. Let's imagine we want to apply a highlight class to our bars when you mouse over it.



svg > g.chart > rect.bar.highlight{
    fill: gold;
    stroke-width: 4px;
}

We can do so with the .on() selection method, which takes two parameters: the event name to listen for, and the callback function to apply. We just need to apply these listeners to our enter selection (they will remain after an update).



//...
let barsEnter = bars.enter().append('rect')
    .classed('bar new', true)
    .attr('x', xScale(0))
    .on('mouseover', function(e,d){
        d3.select(this).classed('highlight', true);
    })
    .on('mouseout', function(e,d){
        d3.select(this).classed('highlight', false);
    });
//...

There are two things to note here. First, we have not used an arrow function like other callbacks, that is because we want to have access to the caller's scope (the element moused over) and use its this to select only the element and apply our class change. Second, the callback does not have the typical parameters (data and index), instead, it uses event and data.

We have added listeners to two events: mousover for the cursor enters the element and mouseout for when it exits.

Conclusion

That is it for this tutorial. From just the simple goal of creating a bar chart, we have explored many concepts core to using D3:

Selections
the General Update Pattern
Transitions
Scales and Axes
Events

There is of course a lot more to D3 than that: data manipulation, layout generators (pies, Voronoi, chords, etc.), geographical maps, colour scales, time and number formatting, complex interactions (brushing, zooming, dragging, forces, etc.), complex transitions. But, hopefully, this tutorial has given you the desire to go further.

Here is the complete code I have used.



<!DOCTYPE html>
<html>
<head>
    <title>D3 Bar Chart</title>
    <script type="text/javascript" src="https://d3js.org/d3.v6.min.js"></script>
    <style type="text/css">
        svg{
            border: solid 1px #222;
        }
        svg > g.chart > rect.bar{
            fill: steelblue;
            stroke-width: 1px;
            stroke: #444;
            transition: fill 300ms;
        }
        svg > g.chart > rect.bar.new{
            fill: seagreen;
        }
        svg > g.chart > rect.bar.obs{
            fill: tomato;
        }
        svg > g.chart > rect.bar.highlight{
            fill: gold;
            stroke-width: 4px;
        }
    </style>
</head>
<body>
    <h1>D3 Bar Chart Example</h1>
    <div id="barContainer"></div>
    <script type="text/javascript">
        // datasets
        let data1 = [{key: 'A', value: 30},{key: 'B', value: 20},
                     {key: 'E', value: 50},{key: 'F', value: 80},
                     {key: 'G', value: 30},{key: 'H', value: 70},
                     {key: 'J', value: 60},{key: 'L', value: 40}];
        let data2 = [{key: 'A', value: 40},{key: 'C', value: 20},
                     {key: 'D', value: 10},{key: 'F', value: 50},
                     {key: 'G', value: 60},{key: 'H', value: 90},
                     {key: 'I', value: 10},{key: 'J', value: 30},
                     {key: 'K', value: 50},{key: 'L', value: 80}];
        // chart dimensions 
        let width = 600, height = 400, margin = {t:10,b:30,l:30,r:10};
        // svg element
        let svg = d3.select('div#barContainer')
            .append('svg')
            .attr('width', width)
            .attr('height', height)
            .style('border', 'solid 1px #222');
        // chart area
        let chart = svg.append('g')
            .classed('chart', true)
            .attr('transform', `translate(${margin.l},${margin.t})`);
        // axes areas
        let xAxis = svg.append('g')
            .classed('axis', true)
            .attr('transform', `translate(${margin.l},${height-margin.b})`);
        let yAxis = svg.append('g')
            .classed('axis', true)
            .attr('transform', `translate(${margin.l},${margin.t})`);
        // update function
        function updateData(dataset){
            // transitions
            let d = 500;
            let tRemove = d3.transition()
                .duration(d);
            let tPosition = d3.transition()
                .duration(d)
                .delay(d);
            let tSize = d3.transition()
                .duration(d)
                .delay(d*2);
            // scales
            let xScale = d3.scaleLinear()
                .domain([0, d3.max(dataset, d=>d.value)])
                .range([0, width-margin.l-margin.r]);
            let yScale = d3.scaleBand()
                .domain(dataset.map(d=>d.key))
                .range([0, height-margin.t-margin.b])
                .padding(0.2);
            // axes
            d3.axisBottom(xScale)(xAxis.transition(tSize));
            d3.axisLeft(yScale)(yAxis.transition(tPosition));
            // update pattern
            // initial selection
            bars = chart.selectAll('rect.bar');
            // data binding
            bars = bars.data(dataset, d=>d.key);
            // exit selection
            bars.exit()
                .classed('obs', true)
                .transition(tRemove)
                .attr('width', 0)
                .remove();
            // enter selection
            let barsEnter = bars.enter().append('rect')
                .classed('bar new', true)
                .attr('x', xScale(0))
                .on('mouseover', function(e,d){
                    d3.select(this).classed('highlight', true);
                })
                .on('mouseout', function(e,d){
                    d3.select(this).classed('highlight', false);
                });
            // update selection
            bars.classed('new', false);
            // enter + update selection
            bars.merge(barsEnter)
                .transition(tPosition)
                .attr('y', d=>yScale(d.key))
                .attr('height', yScale.bandwidth())
                .transition(tSize)
                .attr('width', d=>xScale(d.value));
            // class reset
            setTimeout(()=>{bars.merge(barsEnter).classed('new', false)}, d*4)
        }

        setTimeout(()=>{updateData(data1)}, 2000)
        setTimeout(()=>{updateData(data2)}, 6000)
    </script>
</body>
</html>