### Install billboard.js and React Component
Source: https://github.com/naver/billboard.js/blob/master/packages/react/README.md
Install billboard.js and the @billboard.js/react component using pnpm. This is a prerequisite for using the component.
```bash
# Install billboard.js together if you don't have it already
$ pnpm add billboard.js @billboard.js/react
```
--------------------------------
### Install Release Candidate Version
Source: https://github.com/naver/billboard.js/blob/master/README.md
To install the 'release candidate' build, which precedes the latest official release, use the pnpm add command with the '@next' tag.
```bash
$ pnpm add billboard.js@next
```
--------------------------------
### UMD/CDN Usage Example
Source: https://github.com/naver/billboard.js/blob/master/MODULE_IMPORTS.md
When using the UMD build via CDN, all resolvers are auto-invoked at load time. This means methods like chart.xgrids() work out of the box without extra setup.
```html
```
--------------------------------
### Install billboard.js Locally
Source: https://github.com/naver/billboard.js/wiki/How-to-load-as-ESM-directly-from-the-browser?
Install billboard.js using npm. This command installs the package and its dependencies into your local node_modules directory.
```sh
npm i billboard.js
```
--------------------------------
### Install Puppeteer
Source: https://github.com/naver/billboard.js/wiki/How-to-generate-chart-image-in-Node.js-environment?
Install the Puppeteer package as a development dependency.
```sh
npm i puppeteer --save-dev
```
--------------------------------
### Plugin Development Commands
Source: https://github.com/naver/billboard.js/wiki/Plugin-Interface
Lists the npm commands for facilitating plugin development: `npm run start:plugin` to start the development server and `npm run build:plugin` to build the plugin.
```bash
# Running below command will facilitate on plugin development
# start dev-server
$ npm run start:plugin
# build plugin
$ npm run build:plugin
```
--------------------------------
### Install Nightly Version via pnpm
Source: https://github.com/naver/billboard.js/blob/master/README.md
Alternatively, you can install the nightly version directly from the GitHub repository using the pnpm add command with the specified branch.
```bash
$ pnpm add git+https://github.com/naver/billboard.js.git#nightly
```
--------------------------------
### Install Dependencies with pnpm
Source: https://github.com/naver/billboard.js/blob/master/DEVELOPMENT.md
Install all necessary dependency modules for billboard.js development using pnpm. This step is crucial after cloning the repository.
```bash
# Install the dependency modules.
$ pnpm install
```
--------------------------------
### Complete HTML Structure for ESM Billboard.js
Source: https://github.com/naver/billboard.js/wiki/How-to-load-as-ESM-directly-from-the-browser?
This is a full HTML example demonstrating how to set up an import map for billboard.js and its dependencies, and then generate a chart using ESM.
```html
billboard.js
```
--------------------------------
### Install Billboard.js with pnpm
Source: https://github.com/naver/billboard.js/blob/master/README.md
The standard way to install the latest stable version of Billboard.js using pnpm is by running the 'pnpm add billboard.js' command.
```bash
$ pnpm add billboard.js
```
--------------------------------
### Build billboard.js
Source: https://github.com/naver/billboard.js/blob/master/DEVELOPMENT.md
Utilize package scripts to build billboard.js for development or production. This includes starting a development server, generating a production build, and creating JSDoc documentation.
```bash
# Run webpack-dev-server for development
$ pnpm start
# Build
$ pnpm run build
# Generate jsdoc
$ pnpm run jsdoc
```
--------------------------------
### Usage Example 2: Bar and Area Chart
Source: https://github.com/naver/billboard.js/wiki/How-to-generate-chart-image-in-Node.js-environment?
This example demonstrates generating a bar and area chart and saving it as 'chart02.png'. Ensure 'transition.duration' is set to 0 to prevent rendering issues.
```js
await screenshot({
data: {
columns: [
["data1", 300, 350, 300, 0, 0, 0],
["data2", 130, 100, 140, 200, 150, 50]
],
types: {
data1: "bar",
data2: "area"
}
},
transition: {
duration: 0
}
}, "./chart02.png");
```
--------------------------------
### Usage Example 1: Area Chart
Source: https://github.com/naver/billboard.js/wiki/How-to-generate-chart-image-in-Node.js-environment?
This example demonstrates generating an area step and area spline chart and saving it as 'chart01.png'. Ensure 'transition.duration' is set to 0 to prevent rendering issues.
```js
// index.mjs
import screenshot from "./screen.mjs";
await screenshot({
data: {
columns: [
["data1", 300, 350, 300, 0, 0, 0],
["data2", 130, 100, 140, 200, 150, 50]
],
types: {
data1: "area-step",
data2: "area-spline"
}
},
// IMPORTANT:
// Specify 'transition.duration=0' to avoid partial rendering
// caused by the transition(animation).
transition: {
duration: 0
}
}, "./chart01.png");
```
--------------------------------
### Conventional Commits Body Example
Source: https://github.com/naver/billboard.js/blob/master/CONTRIBUTING.md
An example of a commit message that includes a body, detailing the changes made. It also shows how to indicate a breaking change.
```bash
():
Update condition of tick to avoid unnecessary tick rendering
```
--------------------------------
### Clone billboard.js Repository
Source: https://github.com/naver/billboard.js/blob/master/DEVELOPMENT.md
Clone the billboard.js repository to your local machine and navigate into the project directory. Ensure you have Node.js 10.10.0 or higher installed.
```bash
# Create a folder and move.
$ mkdir billboard.js && cd billboard.js
# Clone the repository.
$ git clone https://github.com/naver/billboard.js.git
```
--------------------------------
### Install Nightly Version via package.json
Source: https://github.com/naver/billboard.js/blob/master/README.md
To use the latest build from the master branch, specify the nightly version in your package.json file. This allows you to test upcoming changes before the official release.
```json
{
...
"billboard.js": "naver/billboard.js#nightly"
}
```
--------------------------------
### App Bootstrap Module Registration
Source: https://github.com/naver/billboard.js/blob/master/MODULE_IMPORTS.md
Centralize module imports and invocations in a single setup file (e.g., src/chart-setup.js) for your application. This ensures all necessary modules are registered once, allowing route-level code to use plain bb.generate() configurations.
```javascript
// src/chart-setup.js — imported once from the app entry
import {bar, line, pie, grid, regions, category, zoom} from "billboard.js";
bar(); line(); pie();
grid(); regions(); category();
zoom();
```
```javascript
// src/main.js (or pages/_app.tsx, app/layout.tsx, etc.)
import "./chart-setup"; // side-effect import — registers once
import bb from "billboard.js";
// …mount app…
```
```javascript
// src/pages/dashboard.js
import bb from "billboard.js";
// Nothing else to import. Write config the v3 way.
bb.generate({
bindto: "#a",
data: { type: "bar", columns: [...] },
grid: { x: { lines: [...] } }
});
```
```javascript
// src/pages/report.js — a totally different route
import bb from "billboard.js";
bb.generate({
bindto: "#b",
data: { type: "pie", columns: [...] }
});
// chart.regions([...]) also works here — registered by chart-setup.js
```
--------------------------------
### Import ESM Dependencies with Import Maps (Local)
Source: https://github.com/naver/billboard.js/wiki/How-to-load-as-ESM-directly-from-the-browser?
Configure import maps to point to local modules within the `node_modules` directory. This is used when billboard.js is installed locally.
```html
```
--------------------------------
### Enabling Zoom Interaction in Billboard.js
Source: https://github.com/naver/billboard.js/blob/master/MODULE_IMPORTS.md
Import the 'zoom' module and enable it via the `zoom.enabled` option in `bb.generate`. This example also uses the 'bar' chart type.
```javascript
import bb, {bar, zoom} from "billboard.js";
bb.generate({
zoom: { enabled: zoom() },
data: { type: bar(), columns: [...] }
});
```
--------------------------------
### Integrating Multiple Optional API Modules in Billboard.js
Source: https://github.com/naver/billboard.js/blob/master/MODULE_IMPORTS.md
Import and integrate various optional API modules like grid, regions, category, exportApi, and flow. This example demonstrates their usage with `bb.generate` and direct chart method calls.
```javascript
import bb, {bar, grid, regions, category, exportApi, flow} from "billboard.js";
const chart = bb.generate({
...grid(),
...regions(),
...category(),
...exportApi(),
...flow(),
data: { type: bar(), columns: [...] },
grid: { x: { lines: [...] } },
regions: [{ start: 1, end: 2 }]
});
chart.xgrids([...]);
chart.regions([...]);
chart.category(0);
chart.export();
chart.flow({ columns: [...] });
```
--------------------------------
### Create Line and Bar Chart with nvd3
Source: https://github.com/naver/billboard.js/wiki/Comparison-table
Example of creating a line and bar chart using nvd3. It demonstrates data structure, chart model selection, margin configuration, and custom tick formatting for axes.
```javascript
nv.addGraph(function() {
var data = [{
"key": "Quantity",
"bar": true,
"color": "#ccf",
"values": [
[1136005200000, 1271000.0],
[1138683600000, 1271000.0],
[1141102800000, 1271000.0],
[1143781200000, 0],
[1146369600000, 0],
]
},
{
"key": "Price",
"color": "#333",
"values": [
[1136005200000, 71.89],
[1138683600000, 75.51],
[1141102800000, 68.49],
[1143781200000, 62.72],
[1146369600000, 70.39]
]
}
];
var chart = nv.models.linePlusBarChart()
.margin({
top: 30,
right: 60,
bottom: 50,
left: 70
})
//We can set x data accessor to use index. Reason? So the bars all appear evenly spaced.
.x(function(d, i) {
return i
})
.y(function(d, i) {
return d[1]
});
chart.xAxis.tickFormat(function(d) {
var dx = data[0].values[d] && data[0].values[d][0] || 0;
return d3.time.format('%x')(new Date(dx))
});
chart.y1Axis.tickFormat(d3.format(',f'));
chart.y2Axis.tickFormat(function(d) {
return '$' + d3.format(',f')(d)
});
chart.bars.forceY([0]);
d3.select('#chart svg')
.datum(data)
.transition()
.duration(0)
```
--------------------------------
### Conventional Commits Type Examples
Source: https://github.com/naver/billboard.js/blob/master/CONTRIBUTING.md
Examples of commit types and their usage. 'skip:' type is used for commits made after the first one, often for code review changes, and is ignored by commit hooks.
```bash
fix(Axis): Correct tick rendering
```
```bash
skip: Applied the review
```
--------------------------------
### Conventional Commits Footer Example
Source: https://github.com/naver/billboard.js/blob/master/CONTRIBUTING.md
Illustrates how to reference related GitHub issues in the commit footer using the 'Ref #ISSUE-NO' format. Also shows the 'BREAKING CHANGE:' notation.
```bash
Ref #20
```
```bash
fix(Axis): Correct tick rendering
Update condition of tick to avoid unnecessary tick rendering
Ref #20
```
```bash
feat(tooltip): Intent to ship tooltip.contents.template
- Implementation of tooltip.contents.template
- Update legend template processing with util's .tplProcess()
Ref #813
```
```bash
feat(browser): Drop support for IE 11
Drop support for IE 11.
Ref #31
BREAKING CHANGE: Internet Explorer 11 is a burden to support and at EOL.
```
--------------------------------
### Create Mixed Chart with Chart.js
Source: https://github.com/naver/billboard.js/wiki/Comparison-table
Example of creating a mixed chart (bar and line) with Chart.js. It shows how to define datasets with different types and configure chart options like axes, title, and legend.
```javascript
var mixedChart = new Chart(document.getElementById("myChart"), {
type: 'bar',
data: {
datasets: [{
label: 'Bar Dataset',
data: [10, 20, 30, 40],
backgroundColor: 'rgba(255, 99, 132, 0.2)',
}, {
label: 'Line Dataset',
data: [0, 15, 30, 50],
borderColor: 'rgba(255, 255, 0, 0.1)',
backgroundColor: 'rgba(255, 99, 132, 0.1)',
// Changes this dataset to become a line
type: 'line'
}],
labels: ['January', 'February', 'March', 'April']
},
options: {
scales: {
yAxes: [{
ticks: {
beginAtZero:true
}
}]
},
title: {
display: true,
text: 'Chart.js example'
},
legend: {
display: true,
position: 'bottom'
}
}
});
```
--------------------------------
### Generate Temperature and Rainfall Chart with Highcharts
Source: https://github.com/naver/billboard.js/wiki/Comparison-table
Highcharts example for plotting temperature (spline) and rainfall (column) on a chart with dual y-axes. Demonstrates configuration for chart type, axes formatting, tooltips, and legend.
```javascript
Highcharts.chart('container', {
chart: {
zoomType: 'xy'
},
title: {
text: 'Average Monthly Temperature and Rainfall in Tokyo'
},
subtitle: {
text: 'Source: WorldClimate.com'
},
xAxis: [{
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
crosshair: true
}],
yAxis: [{ // Primary yAxis
labels: {
format: '{value}°C',
style: {
color: Highcharts.getOptions().colors[1]
}
},
title: {
text: 'Temperature',
style: {
color: Highcharts.getOptions().colors[1]
}
}
}, { // Secondary yAxis
title: {
text: 'Rainfall',
style: {
color: Highcharts.getOptions().colors[0]
}
},
labels: {
format: '{value} mm',
style: {
color: Highcharts.getOptions().colors[0]
}
},
opposite: true
}],
tooltip: {
shared: true
},
legend: {
layout: 'vertical',
align: 'left',
x: 120,
verticalAlign: 'top',
y: 100,
floating: true,
backgroundColor: (Highcharts.theme && Highcharts.theme.legendBackgroundColor) || '#FFFFFF'
},
series: [{
name: 'Rainfall',
type: 'column',
yAxis: 1,
data: [49.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4],
tooltip: {
valueSuffix: ' mm'
}
}, {
name: 'Temperature',
type: 'spline',
data: [7.0, 6.9, 9.5, 14.5, 18.2, 21.5, 25.2, 26.5, 23.3, 18.3, 13.9, 9.6],
tooltip: {
valueSuffix: '°C'
}
}]
});
```
--------------------------------
### Run the script
Source: https://github.com/naver/billboard.js/wiki/How-to-generate-chart-image-in-Node.js-environment?
Execute the index.mjs script to generate the chart images.
```sh
node index.mjs
# ==> will generate 'chart01.png' and 'chart02.png'
```
--------------------------------
### Custom Plugin Implementation Outline
Source: https://github.com/naver/billboard.js/wiki/Plugin-Interface
Provides a detailed outline for a custom plugin's `index.js` file, including constructor logic, lifecycle hooks ($beforeInit, $init, $redraw, $willDestroy), and how to access options and the chart instance (`$$`). Business logic should be placed within lifecycle hooks.
```javascript
class MyPlugin extends Plugin {
constructor(options) {
// plugin's option if necessary
// calling 'super', will assign options as instance member
super(options);
// you can access options as instance member
this.options;
// NOTE:
// Do not write business logic here, write within one of
// lifecycle hook methods($beforeInit, $init, etc.).
// At this point, chart isn't instantiated yet.
}
// will be executed at 'beforeInit' lifecycle
// lifecycle hook is optional. Do not specify if isn't necessary
$beforeInit() {
// the current chart instance variable 'this.$$'
// will be assigned by default as time of the initialization
this.$$; // access current chart instance's `chart.internal`
}
// 'init' hook (required)
$init() {
// write initial code for the plugin
}
// 'redraw' hook (required)
$redraw() {
// will be triggered as time of
// "redraw"(resize, data toggle, etc.) happens
}
// 'willDestroy' hook (not mandatory, but highly recommended to implement)
// will be triggered when '.destroy()' is called
$willDestroy() {
// write code releasing the resources used in this plugin
}
}
```
--------------------------------
### Basic React Component Usage
Source: https://github.com/naver/billboard.js/blob/master/packages/react/README.md
Demonstrates how to use the BillboardJS React component. It shows how to import necessary modules, set up chart options, and access the chart instance using a ref for API calls.
```jsx
import React, {useEffect, useRef} from "react";
// import billboard.js
import bb, {line} from "billboard.js";
import "billboard.js/dist/billboard.css"; // default css
// import react wrapper
import BillboardJS, {IChart} from "@billboard.js/react";
// const BillboardJS = require("@billboard.js/react"); // for CJS
function App() {
// to get the instance, create ref and pass it to the component
const chartComponent = useRef(null);
const options = {
data: {
columns: [
["data1", 300, 350, 300]
],
type: line()
}
};
useEffect(() => {
// get the instance from ref
const chart = chartComponent.current?.instance;
// call APIs
if (chart) {
chart.load( ... );
}
}, []);
return