React component for data animation
npm install react-animated-datasetAnimatedDataset uses the power of d3 data join to build solid animations.
Without animation you used to do something like:
``jsx
const dataset = [{ x: 10, y: 10 }, ... ]
return (
return
})}
)
`
This can be easly translated into this:
`jsx
import { AnimatedDataset } from 'react-animated-dataset'
// ...
const dataset = [{ x: 10, y: 10 }, ... ]
return (
)
`
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.
`bash`
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
`bash`
yarn add react react-dom d3
More specifically, this package uses only d3-selection and d3-transition from the whole d3 ecosystem.
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 addedupdate
- : datum value has changedexit
- : 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.
`jsx
const lettersDataset = randomLetters()
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.
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.
`jsx
// 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'.
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.
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.
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.
- Required
- Type: Array
- Required
- Type: {[key: string]: number | string | ((datum: any, index: number, nodes: Array
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).
`jsx`
stroke: 'black',
strokeWidth: datum => datum.someValue * 10,
'font-size': 15,
fill: (datum, index, nodes) => ...
}}
/>
- Type: { [key: string]: (mouseEvent: MouseEvent, datum: any) => void }
Event listeners keys can be written in kebab-case (on-mouseover) or camel case (onMouseOver).
`jsx`
'on-click': (mouseEvent, datum) => console.log(datum),
onMouseOver: (mouseEvent, datum) => ...
}}
/>
- Type: string"rect"
- Default:
Any valid svg tag name.
- Type: (datum: any, index: number, nodes: Arraydatum => datum.key
- Default:
A function that identifies dataset values. It should return an unique value for each datum.
- Type: {[key: string]: number | string | ((datum: any, index: number, nodes: Array
Same as attrs. init values are used to animate entering and exiting values. It doesn't support event listeners.
- Type: booleanfalse
- Default:
If true animation is disabled and the data is updated immediately.
- Type: number | (datum: any, index: number , nodes: Array1000
- Default:
The animation duration in milliseconds.
- Type: number | (datum: any, index: number , nodes: Array0
- Default:
The animation delay in milliseconds.
- Type: {[key: string]: number | ((datum: any, index: number, nodes: Array
If defined, allows to specify a different animation duration for each attribute
- Type: {[key: string]: number | ((datum: any, index: number, nodes: Array
If defined, allows to specify a different animation delay for each attribute
- Type: {[key: string]: number | ((datum: any, index: number, nodes: Array
If defined, allows to specify a different animation easing for each attribute
If you make some edits and wish to test them locally you can run yarn test.
To publish run yarn release`.