DOCSEARCHbyAlgolia
Submit Docs

billboard.js

repository·master·Indexed 27 days ago

https://github.com/naver/billboard.js

A reusable JavaScript charting library based on D3 v4+ that provides an easy interface for creating various chart types. It supports both SVG and Canvas rendering modes, includes a React wrapper (@billboard.js/react), and offers multiple themes such as datalab, dark, insight, graph, and modern.

Tokens
16.1K
Snippets
44
Records
90
Agent score
90%

What's inside billboard.js

  1. Quickstart: Load billboard.js via Script Tags

    master

    You can load billboard.js by including D3.js and the billboard.js files in your HTML. You can either load them separately or use the packaged version which includes D3.js.

    <!-- Option 1: Load D3.js and billboard.js separately -->
<script src="https://d3js.org/d3.v6.min.js"></script>
<link rel="stylesheet" href="$YOUR_PATH/billboard.css">
<script src="$YOUR_PATH/billboard.js"></script>

<!-- Option 2: Load billboard.js packaged with D3.js -->
<link rel="stylesheet" href="$YOUR_PATH/billboard.css">
<script src="$YOUR_PATH/billboard.pkgd.js"></script>

  3. Style Canvas mode charts using selectors

    master

    When using render: { mode: 'canvas' }, standard SVG DOM nodes do not exist for styling. Instead, use canvas.theme.selectors to map billboard.js SVG selectors to canvas drawing styles.

    Key details:

    • canvas.theme.selectors is a compatibility mapping, not a full CSS engine. Unsupported selectors are ignored.
    • CSS property names can be written in kebab-case or camelCase (e.g., "stroke-width" or strokeWidth).
    • Comma-separated selector groups are supported.
    • Direct canvas.theme keys (like grid or shape) take precedence over selectors if both are provided.
    bb.generate({
  render: {
    mode: "canvas"
  },
  canvas: {
    theme: {
      selectors: {
        ".bb-axis .tick text": {
          fill: "#555",
          font: "12px sans-serif"
        },
        ".bb-grid line": {
          stroke: "#ddd",
          "stroke-width": 1,
          "stroke-dasharray": "2 2"
        },
        ".bb-bar": {
          stroke: "#fff",
          "stroke-width": 1
        }
      }
    }
  }
});

  4. Enable optional API modules in v4 (ESM only)

    master

    In billboard.js v4, several API modules are no longer auto-included in ESM builds to reduce bundle size. To use specific chart methods, you must explicitly import the corresponding resolver from billboard.js and spread its result into the bb.generate() configuration object.

    Note: UMD users are unaffected as the UMD entry auto-invokes all resolvers.

    Available Modules and their corresponding methods:

    • exportApi: enables chart.export()
    • flow: enables chart.flow()
    • grid: enables chart.xgrids() and chart.ygrids()
    • regions: enables chart.regions()
    • category: enables chart.category() and chart.categories()
    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.export();
chart.flow({ columns: [...] });

  6. Migrate from v1.x to v2.x: Internal State and Selection Access

    master

    In version 2.x, internal state and selection variables have been reorganized. If you were accessing private properties via chart.internal, you must update your references:

    • All states are now members of the state prop.
    • All selections are now members of the $el prop.

    Note: While Even is accessible, it is recommended not to use or access private values directly.

  8. Enable Canvas rendering mode for high-density charts

    master

    In v4, you can opt-in to a canvas rendering path to improve performance for high-density axis charts. To use it, you must import from the billboard.js/canvas entry point and set the render.mode option using the canvas() function.

    Note that the /canvas entry is a tree-shaking entry point. Importing shape resolvers from billboard.js/canvas installs canvas-compatible modules without the SVG overhead, whereas importing from the default billboard.js keeps the SVG resolver path.

    import bb, {bar, canvas} from "billboard.js/canvas";

const chart = bb.generate({
  render: {
    mode: canvas()
  },
  data: {
    columns: [
      ["data1", 30, 200, 100, 400]
    ],
    type: bar()
  }
});

  9. Use billboard.js via UMD/CDN

    master

    When using UMD builds (billboard.js, billboard.pkgd.js, or CDN), all modules are auto-included. You do not need to manually import or invoke resolvers; all features work out of the box.

    <script src="https://cdn.jsdelivr.net/npm/billboard.js/dist/billboard.pkgd.min.js"></script>
<script>
  const chart = bb.generate({ data: { type: "bar", columns: [["data1", 30, 200, 100]] } });
  chart.xgrids([{ value: 1, text: "L1" }]); // Works automatically
</script>

  11. Passing options via props

    master

    You can pass chart options directly as props to a component that wraps BillboardJS. If the chart type is passed via props, you must manually initialize the corresponding chart type module from billboard.js (e.g., Chart[props.data.type]()) to ensure the module is available, as this affects tree-shaking behavior.

    import * as Chart from "billboard.js";
import "billboard.js/dist/billboard.css";  // default css
import BillboardJS, {IChart, IChartOptions} from "../src/index";

export function App(props: IChartOptions) {
    const chartComponent = useRef<IChart>(null);

    // when chart "type" is passed from props, chart types need to be initialized separately.
    // in this scenario, only used chart type modules can't be "tree-shaken".
    Chart[props.data.type]();

    useEffect(() => {
        const chart = chartComponent.current?.instance;

        if (chart) {
            chart.load( ... );
        }
    }, []);

    return <BillboardJS 
        bb={Chart.bb} 
        options={props} 
        ref={chartComponent}
     />;
}