planttheideareact-billboardjs
React component for the billboard.js charting library
This is based on react-c3js, with modifications for billboard.js and enhancements for rendering
Installation
$ npm install react-billboardjs --saveUsage
import React, { Component } from 'react';
// component and styles
import BillboardChart from 'react-billboardjs';
import 'billboard.js/dist/billboard.css';
const CHART_DATA = {
columns: [
['data1', 30, 20, 50, 40, 60, 50],
['data2', 200, 130, 90, 240, 130, 220],
['data3', 300, 200, 160, 400, 250, 250],
],
type: 'line',
};
class LineChart extends Component {
render() {
return <BillboardChart data={CHART_DATA} />;
}
}Make sure to include the CSS file provided with billboard.js to include appropriate styles for billboard. The example above is if you are using webpack or a similar bundler, but the styles are global so bring them in however is best for your application.
Production usage
The PropTypes of this package are quite large, as they try to be comprehensive coverage for the configuration of billboard.js. If you do not want to incur this cost in production, then you can point your package to the min build which excludes them. Example in a webpack config:
module.exports = {
// ...config
resolve: {
alias: {
'react-billboardjs': path.resolve(
__dirname, // assuming config is top of the directory
'node_modules/react-billboardjs/dist/react-billboardjs.min.js',
),
},
},
};This creates a much smaller bundle, as the minified + gzipped size of react-billboardjs drops from 4.51KiB to 1.39KiB.
Required props
data
The data passed to the configuration object for the billboard.js chart. It is a pass-through to the data property on bb.generate().
Optional props
All top-level properties available on the billboard.js options are passable as props, so for more detail about each of those props please check their documentation site. There are also a few additional props specific to the component, which are detailed below.
className
string
An additional className that is passed to the element that the chart is rendered into.
<BillboardChart
className="fancy"
...
/>domProps
Object
Any additional props that you want passed to the element that the chart is rendered into.
<BillboardChart
domProps={{'data-type': 'chart'}}
...
/>isPure
boolean
Are the prop values passed based on a shallow-equal comparison of props and context. This can prevent unnecessary re-renders when set to true, but expects any prop changes to be new objects (meaning arrays / objects that are mutated will not trigger a render).
<BillboardChart
isPure
...
/>style
Object
An additional style object that is passed to the element that the chart is rendered into.
const STYLE = {
display: 'inline-block'
};
<BillboardChart
style={STYLE}
...
/>One caveat to keep in mind is that there are two styles that will always be applied from billboard.js even if the properties are included in the style object:
max-height(dynamically calculated based on the height of the container)position(set torelative)
If you want either of these to apply to the chart, the easiest way to accomplish this is to have a standard <div> that wraps the chart that you can apply these styles to.
unloadBeforeLoad
boolean
Should the current data be unloaded before the new data will be loaded.
<BillboardChart
unloadBeforeLoad
...
/>Managing the internal chart
If you capture the ref of the chart, you will gain access to the instance, which allows you to use both the component methods and the billboard.js native chart.
class Chart extends PureComponent {
getRef = (ChartInstance) => {
this.chartInstance = ChartInstance;
};
render() {
return (
<BillboardChart
data={...}
ref={this.getRef}
/>
);
}
}destroyChart
Destroys the chart and sets the internal chart to null (equivalent to the native Chart.destroy method).
this.chartInstance.destroyChart();exportChart
Exports the chart using the functionality introduced in 1.2.0 of billboard.js (equivalent to the native Chart.export method).
this.chartInstance.exportChart({ mimeType: 'image/png' }, (dataUrl) => {
const link = document.createElement('a');
link.download = 'chart.png';
link.href = dataUrl;
link.textContent = 'Download chart as PNG';
document.body.appendChild(link);
});loadData
Loads new data into the chart (equivalent to the native Chart.load method).
this.chartInstance.loadData({
columns: [['data1', 100, 50]],
});redraw
Forces a redraw of the chart.
this.chartInstance.redraw();unloadData
Loads new data into the chart (equivalent to the native Chart.unload method).
this.chartInstance.unloadData({
ids: ['data1'],
done() {
console.log('unloaded data1!');
},
});updateConfig
Updates the configuration value of a specific item (equivalent to the native Chart.config method).
this.chartInstance.updateConfig('line.max', 100);Chart instance
If you want to access the native billboard.js chart instance, it is available on the chart property of the ref.
this.chartInstance.chart.defocus('data1');Managing all charts
The BillboardChart component itself has some static methods that are used to get information about the global bb object.
getInstances
Get all chart objects for all charts rendered. This aligns with the bb.instance property.
console.log(BillboardChart.getInstances()); // [Chart, Chart]Development
Standard stuff, clone the repo and npm install dependencies. The npm scripts available:
build=> run rollup to build distributed filesclean=> remove the distributed files indistdev=> run webpack dev server to run example app (playground!)lint=> run ESLint against all files in thesrcfolderlint:fix=> runlintwith--fixappliedprepublishOnly=> runslint,test, andbuildscriptsrelease=> release a new version of the package (requiresrelease-itinstalled globally)release:beta=> release a new beta version of the package (requiresrelease-itinstalled globally)test=> run AVA test functions withNODE_ENV=testtest:coverage=> runtestbut withnycfor coverage checkertest:watch=> runtest, but with persistent watcher