react-animated-dataset

AnimatedDataset

AnimatedDataset uses the power of d3 data join to build solid animations.

Without animation you used to do something like:

const dataset = [{ x: 10, y: 10 }, ... ]

return (
  <svg>
    {dataset.map(p => {
      const cx = p.x
      const cy = p.y

      return <circle key={p.y} cx={cx} cy={cy} r={4} />
    })}
  </svg>
)

This can be easly translated into this:

import { AnimatedDataset } from 'react-animated-dataset'

// ...

const dataset = [{ x: 10, y: 10 }, ... ]

return (
  <svg>
    <AnimatedDataset
      dataset={dataset}
      tag="circle"
      attrs={{
        cx: p => p.x,
        cy: p => p.y,
        r: 4,
      }}
      keyFn={p => p.y}
    />
  </svg>
)

And it comes with animations too!

The component is designed to transform and animate dataset of any shape into any svg element. Animation are automatically triggered by passing a different dataset, a different attrs object or both. With keyFn the component is able to understand which datum has to be updated, added or removed.

Install

yarn add react-animated-dataset

Note that, for this package to work, react and d3 are also needed. If you haven't already installed them, install them with

yarn add react react-dom d3

More specifically, this package uses only d3-selection and d3-transition from the whole d3 ecosystem.

Usage

The component creates a svg element (specified in tag) for each value of dataset. tag attributes are inferred from attrs object where keys are the attribute name and values can be the actual attribute value or a function that returns the value from a single dataset value (see example above).

When dataset values or attrs values change, AnimatedDataset triggers an animation to rearrange the data. The animation is indipendent for each dataset value and there can be 3 animation states:

• enter: datum is added
• update: datum value has changed
• exit: datum is removed

To tell one state from an other, AnimatedDataset uses keyFn: it is a function that should return an unique value for each dataset entry. These animation states can be customized with the init prop. init has same shape as attrs and its values are used to specify the attributes values for every datum that is entering or exiting the dataset.

const lettersDataset = randomLetters()

<AnimatedDataset
  dataset={lettersDataset}
  tag="text"
  init={{
    opacity: 0,
    y: l => (lettersDataset.includes(l) ? 0 : 80),
  }}
  attrs={{
    opacity: 1,
    x: (_, index) => index * 40,
    y: 40,
    text: letter => letter,
    fill: 'black',
    fontSize: 50,
  }}
  keyFn={letter => letter}
/>

In the example above, opacity: 0 and y function in init are used for every entering and exiting letters.

Use case: Linechart with d3

In this next example we will draw a simple line chart, with circles for each data point and a grid with only horizontal lines. Starting from a dataset of type Array<{x: number, y: number}>, we can use d3.scaleLinear and d3.line as a utility to map data points to coordinates and to create the shape of the path.

// Initial setup

const xScale = d3
  .scaleLinear()
  .domain(xDomain)
  .range([0, WIDTH])

const yScale = d3
  .scaleLinear()
  .domain(yDomain)
  .range([HEIGHT, 0])

const lineGenerator = d3
  .line()
  .x(p => xScale(p.x))
  .y(p => yScale(p.y))


// To draw the horizontal grid we use yScale.ticks as dataset.
// To highlight the line relative to value 0 we can check tick
// value in 'stroke-width' and 'opacity'.

<AnimatedDataset
  dataset={yScale.ticks(10)}
  tag="line"
  init={{ opacity: 0 }}
  attrs={{
    x1: xScale.range()[0],
    x2: xScale.range()[1],
    y1: tick => yScale(tick),
    y2: tick => yScale(tick),
    stroke: 'lightgrey',
    strokeWidth: tick => (tick === 0 ? 2 : 1),
    opacity: tick => (tick === 0 ? 1 : 0.5),
  }}
  keyFn={tick => tick}
/>


// Next we draw the linechart using a single path. To get a single
// path out of AnimatadDataset we need to wrap our dataset in
// an array and set d attribute to the lineGenerator.

<AnimatedDataset
  dataset={[dataset]}
  tag="path"
  attrs={{
    d: lineGenerator,
    fill: "none",
    stroke: "darkgrey"
  }}
  keyFn={(_, i) => i}
/>


// Finally we add circles for every data point. As for
// grid, we use xScale and yScale to calculate the actual
// position. We can also change fill according to y value.

<AnimatedDataset
  dataset={dataset}
  tag="circle"
  attrs={{
    opacity: 1,
    cx: p => xScale(p.x),
    cy: p => yScale(p.y),
    fill: p => (p.y >= 0 ? "green" : "red"),
    r: 3
  }}
  keyFn={(_, i) => i}
/>

Whenever dataset, xRange or yRange change, we have smooth animations.

As it can be seen in the result, AnimatedDataset supports path morphing and color interpolation. Also, thanks to the combination of grid keyFn and init props, the component knows which line to move and which to fade in/out.

Props

# dataset

• Required
• Type: Array<any>

# attrs

• Required
• Type: {[key: string]: number | string | ((datum: any, index: number, nodes: Array<SVGElement>) => number | string)}

attrs keys should be an attribute name for given tag. They can be kebab-case (stroke-width) or camel case (strokeWidth).

attrs values should be the actual value or a function to calculate the value. Function accepts as parameter a single datum, its index and the array of rendered svg elements (the d3 selection).

<AnimatedDataset
  attrs={{
    stroke: 'black',
    strokeWidth: datum => datum.someValue * 10,
    'font-size': 15,
    fill: (datum, index, nodes) => ...
  }}
/>

# events

• Type: { [key: string]: (mouseEvent: MouseEvent, datum: any) => void }

Event listeners keys can be written in kebab-case (on-mouseover) or camel case (onMouseOver).

<AnimatedDataset
  events={{
    'on-click': (mouseEvent, datum) => console.log(datum),
    onMouseOver: (mouseEvent, datum) => ...
  }}
/>

# tag

• Type: string
• Default: "rect"

Any valid svg tag name.

# keyFn

• Type: (datum: any, index: number, nodes: Array<SVGElement>) => any
• Default: datum => datum.key

A function that identifies dataset values. It should return an unique value for each datum.

# init

• Type: {[key: string]: number | string | ((datum: any, index: number, nodes: Array<SVGElement>) => number | string)}

Same as attrs. init values are used to animate entering and exiting values. It doesn't support event listeners.

# disableAnimation

• Type: boolean
• Default: false

If true animation is disabled and the data is updated immediately.

# duration

• Type: number | (datum: any, index: number , nodes: Array<SVGElement>) => number
• Default: 1000

The animation duration in milliseconds.

# delay

• Type: number | (datum: any, index: number , nodes: Array<SVGElement>) => number
• Default: 0

The animation delay in milliseconds.

# durationByAttr

• Type: {[key: string]: number | ((datum: any, index: number, nodes: Array<SVGElement>) => number)}

If defined, allows to specify a different animation duration for each attribute

# delayByAttr

• Type: {[key: string]: number | ((datum: any, index: number, nodes: Array<SVGElement>) => number)}

If defined, allows to specify a different animation delay for each attribute

# easingByAttr

• Type: {[key: string]: number | ((datum: any, index: number, nodes: Array<SVGElement>) => number)}

If defined, allows to specify a different animation easing for each attribute

Contributing

If you make some edits and wish to test them locally you can run yarn test.

To publish run yarn release.