mip-billboardjs

MIP React component for the billboard.js charting library

This is based on react-c3js, with modifications for billboard.js and enhancements for rendering

Table of contents

• Installation
• Usage
• Props
  • className
  • isPure
  • style
  • unloadBeforeLoad
• Managing the internal chart
  • loadData
  • redraw
  • unloadData
  • Chart instance
• Development

Installation

$ npm install react-billboardjs --save

Usage

import React, {Component} from 'react';

// component and styles
import BillboardChart from 'react-billboardjs';
import 'react-billboardjs/lib/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 provided CSS file to ensure that all appropriate styles for billboard are included as well (this is the same CSS file provided by billboard.js, so if you are already including that then no need to include this as well). 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.

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:

• className {string}
• isPure {boolean}
• style {Object}
• unloadBeforeLoad {boolean}

className

An additional className that is passed to the element that the chart is rendered into.

<BillboardChart
  className="fancy"
  ...
/>

isPure

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

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 to relative)

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

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}
      />
    );
  }
}

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']
});

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');

Development

Standard stuff, clone the repo and npm install dependencies. The npm scripts available:

• build => run webpack to build development dist file with NODE_ENV=development
• build:minifed => run webpack to build production dist file with NODE_ENV=production
• copy:css => copy the billboard.css file from billboard.js package to src
• dev => run webpack dev server to run example app (playground!)
• lint => run ESLint against all files in the src folder
• lint:fix => run lint with --fix applied
• prepublish => runs compile-for-publish
• prepublish:compile => run lint, test, transpile:es, transpile:lib, build, and build:minified scripts
• test => run AVA test functions with NODE_ENV=test
• test:coverage => run test but with nyc for coverage checker
• test:watch => run test, but with persistent watcher
• transpile:lib => run babel against all files in src to create files in lib
• transpile:es => run babel against all files in src to create files in es, preserving ES2015 modules (for pkg.module)