D3 Render

Declarative and reusable D3. Replace

select

append

data

join

enter

exit

transition

Warning, highly experimental at this stage. API will change.

Articles

• Introducing D3 Render: Truly Declarative and Reusable D3.
• COVID-19 Bubble Chart Tutorial

What's the difference?

Instead of imperative code:

import * as d3 from 'd3';

// HTML file has an  element
const svg = d3.select('svg');
svg
  .append('rect')
  .attr('fill', 'pink')
  .attr('x', 0)
  .attr('width', 100)
  .attr('height', 100);

Write declarative style like this:

import render from 'd3-render';

const data = [{ append: 'rect', fill: 'pink', x: 0, width: 100, height: 100 }];
// HTML file has an  element
render('svg', data);

Getting Started

$ npm install d3-render d3-selection d3-transition

D3 Render needs

d3-selection

d3-transition

Documentation

Render

One function to rule them all. To use, add this to your JavaScript or TypeScript file:

import render from 'd3-render';

render(selector, data);
// Render also returns the full D3 selection for advanced use cases
const selection = render(selector, data);

render

selector

A D3 selector string, HTML node or D3 selection to specify the root element where

render

// Selects first  element
render('svg', data);

// Select by id
render('#root', data);
// Select first element with this class name
render('.data-viz', data);
// Select by DOM node
const node = document.querySelector('.data-viz');
render(node, data);
// Select by D3 selection
const selection = d3.select('svg');
render(selection, data);
// Or called by D3
d3.select('svg').call(render, data);

data

An array of objects describing elements that D3 will append or update. For example:

const data = [
  {
    append: 'circle',
    r: 50,
    cx: 50,
    cy: 50,
    fill: 'purple',
  },
  {
    append: 'rect',
    width: 100,
    height: 100,
    x: 100,
    y: 0,
    fill: 'blue',
  },
];

render('#root', data);

render

#root

The D3 selection API is called for you, hiding imperative code like

selection.append()

selection.attr()

Nesting

data

children

Say we want to wrap the circle and rectangle above within a group element:

const data = [
  {
    append: 'g',
    children: [
      {
        append: 'circle',
        ...
      },
      {
        append: 'rect',
        ...
      },
    ],
  },
];

render

The

children

Element Keys

Below is a list of important element keys:

| Element Key | Description | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

append

rect

circle

path

g

div

img

selection.append()

key

class

id

x

y

width

height

cx

cy

r

d

fillOpacity

selection.attr()

fillOpacity

fill-opacity

{ enter, exit }

duration

0

100px

height: { enter: 100, exit: 0 }

text

text

{ append: text, text: 'Greetings'}

html

element.innerHTML

{ html: 'Important normal'}

children

style

style: { fillOpacity: 0.5 }

selection.style()

duration

selection.transition().duration(myDuration)

delay

ease

{ append: 'rect', ease: d3.easeQuadInOut }

children

onClick

onMouseOver

onMouseOut

on*

{ onClick: (event, data, index) => {} }

call

{ call: xAxis }

selection.call()

* Required

Updating Elements

To make updates to rendered elements, just run

render

data

// Initial data
const data = [
  { append: 'ellipse', fill: 'red', rx: 100, ry: 50, duration: 1000 },
];

// Initial render on 
render('#root', data);
// After two seconds, change ellipse to blue
setTimeout(() => {
  // Set some updated data
  const newData = [
    { append: 'ellipse', fill: 'blue', rx: 100, ry: 50, duration: 1000 },
  ];
  // Call render again
  render('#root', newData);
}, 2000);

Behind the scenes,

render

data

newData

const data = [{ fill: 'red' }];
const svg = d3.select('#root');

function update(data) {
  svg
    .selectAll('ellipse')
    .data(data)
    .join(
      enter =>
        enter
          .append('ellipse')
          .attr('rx', 100)
          .attr('ry', 50)
          .attr('fill', d => d.fill),
      update =>
        update.call(update =>
          update
            .transition()
            .duration(1000)
            .attr('fill', d => d.fill)
        )
    );
}
update(data);
// After two seconds, turn ellipse blue
setTimeout(() => {
  update([{ fill: 'blue' }]);
}, 2000);

