Boardplot

Boardplot is a chart library for AI agents and React apps: one JSON spec gives a consulting-grade business chart for reports, dashboards and slides, as SVG, PNG or a React component.

Gallery · Manual · Chart reference · AI agents · React · Changelog · Apache-2.0

This stacked column chart is one JSON spec drawn by boardplot render; the variance to the prior year above each column is computed from the data. Boardplot has 37 chart types, 83 variants and 649 example specs; the gallery shows each type with its spec.

Why Boardplot

• Business notation is built in: actual against plan and prior year, variances, bridges, event lanes and forecasts. Totals, shares and growth rates are computed from your data, and each render reports the numbers it derived.
• Automatic label placement: one collision solver places the labels, and a render reports every label it left out. A chart that cannot fit is refused with the size it needs.
• The same spec, settings and engine version give byte-identical SVG.
• One spec, { "type", "data", "options" }, works in React, the CLI and six MCP tools. A spec error comes back as JSON with the path, the expected value and a fix, so an agent can repair the spec.

Match your design system

• Set brand colours, series colours, type sizes and spacing through theme tokens, or start from one of ten presets. Bridge is the default.
• Style tables with the same tokens, or start from the ready table look.
• Use your own font: boardplot fonts build makes the width tables that layout measures with. The font files must be loaded where the chart is shown, and installed where a PNG is drawn.
• Choose the locale, the number formats and the reading target: report, dashboard, slide or print.

The theme reference lists every token.

Examples

Each chart links to its spec in the gallery. Companies, products, sources and numbers in the examples are invented.

Quick start

Boardplot needs Node.js 22.12 or newer.

npm install boardplot
cat > revenue.json <<'EOF'
{
  "name": "revenue",
  "type": "column",
  "data": {
    "categories": ["2024", "2025"],
    "series": [{ "id": "revenue", "label": "Revenue", "values": [120, 135] }]
  },
  "options": { "title": "Revenue grew 12.5 percent", "subtitle": { "measure": "Revenue" }, "unit": "$m" }
}
EOF
npx boardplot render revenue.json --out charts

This writes charts/revenue.svg and prints the result as JSON. Add --format png for a PNG. npx boardplot list shows every chart type, and npx boardplot fixtures --type waterfall prints complete example specs. To draw several charts in one call, which starts the CLI once, send { "version": 1, "charts": [...] } with a name per chart; see Several charts in one call.

The package has ES module entries only (import, not require). A new npm init project is CommonJS, so run npm pkg set type=module before a server-side script imports Boardplot.

Boardplot is at 0.x: options and output can change between minor versions. CHANGELOG.md lists each change.

AI agents

For Claude Code and Codex, install the plugin. It adds the MCP server and a chart skill. This repository is its marketplace:

claude plugin marketplace add boardplot/boardplot
claude plugin install boardplot@boardplot

codex plugin marketplace add boardplot/boardplot
codex plugin add boardplot@boardplot

The plugin installs the npm package at its own version into a Boardplot cache folder, so PNG works without a browser. For a machine without npm registry access, each release also has an offline ZIP with the runtime bundled; that route needs Chrome or Chromium for PNG. See the plugin README.

Any other MCP client: install the package globally once, then add the stdio server boardplot-mcp. It has six tools: boardplot_list, boardplot_describe, boardplot_fixtures, boardplot_measure, boardplot_render and boardplot_feedback. With a global install, npm does not run in the folder the agent works in, so that folder's npm settings cannot change which package runs. Run the same command again to update.

npm install -g boardplot

{
  "mcpServers": {
    "boardplot": { "command": "boardplot-mcp" }
  }
}

Claude Code and Codex also take the server without the plugin: claude mcp add boardplot -- boardplot-mcp or codex mcp add boardplot -- boardplot-mcp.

Then ask the agent for a chart, for example "Use Boardplot to draw an EBIT bridge from this data". llms.txt indexes the manual and the chart reference for language models.

React

React 18 or 19 is a peer dependency.

npm install boardplot react react-dom

import { ColumnChart } from 'boardplot/react/column';

const data = {
  categories: [{ id: '2024', label: '2024' }, { id: '2025', label: '2025' }],
  series: [{ id: 'revenue', label: 'Revenue', values: [120, 135] }],
};

export function Revenue() {
  return <ColumnChart data={data} title="Revenue grew 12.5 percent" unit="$m" size="container" fit="content" />;
}

Each chart type has its own entry, such as boardplot/react/column. BoardplotChart from boardplot/react/spec takes a whole spec instead. The React route, in order: Getting a chart in React, Rows in React for query rows, Container sizing, Theme provider and Export, which ends with a complete typed PNG and SVG download.

The catalog

37 chart types, 83 variants and 649 example specs. fixtures.md lists every example spec.

| Type | Aliases | Summary | |---|---|---| | column | | Vertical bars, grouped or stacked | | bar | | Horizontal bars per item | | line | profile | Lines and areas over time | | dimswitch | dim-switch-table, dim-switch | KPIs by one dimension and period, from sums | | table | tbl | Management table with totals | | waterfall | bridge | Bridge | | kpi | | Single-metric card | | combo | | Columns with line or area overlays | | variance | deviation | Variance tier against PY, PL or FC | | bullet | | KPI rows with bands and target | | bartable | bar-table, table-bars | Table rows with stacked bars, one panel per measure | | pvm | price-volume-mix | Price, volume and mix bridge | | pie | doughnut, donut | Pie or doughnut of shares | | status | | Entity by period state matrix | | heatmap | matrix | Row by column matrix | | gantt | timeline | Timeline with spans and events | | scatter | bubble | XY/bubble | | funnel | | Stage funnel with conversion rates | | pareto | pareto-chart | Sorted columns with cumulative curve | | mekko | marimekko, bar-mekko | Variable-width stacked columns | | sparkline | | One series as a mini line | | treemap | voronoi-treemap | Part of a whole as nested areas | | sankey | | Flows from sources to targets in stages | | grid | facets | Facets and metric stacks on one category axis | | slope | | Two-point slope lines | | dot | cleveland, dumbbell, lollipop | Dots, dumbbells or lollipops | | cohort | retention | Retention by cohort and period | | choropleth | | Region map coloured by value | | butterfly | | Two mirrored bar panes | | likert | diverging-stacked | Diverging bars for survey scales | | histogram | distribution, frequency | Equal-width bins of raw values | | box | boxplot, box-and-whisker | Box plots of raw observations | | waffle | | Share of a whole as a grid of cells | | pyramid | age-pyramid, population-pyramid | Mirrored bands on one scale | | diagram | | Node and edge diagrams, including system architecture | | tilemap | | Equal-size region tiles | | creative | | Ad-creative review card (early alpha) |

Documentation

• Gallery: one drawn example of each chart type, with its spec
• Use cases: prompts and steps for a slide deck, an analysis page, a React dashboard, a Word report or a weekly report built by an AI agent
• The manual: the spec, the MCP tools, the CLI, React, sizing, errors and themes
• Chart reference: one page per chart type, plus options, themes, React and fixtures
• llms.txt: an index of the manual and the reference for language models

Development

npm ci
npm run typecheck
npm test
npm run build

npm run docs:build regenerates docs/reference, the gallery, llms.txt and the catalog table above. CONTRIBUTING.md and AGENTS.md have the rules for a pull request. SECURITY.md says how to report a security problem.

License

Apache-2.0. See LICENSE and NOTICE.md.