We are using d3-selection 1.4's

join

join

render

Enter/Exit Elements

The

render

data

Here is a simple example below:

// Build an svg with nothing in it
render('#root', []);
// Renders: 

// Two seconds later, re-render with a new rect element
setTimeout(() => {
  render('#root', [{ append: 'rect', width: 100, height: 100, fill: 'pink' }]);
  // Renders: Howdy there!
  // Two seconds after text element appears, remove it
  setTimeout(() => {
    render('#root', []);
    // Renders: 
  }, 2000);
}, 2000);

D3's data binding works much the same way. In fact, we are also data binding in the background, but we've also added some boilerplate to make enter/exit transitions easy to do.

Enter/Exit Transition

Let's enable enter/exit transitions by adding two lines of code:

render('#root', []);

setTimeout(() => {
  render('#root', [
    {
      append: 'rect',
      // Was width: 0
      width: { enter: 100, exit: 0 },
      height: 100,
      fill: 'pink',
      // Length of transition in milliseconds
      duration: 1000,
    },
  ]);
  setTimeout(() => {
    render('#root', []);
  }, 2000);
}, 2000);

The

width

enter

exit

rect

0

duration

100px

When the

rect

data

100px

0

rect

The

{ enter, exit }

Event Handlers

An event handler for the element can be defined along with the rest of the attributes.

render('#root', [
  {
    append: 'circle',
    r: 50,
    cx: 50,
    cy: 50,
    // Circle can call function when it is clicked or tapped
    onClick: (event, datum) => {},
    // Or when the mouse is over
    onMouseOver: (event, datum) => {},
  },
]);

Any

on*

onDrag

onScroll

onWheel

selection.on()

Inline Styles

An element can be styled inline with the

style

style

render('#root', [
  {
    append: 'rect',
    width: 50,
    height: 50,
    style: {
      fillOpacity: 0.5,
    },
  },
]);

React Example

D3 Render is actually inspired by React's declarative mental model, so it is no suprise that integration between the two is quite simple:

// App.js

import React from 'react';
import render from 'd3-render';
const App = () => {
  const svg = React.useRef();
  const [data, setData] = React.useState([
    {
      append: 'rect',
      width: 100,
      height: 100,
      fill: 'green',
      duration: 1000,
      // Add some interactivity to the  element
      onClick: () => {
        setData([{ ...data[0], fill: 'yellow' }]);
      },
    },
  ]);
  React.useEffect(() => {
    if (svg && svg.current) {
      // Pass svg node to D3 render, along with data.
      // render runs whenever data changes
      render(svg.current, data);
    }
  }, [data]);
  return ;
};

Todos

Documentation

• [ ] Add animated gifs
• [x] Interactivity example
• [x]

  update

  example
• [x]

  html

  example
• [x] Nesting with

  children

  example
• [ ] Component example
• [ ] Data

  key

  example
• [ ] Selection return example
• [x] Incremental adoption example with

  d3.select('svg').call(render, data)

• [ ] Element node access in function value eg.

  delay: function(d, i) { this.getTotalLength() }

API

• [x] Reduce bundle size by only requiring

  d3-selection

  and

  d3-transition

• [x] Merge

  render

  and

  renderSelection

  into one function
• [x] Add

  style

  attribute key
• [x] Use camelCased element keys and then convert to snake-case for selection.attr()
• [x] Add more on* events
• [x] Try

  selection.prototype = render

  for

  d3.render()

  to work
• [x] Enable HTML element appends
• [x] Add tests
• [x] Integrate

  selection.html()

• [x] Add

  update

  to

  { enter, exit }

  transition object
• [x] Consider

  start

  in transition object
• [x] Consider

  { enter, exit }

  for

  ease

  ,

  delay

  and

  duration

• [ ] Design declarative API for complex timeline based animations
• [ ] Remove transition if no duration

Local Development

This project was bootstrapped with TSDX.

Below is a list of commands you will probably find useful.

npm start

or

yarn start

Runs the project in development/watch mode. Your project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab.

Your library will be rebuilt if you make edits.

npm run build

or

yarn build

Bundles the package to the

dist

npm test

or

yarn test

Runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit.