#Plotissimo user guide
Plotissimo draws charts as SVG: line, bar and bubble charts, pies, donuts and rings, gauges, bullet charts, sparklines, radar and slope charts, heat maps, sunbursts, the materiality matrix and Gantt charts. This guide explains how to put a chart on a page, how to change it, and every option. The principles behind it are in design_principles.md.
This guide describes Plotissimo 0.4.1. Options may still change before 1.0.0 (see CHANGELOG.md).
Contents
- Installation
- Your first chart
- Chart types
- Chart options
- Title
- Legend
- Axes
- Scales
- Plot area: grid, zones and reference lines
- Series
- Materiality matrix
- Gantt chart
- Changing a chart after drawing
- Events
- Popups
- Themes and styling
- Accessibility
- Export: PNG and SVG
- Spacing values
- Troubleshooting
- Building blocks
- Frameworks
#1. Installation
In your project folder (a new, empty folder first needs a package.json; npm init -y makes one):
npm init -y # only if the folder has no package.json yet
npm install plotissimo
The files are then in node_modules/plotissimo/dist/:
| File | Use |
|---|---|
plotissimo.min.js |
for a <script> tag (the global Plotissimo) |
plotissimo.esm.js |
an ES module, for import |
plotissimo.css |
the stylesheet with the themes; every chart needs it, without it the chart has no colours |
plotissimo.d.ts |
the type definitions, for code completion in editors and TypeScript |
plotissimo.global.d.ts |
the same for the global Plotissimo of a <script> tag page |
Plotissimo has no runtime dependencies and needs no framework. There are three ways to use it; each has a complete page below.
A. A <script> tag (the simplest). The page loads the stylesheet and the script; the script makes the global
Plotissimo:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My first chart</title>
<link rel="stylesheet" href="node_modules/plotissimo/dist/plotissimo.css">
</head>
<body>
<div id="chart"></div>
<script src="node_modules/plotissimo/dist/plotissimo.min.js"></script>
<script src="charts.js"></script>
</body>
</html>
// charts.js — the first line gives your editor the types of the global Plotissimo (code completion)
/// <reference types="plotissimo/global" />
new Plotissimo.Chart("#chart", {
series: [{ type: "line", name: "Rotterdam", data: [[1, 60], [2, 72], [3, 81]] }],
});
You may also write the chart code inside a <script> in the page, but editors have no type information there, so no
code completion for the options. In production, copy the two files to your web server and adjust the paths.
B. import in your own module, without a bundler. An import map tells the browser where "plotissimo" is:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My first chart</title>
<link rel="stylesheet" href="node_modules/plotissimo/dist/plotissimo.css">
<script type="importmap">
{ "imports": { "plotissimo": "./node_modules/plotissimo/dist/plotissimo.esm.js" } }
</script>
<script type="module" src="src/main.js"></script>
</head>
<body>
<div id="chart"></div>
</body>
</html>
// src/main.js
import { Chart } from "plotissimo";
new Chart("#chart", {
series: [{ type: "line", name: "Rotterdam", data: [[1, 60], [2, 72], [3, 81]] }],
});
type="module"is needed forimport; the module runs when the page is loaded, so it may stand in the<head>.- A page with modules works only through a web server (
http://…), not opened from disk (file://): in PhpStorm use Open In > Browser, otherwise e.g.npx serve. - The stylesheet is a
<link>;import "plotissimo/plotissimo.css"works only with a bundler.
C. With a bundler (Vite, webpack, Rollup, esbuild): in your application's main file, e.g. src/main.js:
import { Chart, BarChart } from "plotissimo";
import "plotissimo/plotissimo.css"; // a bundler includes the stylesheet
new BarChart("#chart", { series: [{ data: [["Q1", 12], ["Q2", 18]] }] });
The bundler finds the package in node_modules, and makes one script and one stylesheet for your page. For
Laravel, React, Next.js, Vue, Angular and Svelte, see frameworks.
Code completion. With import (B, C) editors read the types from the package. For the global Plotissimo (A)
start your .js file with /// <reference types="plotissimo/global" />. The types describe every chart, option,
event and method; a chart class knows its default series type (in a BarChart a series without type is a bar
series; a series of another type names its type, {type: "line", …}). If an editor completes only words it has
seen in your files, its project set-up is not reading node_modules: in PhpStorm, close the project and open the
folder again.
#2. Your first chart
<div id="chart"></div>
<script>
const chart = new Plotissimo.Chart("#chart", {
title: { text: "Energy use", subtitle: "2026" },
axes: {
bottom: { title: "Month" },
left: { title: "Energy", unit: "MWh" },
},
series: [
{ type: "line", name: "Rotterdam", data: [[1, 60], [2, 72], [3, 81], [4, 77]] },
{ type: "line", name: "Utrecht", data: [[1, 40], [2, 45], [3, 52], [4, 61]] },
],
});
</script>
- The first parameter is the target: the element the chart goes into, normally found by its
id(here the<div id="chart">). Write it as"chart"or"#chart", as any other CSS selector (e.g.".dashboard .chart"), or pass the element itself (document.getElementById("chart")). If a selector matches several elements, the chart goes into the first one only, with a warning in the browser console. An<svg>is added to the element; if the target is an<svg>itself, the chart is drawn in it. - If there are no errors in the code or the configuration, the chart is drawn straight away (see
finding errors below). It fills the width of its container and keeps its proportions (
widthandheightset the proportions and the coordinate system, see chart options). - Each series gets the next colour of the theme's palette and an item in the legend.
#Finding errors
Look in two places:
The editor, while you type. Make
// @ts-checkthe first line of your.jsfile (above the/// <reference …>orimportline of installation). The editor (PhpStorm, VS Code, …) then underlines what is wrong, with the reason on hover, and lists it in its problems view (PhpStorm: View > Tool Windows > Problems):- a misspelled option, e.g.
titel("did you mean to write 'title'?"), or a misspelled chart class (BarChar); - a wrong kind of value, e.g. a number where text is expected (
unit: 5).
Without
// @ts-checkthe editor still completes the options, but it may not report these mistakes. The check needs a separate.jsfile: the editor does not check code inside a<script>in an HTML page. Within one object the editor may show one problem at a time: when you fix it, the next one appears.- a misspelled option, e.g.
The browser, when the page runs. Open the developer tools (Chrome, Edge and Firefox: F12 or Cmd+Option+I on a Mac; Safari: Cmd+Option+C, after Settings > Advanced > "Show features for web developers") and look at the Console. Plotissimo's messages start with
Plotissimo::- an error stops the chart, e.g.
Plotissimo: target not found: #chart(see troubleshooting); - a warning does not stop it, e.g. an old option name that still works until version 1.0, or a target that matches several elements.
The browser does not report a misspelled option: Plotissimo ignores options it does not know, so the chart is drawn without it. The editor check of step 1 finds those.
- an error stops the chart, e.g.
#Licence key
Plotissimo is commercial software. With a licence you get a licence key from N2 Management B.V.; set it once per page, before or after the charts are made:
Plotissimo.setLicenseKey("eyJ2IjoxLCJwcm9kdWN0Ijoi…");
or, before the library's script loads: <script>window.PLOTISSIMO_LICENSE_KEY = "…";</script>.
Without a valid key, every chart shows a watermark in its bottom right corner: the Plotissimo emblem (the "P" with the
robot) with "Plotissimo · unlicensed" and "www.plotissimo.com" on two lines beside it, sized to the chart (an emblem of 44 px for charts of 300 px and higher, 32 px
from 200 px, 22 px from 120 px; on smaller charts, such as sparklines, a smaller emblem and text on top of the chart), and
the browser console says once why (no key, expired, another domain, …). The charts work fully either way. On
development hosts there is no watermark: localhost, 127.0.0.1, *.localhost, *.local, *.test and pages
opened from disk (a frame without a host name of its own, such as <iframe srcdoc>, does show it). Charts of 120 px and higher keep a strip at the bottom for the watermark, so it covers nothing; on smaller charts it
lies on top, its text with an edge in the background colour.
To see the watermark on a development host, as on a customer's site: Plotissimo.previewWatermark(true) (or
window.PLOTISSIMO_PREVIEW_WATERMARK = true before the script loads). It can only turn the watermark on; a valid key
still removes it. examples/licence.html has a switch for it and a field to try a key.
The key is checked in the browser, without contacting a server: it is signed by N2 Management B.V., and the library
checks the signature, the domain (the page's host, e.g. www.example.com or every subdomain with *.example.com),
the version (a licence covers the versions released up to its "updates until" date) and, for a subscription, the
end date. The check needs the browser's cryptography, which works on https pages (and on development hosts).
Plotissimo.license() gives the page's status: {status: "none" | "pending" | "valid" | "invalid", reason, licensee, plan, domains, updatesUntil, expires, development}.
#3. Chart types
Chart draws any combination of series. The presets are the same chart with suitable defaults:
| Class | Default series type | What the preset changes |
|---|---|---|
Chart / LineChart |
line |
nothing |
BarChart |
bar |
the x scale is a category (band) scale; no vertical gridlines and no ticks on the bottom axis |
BubbleChart |
bubble |
600 × 600, square plot area, series not clipped, no legend |
MaterialityMatrix |
matrix |
640 × 680, square plot area, scales 0–9, quadrants and threshold lines, legend at the bottom, see section 11 |
PieChart |
pie |
no axes, no plot area background, legend at the right, see Pie, donut and rings |
GaugeChart |
gauge |
320 × 240, no axes, no legend, see Gauge |
BulletChart |
bullet |
rows from the top, value scale from 0, no plot area background, the height follows the rows (rowHeight 34), see Bullet chart |
SparklineChart |
line |
120 × 32, fixed size, no axes, legend, title or backgrounds; thin line with only the last point marked, see Sparkline |
RadarChart |
radar |
no axes, legend at the bottom, see Radar chart |
SlopeChart |
slope |
no axes or legend, room for the end labels, see Slope chart |
HeatmapChart |
heatmap |
band × band without gaps, the first row at the top, no ticks or grid, legend at the bottom, see Heat map |
SunburstChart |
sunburst |
no axes, the main branches in the legend at the bottom, see Sunburst |
WaterfallChart |
waterfall |
the x scale is a category (band) scale, the kinds (increase, decrease, total) in the legend at the bottom, see Waterfall |
LimitDiagram |
limit |
the x scale is a category (band) scale, the sources in the legend at the bottom, room at the left and right for the line labels and gap arrows, see Limit diagram |
SankeyChart |
sankey |
760 × 420, no axes, no legend, no plot area background, see Sankey diagram |
HistogramChart |
histogram |
linear x and y scales, no vertical gridlines, no legend, see Histogram |
BoxPlotChart |
boxplot |
the x scale is a category (band) scale, no legend, see Box plot |
FunnelChart |
funnel |
560 × 360, no axes, no legend, see Funnel |
TreemapChart |
treemap |
720 × 440, no axes, no legend, see Treemap |
ScoreCardChart |
scorecard |
360 × 135, no axes, no legend, see Score card |
GanttChart |
gantt |
time scale on x, rows (band scale) on y from the top, stripes, today's line, the height follows the rows, see section 12 |
Options you pass always win over the preset. A series without type gets the chart's default type
(seriesType).
new Plotissimo.BarChart("#sales", {
series: [
{ name: "2025", data: [["Q1", 12], ["Q2", 18], ["Q3", 15], ["Q4", 21]] },
{ name: "2026", data: [["Q1", 14], ["Q2", 20], ["Q3", 19], ["Q4", 25]] },
],
});
#4. Chart options
| Option | Default | Meaning |
|---|---|---|
width, height |
640, 400 |
the size in pixels (the SVG's viewBox); with responsive: true the proportions |
responsive |
true |
true: fill the container's width and keep the proportions (text scales along); "fill": the container's width and height, text at its real size, redrawn when the container changes, see sizes; false: exactly width × height pixels |
padding |
8 |
space between the edge of the chart and its contents (spacing value) |
theme |
"default" |
"default", "dark", "minimal" or your own (themes) |
effects |
null |
"elevated" (soft shadows, a lift on hover), "glow" (a glow in each element's colour), or both as an array, see effects |
palette |
null |
the series colours of this chart, e.g. ["#172554", "#f59e0b"], or a named palette ("colorblind", "blue", "blue-dark"), instead of the theme's (palette) |
className |
"" |
extra class names on the <svg> |
background |
true |
draw the chart background (false: transparent) |
seriesType |
"line" |
the type of a series without type |
seriesDefaults |
{} |
per series type, the options its series start from, e.g. {line: {lineWidth: 1}, bar: {cornerRadius: 2}}; a series' own options win |
rowHeight |
null |
pixels per row of a band scale y (Gantt, bullet charts): the chart's height follows the number of rows; null keeps height |
fontSize |
12 |
only used to estimate text sizes when there is no browser (tests, server) |
title |
{} |
title options |
legend |
{} |
legend options |
axes |
bottom and left on | axis options per position: bottom, left, top, right |
scales |
x and y linear |
scale options per scale key |
plotArea |
{} |
plot area options |
series |
[] |
the series |
popup |
null |
a function that gives the content of an HTML popup when a part is clicked, see popups |
animation |
true |
parts grow or fade in on the first draw and move to their new place after a change; false, or {enter, update, duration}, see animations |
accessibility |
{label: null, description: "auto", table: false} |
the name and description screen readers read, and the data as hidden tables, see accessibility |
draw |
true |
draw at once; false: call chart.draw() yourself |
#Chart sizes
responsive |
The chart is | Use it for |
|---|---|---|
true (default) |
as wide as its container, as high as its proportions (width / height) give; the whole drawing scales, text too |
charts in a text column, reports |
"fill" |
exactly its container's width and height; the layout uses that space, text keeps its size; when the container changes size (window, grid, panel), the chart lays itself out again (ResizeObserver) |
dashboards and tiles: every chart in a grid row as high as the row |
false |
exactly width × height pixels |
sparklines in table cells, images |
With "fill", CSS decides the size: give the container a height, e.g. grid-auto-rows: 340px on a grid, a
height, aspect-ratio or flexbox. The chart lies in its container absolutely (it never makes its container
larger); a container without a height of its own gets the height option as its min-height. Charts whose rows
decide their height (rowHeight, Gantt and bullet charts) only take the container's width.
.dashboard { display: grid; grid-template-columns: repeat(3, 1fr); grid-auto-rows: 340px; gap: 16px; }
new Plotissimo.BarChart(".dashboard .tile-1", { responsive: "fill", series: [...] });
All key elements (title, legend, axes) also take these general options:
| Option | Default | Meaning |
|---|---|---|
visible |
true |
show the element |
padding, margin |
element-specific | space inside and outside the element (spacing value) |
width, height |
"auto" |
a fixed size in pixels instead of the measured size |
background |
false |
draw a background rectangle (class pl-bg, style it in CSS) |
className |
"" |
extra class names on the element's group |
#5. Title
title: { text: "Energy use", subtitle: "2026", align: "left", span: "plot" }
| Option | Default | Meaning |
|---|---|---|
text |
"" |
the title; also the accessible name of the chart |
subtitle |
"" |
a second, smaller line |
position |
"top" |
"top" or "bottom" |
align |
"center" |
"left", "center", "right" |
span |
"chart" |
"chart": aligned with the full width; "plot": aligned with the plot area |
gap |
2 |
pixels between title and subtitle |
padding |
[4, 0, 8, 0] |
Without text and subtitle the title takes no space.
#6. Legend
legend: { position: "bottom", title: "Sites" }
| Option | Default | Meaning |
|---|---|---|
position |
"right" |
"right", "left", "top", "bottom"; at the top or bottom the items wrap over several rows |
title |
"" |
a heading above the items |
toggleSeries |
true |
a click (or Enter / Space) on an item hides or shows its series |
symbolSize |
12 |
size of the symbol in pixels |
symbolGap |
6 |
between symbol and label |
itemGap |
6 |
between items (between columns: twice this) |
valign |
"top" |
at the left or right: "top" or "middle" |
padding |
8 |
The legend shows one item per series that has a name. A series with legend: false has no item. The materiality
matrix shows one item per category instead. The axes do not move when a series is hidden: hidden series still count
for the scales.
#7. Axes
There are four axes: bottom and top (horizontal) and left and right (vertical). An axis has its title and
ticks, and its range: min, max, step and the other range settings below go on the axis itself. The top and
right axes are off until you give them options; visible: false hides an axis, visible: true shows one without
other options.
A series uses the bottom and left axes; yAxis: "right" puts it on the right axis (with a range of its own),
xAxis: "top" on the top axis. A right axis that no series uses repeats the left one.
new Plotissimo.Chart("#chart", {
axes: {
bottom: { title: "Month", min: 0, max: 12, step: 1 },
left: { title: "Energy", unit: "MWh", min: 0, max: 100 },
right: { title: "Price", unit: "€", min: 0, max: 0.4 },
},
series: [
{ type: "line", name: "Energy", data: [[1, 60], [2, 72], [3, 81]] },
{ type: "line", name: "Price", yAxis: "right", data: [[1, 0.21], [2, 0.24], [3, 0.19]] },
],
});
Range settings (without them the range follows the data):
| Option | Default | Meaning |
|---|---|---|
min, max |
from the data | the ends of the axis, kept exactly |
step |
a round step | the distance between ticks, e.g. 25 |
nice |
true |
round the ends found from the data outward to the step (not fixed min / max) |
includeZero |
false |
always include 0 (without a fixed min) |
reverse |
false |
the other way round (e.g. rank 1 at the top) |
type |
the chart's | "linear" (numbers), "band" (categories), "time" (dates); without a type (line and bubble charts) numbers, or categories when the values are text, e.g. ["Jan", 12] |
categories |
from the data | a band axis: the categories in a fixed order |
paddingInner, paddingOuter |
0.2, 0.1 |
a band axis: space between the bands and at the ends |
interval, locale |
automatic, "en" |
a time axis: the tick interval ("month", "year", …) and the language of month names |
The other axis options:
| Option | Default | Meaning |
|---|---|---|
visible |
bottom, left: true; top, right: false |
|
scale |
see scales | advanced: the key of a scale this axis shows (normally not needed) |
title |
"" |
the axis title |
unit |
"" |
unit of measure, shown as "Title (unit)" |
showUnit |
true |
show the unit of measure |
line |
true |
draw the axis line |
ticks.major |
{show: true, size: 6, direction: "out", count: "auto", spacing: null} |
major ticks; direction: "out", "in" or "cross"; count: a fixed number of intervals; spacing: pixels per interval when count is "auto" (default 80 horizontal, 50 vertical) |
ticks.minor |
{show: false, size: 3, direction: "out", count: 4} |
minor ticks; count per major interval |
labels.show |
true |
tick labels |
labels.format |
null |
a function (value, axis) => text; default: the value with as many decimals as the step |
labels.rotate |
0 |
angle in degrees, e.g. -45 for long category names |
labels.gap |
4 |
between tick and label |
labels.overlap |
"hide" |
"hide": labels that would overlap are left out; "show": always all |
labels.minGap |
4 |
minimum pixels between labels before they count as overlapping |
titleGap |
6 |
between labels and title |
The gridlines of the plot area use the same ticks as the axes.
#8. Scales
Normally you set ranges on the axes (min, max, … in axes). Underneath, each axis shows a scale,
which turns data values into positions: x (bottom), y (left), x2 (top) and y2 (right, when a series uses it or
it has settings of its own). The scales option sets them directly: for a scale that no axis shows, for several series
sharing an extra scale (series option x / y with the scale's key), or in code written before the range settings
were on the axes. Settings on an axis win over scales.
Settings of the scales:
scales: {
x: { type: "linear" },
y: { min: 0, includeZero: true },
y2: { min: 0, max: 100 },
}
Linear scale (type: "linear", the default)
| Option | Default | Meaning |
|---|---|---|
min, max |
from the data | fixed bounds |
step |
automatic | a fixed distance between major ticks; otherwise 1, 2, 2.5 or 5 × a power of ten |
nice |
true |
round bounds from the data outward to a whole step |
includeZero |
false |
always include 0 |
reverse |
false |
high values at the left / bottom |
Band scale (type: "band"): categories, for bars; also for a line chart whose x values are text (["Jan", 12]), without setting it. Dates as text ("2026-03-31") are categories too: for a date axis set type: "time".
| Option | Default | Meaning |
|---|---|---|
categories |
in order of appearance in the data | a fixed list and order of categories |
paddingInner |
0.2 |
space between bands, as a fraction of a band |
paddingOuter |
0.1 |
space before the first and after the last band |
reverse |
false |
reverse the order |
A bar chart is vertical when x is the band scale, and horizontal when y is:
new Plotissimo.BarChart("#c", {
scales: { x: { type: "linear" }, y: { type: "band" } },
series: [{ data: [[12, "Rotterdam"], [8, "Utrecht"]] }],
});
Time scale (type: "time"): dates. Values may be Date objects, timestamps (milliseconds) or date strings such
as "2026-03-31". Ticks fall on calendar dates: days, weeks (Mondays), months, quarters, half years, years, ...,
chosen for the space available. Dates are handled in UTC, so a date without a time never shifts a day.
| Option | Default | Meaning |
|---|---|---|
min, max |
from the data | fixed bounds (a date) |
nice |
true |
round bounds from the data outward to the tick interval |
interval |
automatic | a fixed tick interval: "day", "2 days", "week", "2 weeks", "month", "2 months", "quarter", "half year", "year", "2 years", "5 years", "10 years", ... |
locale |
"en" |
the language of the month names, e.g. "nl" |
format |
automatic | (date, scale) => text; default "Jan 2026" at the first tick and in January, otherwise "Apr" (days: "12 Jan") |
reverse |
false |
Minor ticks (axes.bottom.ticks.minor.show) fall on the next smaller unit, e.g. months between quarters.
new Plotissimo.LineChart("#c", {
scales: { x: { type: "time", interval: "quarter" } },
series: [{ data: [["2026-01-15", 12], ["2026-04-15", 18], ["2026-08-01", 15]] }],
});
#9. Plot area: grid, zones and reference lines
| Option | Default | Meaning |
|---|---|---|
background |
true |
the plot area background |
border |
true |
a border around the plot area |
clip |
true |
cut off series outside the plot area |
aspectRatio |
null |
width / height, e.g. 1 for a square plot area |
margin |
0 |
space between the plot area (with its axes) and the title / legend |
grid.horizontal |
{axis: "left", major: {show: true}, minor: {show: false}} |
horizontal gridlines, following the ticks of axis |
grid.vertical |
{axis: "bottom", major: {show: true}, minor: {show: false}} |
vertical gridlines |
stripes |
false |
alternating row (or column) backgrounds: true follows the left axis, or {axis: "bottom", odd: false} |
fills |
[] |
coloured zones, see below |
lines |
[] |
reference lines, see below |
Zones (fills) colour part of the plot area, behind the data. Positions are data values.
plotArea: {
fills: [
{ y0: 0, y1: 50, color: "#dcfce7", label: "Target", labelPosition: "top-right" },
{ x0: 3, color: "#fee2e2", opacity: 0.5 }, // from x = 3 to the edge
{ points: [[1, 10], [4, 80], [4, 10]], color: "#e0e7ff" }, // polygon
{ shape: "ellipse", cx: 5, cy: 50, rx: 1, ry: 20, color: "#fef9c3" },
{ d: (s) => `M${s.x(1)},${s.y(0)} L${s.x(6)},${s.y(90)}`, stroke: "#999" }, // free SVG path
{ y0: 60, color: "#6366f1", shade: { direction: "up" } }, // gradient
],
}
| Option | Meaning |
|---|---|
x0, x1, y0, y1 |
a rectangle; a missing bound is the edge of the plot area; on a band scale a category |
points |
a polygon: [[x, y], ...] |
shape: "ellipse", cx, cy, rx, ry |
an ellipse |
d |
an SVG path, or a function that receives {x(value), y(value), width, height} and returns one |
color, opacity, stroke |
colours (without color the theme's first palette colour, faint) |
shade |
a gradient: true, or {type: "linear" | "radial", direction: "up" | "down" | "left" | "right", stops: [[offset, colour, opacity], ...]}; direction is the way the zone fades towards ("up": full at the bottom, faint at the top), the opposite of a series' gradient, whose direction is the side with the full colour |
cornerRadius |
rounded corners of a rectangle |
label |
a text in the zone, drawn in front of the gridlines |
labelPosition |
for a rectangle: "top-left" (default), "top-right", "bottom-left", "bottom-right" |
labelAt |
[x, y] in data values: the label's centre (any shape) |
labelInset |
pixels from the corner, default 6 |
labelClassName, className |
extra classes |
x, y |
other scale keys |
Reference lines are dashed lines at a value, e.g. a target or a threshold:
plotArea: { lines: [{ y: 75, label: "Target" }, { x: 6, className: "my-line" }] }
x gives a vertical line, y a horizontal one; xScale / yScale pick another scale. A line outside the plot
area's range is left out.
| Option | Meaning |
|---|---|
label |
a text with the line |
labelPosition |
"inside" (default: in the plot area, next to the line), or for vertical lines a badge outside the plot area: "outside-top" or "outside-bottom". The layout keeps room for badges between the plot area and its axes, so they never cover the data |
title |
a text shown on hover (e.g. the full date) |
className |
extra classes; a badge gets <className>-badge, e.g. .pl-today-badge |
plotArea: { lines: [{ x: "2030-01-01", label: "Target 2030", labelPosition: "outside-top", title: "−55 % CO₂" }] }
#10. Series
Options for every series type:
| Option | Default | Meaning |
|---|---|---|
type |
the chart's seriesType |
"line", "bar", "bubble", "matrix" |
name |
"" |
the name in the legend |
data |
[] |
the data, see below |
yAxis |
"left" |
"right": the series uses the right axis, with a range of its own |
xAxis |
"bottom" |
"top": the series uses the top axis |
x, y |
"x", "y" |
advanced: scale keys (see scales); xAxis / yAxis set them |
color |
palette | a fixed colour for this series (does not change with the theme or the palette) |
visible |
true |
|
legend |
true |
false: no legend item |
className |
"" |
extra classes on the series group |
Data is a list of points, as arrays or as objects:
data: [[1, 60], [2, 72]] // [x, y] (bubble: [x, y, size])
data: [{ x: 1, y: 60, label: "Start", color: "#e11d48" }] // objects: extra fields per point
A point with x or y null is skipped. Fields per point: label (data label), color (this point only); bubbles
also size, shortLabel, selected; line points marker, markerSize, markerFill, markerFillColor,
markerLineWidth, showLabel.
#Line
The x axis follows the data: numbers give a number axis, text (["Jan", 12]) gives categories in the order of
the data. Dates need axes: { bottom: { type: "time" } }.
| Option | Default | Meaning |
|---|---|---|
line |
true |
false: no line, markers only |
lineWidth |
2 (stylesheet) |
the line width in pixels |
lineStyle |
"solid" |
a dash pattern, see below |
points |
true |
which points get a marker: true (all), false, or only "last", "first-last", "min-max", "extremes" (min, max and last); the classes pl-point-first / -last / -min / -max colour them (min red, max green) |
marker |
"circle" |
"circle", "square", "triangle", "star", "x", "+" (also "plus") |
markerSize |
8 |
the width and height of a marker in pixels |
markerFill |
false |
false: hollow (the line shows through); true: filled with markerFillColor. "x" and "+" are lines only and never filled |
markerFillColor |
the line colour | the fill colour of filled markers, any CSS colour; "var(--pl-bg)" gives the background colour of the theme |
markerLineWidth |
lineWidth |
the line width of the markers |
area |
false |
fill between the line and the zero line (stacked: the series below it) |
gradient |
null |
the area fading out towards the bottom, see gradients |
stack |
null |
a name: line series with the same name pile up, usually with area: true, see stacks |
labels |
"click" |
the points' label: "click" (a click on the point shows / hides it), "always" (or true), false |
series: [
{ name: "Measured", marker: "square", markerSize: 10, markerFill: true, data: [[2019, 820], [2020, 760]] },
{ name: "Forecast", lineStyle: "-", lineWidth: 1, marker: "+", data: [[2020, 760], [2021, 700]] },
{ name: "Samples", line: false, marker: "triangle", markerFill: true, markerFillColor: "#fde68a",
data: [[2019, 790], { x: 2020, y: 735, marker: "star", markerSize: 12 }] },
]
Markers. Every shape fits a box of markerSize × markerSize centred on the point. A point can override
marker, markerSize, markerFill, markerFillColor and markerLineWidth of its series. Setting
markerFillColor alone does not fill a marker: markerFill: true is needed too.
Line styles. lineStyle takes a short code; spaces are ignored, so " . - " is the same as ".-". The dashes
and gaps grow with lineWidth, so a pattern keeps its look on thin and thick lines.
lineStyle |
Line |
|---|---|
"solid" |
solid (the default) |
"-" |
dashes |
"--" |
long dashes |
"..." |
dots |
".-" |
dot-dash |
"-.." |
dash-dot-dot |
"--." |
long dash-dot |
[8, 3] or "8 3" |
your own pattern: dash and gap lengths in pixels, as SVG stroke-dasharray |
An unknown code gives the error Plotissimo: unknown line style.
Legend. A line series' legend symbol is the series' own line (width and style) with its marker (shape, fill and
line width) in the middle, so it looks like the plot. The symbols of a legend with line series are wider (2.5 ×
symbolSize), so that the line style is visible.
CSS. Markers have the classes pl-point pl-marker pl-marker-<shape> (pl-marker-plus for +), and
pl-marker-filled when filled; the fill colour is the variable --pl-marker-fill.
#Bar
| Option | Default | Meaning |
|---|---|---|
groupPadding |
0.05 |
space between the bars of one category |
barWidth |
12 |
bar width in pixels when neither scale is a band scale |
cornerRadius |
0 |
rounded corners in pixels |
labels |
false |
true: the value at the end of each bar (or the point's label); stacked: in the middle of its segment, when the segment is big enough |
format |
null |
(value, point) => text for the labels and the stack totals (a total's point is {total: true}) |
gradient |
null |
a gradient fill, full at the bar's end, see gradients |
stack |
null |
a name: bar series with the same name pile up, see stacks |
Several bar series on one band scale are drawn side by side. Bars start at zero; negative values point the other way
(class pl-bar-negative).
#Stacked bars and areas
Series with the same stack name pile up per category: bars on bars, or areas on areas (line series with
area: true). Positive values stack upwards from zero, negative values downwards. Different stack names stand side
by side, so a chart can show grouped stacks (e.g. per quarter a stack for 2025 and one for 2026).
new Plotissimo.BarChart("#scopes", {
stackTotals: true,
series: [
{ name: "Scope 1", stack: "emissions", labels: true, data: [["2025", 540], ["2026", 510]] },
{ name: "Scope 2", stack: "emissions", labels: true, data: [["2025", 160], ["2026", 120]] },
{ name: "Scope 3", stack: "emissions", labels: true, data: [["2025", 1250], ["2026", 1190]] },
],
});
new Plotissimo.LineChart("#energy", {
scales: { x: { type: "time" } },
series: [
{ name: "Gas", stack: "energy", area: true, points: false, data: [...] },
{ name: "Solar", stack: "energy", area: true, points: false, data: [...] },
],
});
| Chart option | Default | Meaning |
|---|---|---|
stackMode |
"normal" |
"percent": every category adds up to 100 (each value as a share of the category's total); set the axis labels to (v) => v + "%" |
stackTotals |
false |
stacked bars: the total above each stack (and below it, for negative values); not in percent mode |
The order of the series is the order of the stack, from the bottom up. A hidden series (legend) leaves its stack, and the others close up. A category missing in one series simply adds nothing there. Labels inside the segments are dark or white by the segment's colour.
#Bubble
| Option | Default | Meaning |
|---|---|---|
minRadius, maxRadius |
4, 28 |
the radius of the smallest and largest size; the area grows with the size |
sizeDomain |
from the data | [min, max] of the sizes, e.g. to compare several charts |
radius |
10 |
the radius of points without size |
labels |
"hover" |
"hover", "always" (or true), false |
selectable |
true |
a click selects / deselects a bubble and brings it to the front |
shortLabel is drawn inside the bubble. Large bubbles are drawn first, so small ones stay visible.
Bubbles are always circles: the marker options (marker, markerFill, ...) are for line series only.
#Pie, donut and rings
new Plotissimo.PieChart("#suppliers", {
title: { text: "Suppliers per country" },
series: [{
innerRadius: 0.62, // a donut; 0 (the default) is a pie
centerLabel: (total) => total, // a text in the middle
centerSubLabel: "suppliers",
data: [["Netherlands", 48], ["Germany", 31], { label: "Other", value: 9, color: "#94a3b8" }],
}],
});
Data: [label, value] or {label, value, color, textColor, className, id, ...}. Values of zero or less are
left out. Each slice gets the next palette colour; color sets its own.
| Option | Default | Meaning |
|---|---|---|
innerRadius |
0 |
the hole, as a fraction of the radius: 0 pie, e.g. 0.6 donut |
outerRadius |
1 |
the outside, as a fraction of the radius; with innerRadius several pie series nest as rings |
startAngle, endAngle |
0, 360 |
degrees, 0 at 12 o'clock, clockwise; -90 and 90 give the upper half circle. The shape is fitted to the plot area, so a half circle uses the full width |
padAngle |
0 |
degrees of space between the slices |
sort |
false |
true: largest slice first |
labels |
"auto" |
"inside", "outside" (with a leader line; labels on one side are pushed apart so they do not overlap), "auto" (inside when it fits, otherwise outside), false |
labelFormat |
percentage | (datum, {value, percent, total}) => text; default "41%" inside and "Netherlands 41%" outside |
minLabelAngle |
4 |
degrees: a thinner slice gets no label inside (with "auto" it goes outside) |
centerLabel, centerSubLabel |
null |
donut: a text in the middle (a string, or (total, series) => text) |
explode |
6 |
pixels a slice moves out on hover and when selected; 0 never |
selectable |
true |
a click selects a slice (it stays out); event selectionChange |
gradient |
null |
a radial gradient: full at the edge, lighter towards the middle, see gradients |
The legend shows one item per slice; a click hides or shows that slice, and the others share the whole again
(event sliceToggle). Rings: give each pie series its own innerRadius / outerRadius, e.g. 0.32–0.62 and
0.65–1, and legend: false on the series whose slices should not be in the legend.
#Gauge
One value on a scale along an arc: a score, a percentage, a KPI.
const score = new Plotissimo.GaugeChart("#score", {
series: [{
value: 72, unit: "%", label: "ValuechainScore",
bands: [
{ from: 0, to: 50, color: "#ef4444", label: "Low" },
{ from: 50, to: 75, color: "#f59e0b", label: "Medium" },
{ from: 75, to: 100, color: "#10b981", label: "High" },
],
target: 85,
}],
});
score.setValue(80);
| Option | Default | Meaning |
|---|---|---|
value |
null |
the value shown (null: "–") |
min, max |
0, 100 |
the scale; values outside it stop at its ends |
startAngle, endAngle |
-120, 120 |
degrees, 0 at 12 o'clock; -90 / 90 a half circle, 0 / 360 a full ring. The shape is fitted to the chart |
innerRadius, outerRadius |
0.72, 1 |
the track, as fractions of the radius; several gauge series nest as rings |
rounded |
true |
round ends of the track and the value arc |
bands |
[] |
[{from, to, color, label}]: coloured ranges; the value arc takes the colour of the band its value is in; labelled bands are the legend items |
bandPosition |
auto | "outside" (a thin ring around the track; the default with a value arc, so the arc does not cover the bands) or "track" (on the track; the default with only a needle) |
bandWidth |
0.07 |
the outside ring's width, as a fraction of the radius |
bandOpacity |
1 |
the bands' opacity, e.g. 0.25 for light bands on the track |
valueArc |
true |
the value as an arc from min |
needle |
false |
a needle pointing at the value (the value text moves under its hub on a half circle) |
target |
null |
a marker across the track at this value, with "Target: …" on hover |
ticks |
{count: 5, minor: 0, labels: true} |
major ticks at a nice step near (max − min) / count (or step), minor ticks between them, labels; false: none |
format |
automatic | (value) => text for the value and the tick labels |
unit |
"" |
after the value, e.g. "%" |
label |
"" |
under the value |
showValue |
true |
the value in the middle |
gradient |
null |
the value arc lighter at its start, see gradients |
color |
palette | the value arc's colour when there are no bands |
chart.setValue(value, index) changes the value of a gauge (the first by default) and redraws. A click on a gauge
gives the part gauge with {value, band}, also for popups. Several gauges side by side, like KPI
tiles, are separate charts in a CSS grid (see examples/gauge.html).
#Bullet chart
KPIs as rows, after Stephen Few's design: ranges in the background (e.g. poor / fair / good), the value as a bar, the target as a line and an earlier value (e.g. last year) as a thin dark bar on top.
new Plotissimo.BulletChart("#kpis", {
scales: { x: { max: 100 } },
series: [{
ranges: [50, 75, 100], // or [{to: 50, color: "#fecaca", label: "Poor"}, ...]
labels: true, unit: "%",
data: [
{ label: "Renewable energy", value: 62, target: 75, previous: 48 },
["Women in management", 38, 40], // [label, value, target]
],
}],
});
Data: {label, value, target, previous, ranges, color, className, ...} or [label, value, target]. ranges on a
row replaces the series' ranges for that row.
| Option | Default | Meaning |
|---|---|---|
ranges |
[] |
the ends of the ranges from the lowest: numbers (greys from the theme, the lowest darkest) or {to, color, label}; labelled ranges are the legend items |
orientation |
"horizontal" |
"vertical": columns; then use scales: {x: {type: "band"}, y: {type: "linear", includeZero: true, reverse: false}} |
barSize |
0.36 |
the value bar's thickness, as a fraction of the row |
targetSize |
0.72 |
the target line's length, as a fraction of the row |
labels |
false |
true: the value after the bar |
format, unit |
(value, datum) => text; unit after the value (labels and hover text) |
|
color |
palette | the value bar's colour |
Each row shows "label: value, target …" on hover; a click gives the part bullet with {datum, value, target}.
In a table: one small BulletChart per row with rowHeight: null, a small height, and the axes hidden (see
examples/bullet.html).
#Sparkline
A small line without axes, for tables and KPI tiles.
new Plotissimo.SparklineChart(cell, {
series: [{ data: [[1, 82], [2, 79], [3, 85], [4, 77], [5, 74]] }],
});
new Plotissimo.SparklineChart(tile, {
width: 200, height: 44, responsive: true, // fill a tile's width
plotArea: { fills: [{ y0: 2.5, y1: 4, color: "#94a3b8", opacity: 0.2 }] }, // a normal range
series: [{ area: true, points: "extremes", data: [...] }],
});
The preset: 120 × 32 pixels, responsive: false (the same size in every table cell), no axes, legend, title or
backgrounds, scales without rounding, and through seriesDefaults a 1.5 px line with only the last point marked
(filled). Every line option works (area, points, lineStyle, color, ...). Bars: a series with
type: "bar" and scales: { x: { type: "band" } }.
#Radar chart
Values per category on spokes around a centre: scores per category, a company against its sector.
new Plotissimo.RadarChart("#scores", {
radar: { max: 100, ticks: 4 },
series: [
{ name: "Your company", data: [["Identity", 92], ["IT", 64], ["ESG", 71], ["Financial", 85]] },
{ name: "Sector average", area: false, points: false, lineStyle: "-", color: "#64748b",
data: [["Identity", 80], ["IT", 70], ["ESG", 60], ["Financial", 75]] },
],
});
Data: [category, value] or {category (or label), value, color, ...}. All radar series of a chart share the
categories (in the order they appear, or radar.categories), the scale and the grid; a series without a value for
a category has its point at the centre there.
Chart option radar
| Option | Default | Meaning |
|---|---|---|
min, max |
0, from the data |
the scale from the centre to the outer ring |
ticks |
4 |
about this many rings (a nice step) |
shape |
"polygon" |
the grid: "polygon" or "circle" |
tickLabels |
true |
the ring values, between the first two spokes |
format |
automatic | (value) => text for the tick labels, value labels and hover text |
categories |
from the data | a fixed list and order of the spokes |
startAngle |
0 |
degrees: where the first spoke points (0 = 12 o'clock) |
Series options: area (fill, default true), points (markers, true), marker, markerSize (6),
lineWidth, lineStyle (e.g. "-" for a benchmark), labels (the value next to each point), color. Each
point shows "Series – Category: value" on hover; a click gives the part point with {category, value}; the
category names are the plot area's part category.
#Slope chart
Per item a line between its values at two (or more) moments: what got better, what got worse.
new Plotissimo.SlopeChart("#kpis", {
series: [{
columns: ["2025", "2026"], unit: "%",
data: [
["Renewable energy", 48, 62], // [label, value, value, ...]
{ label: "Staff turnover", values: [12, 15], lowerIsBetter: true },
],
}],
});
Data: [label, value, value, …] or {label, values, lowerIsBetter, color, className, ...}.
| Option | Default | Meaning |
|---|---|---|
columns |
"1", "2", … |
the names of the moments, shown above the columns |
colorBy |
"direction" |
"direction": better green, worse red, unchanged grey (up is better, down for items with lowerIsBetter); "palette": a colour per item, with legend items |
labels |
true |
name and value at the first and last column (pushed apart so they do not overlap), the value at the columns between |
format, unit |
(value, datum) => text; unit after the value |
|
markerSize |
7 |
the dots at the values |
The chart keeps room left and right for the end labels and on top for the column names. Hovering (or focusing) a
line fades the others; each line shows its values on hover; a click gives the part item with
{datum, change, direction, verdict}.
#Heat map
A grid of cells, each coloured by its value: a risk matrix, energy per site and month, change against last year.
new Plotissimo.HeatmapChart("#risks", {
scales: { y: { type: "band", paddingInner: 0, paddingOuter: 0, reverse: true, categories: ["5 Severe", "4 Major", "3 Moderate", "2 Minor", "1 Negligible"] } },
series: [{
labels: true,
bins: [
{ to: 4, color: "#22c55e", label: "Low" }, { to: 9, color: "#facc15", label: "Medium" },
{ to: 15, color: "#f97316", label: "High" }, { to: 25, color: "#dc2626", label: "Critical" },
],
data: [["3 Possible", "4 Major", 12], ["1 Rare", "5 Severe", 5]], // [column, row, value]
}],
});
Data: [column, row, value] or {x, y, value, label, color, className, ...}. Columns and rows are in the order
they appear (or scales.x.categories / scales.y.categories); the first row is at the top.
| Option | Default | Meaning |
|---|---|---|
colors |
"blues" |
the colour scale: "blues", "greens", "reds", "risk" (green – yellow – red), "diverging" (blue – white – red), or an array of "#rrggbb" colours from low to high (names such as "red" cannot be mixed) |
min, max |
from the data | the ends of the colour scale |
mid |
halfway | a diverging scale's middle value (gets the middle colour), e.g. 0 for a change |
bins |
null |
classes instead of a continuous scale: [{to, color, label}] from the lowest; a value gets the first class whose to it does not exceed. The classes are the legend items |
labels |
false |
true: the value (or the cell's label) in each cell that is wide enough, dark or white by the cell's colour |
format, unit |
(value, datum) => text; unit after the value |
|
gap |
2 |
pixels between the cells |
cornerRadius |
2 |
rounded corners in pixels |
emptyColor |
null |
a colour for cells without a value (default: no cell) |
The legend shows the colour scale as a bar from its low to its high end, or the classes. Each cell shows
"column · row: value (class)" on hover; a click gives the part cell with {datum, value, color, bin}, e.g. for a
popup with the risks of that cell (see examples/heatmap.html).
#Sunburst
A tree as rings around a centre: a company with its suppliers and their suppliers, emissions by scope and category.
new Plotissimo.SunburstChart("#chain", {
series: [{
data: { label: "Acme B.V.", color: "#16a34a", children: [
{ label: "Steel Works", color: "#f59e0b", children: [{ label: "Ore Mining", color: "#dc2626" }] },
{ label: "PlastiCo", color: "#16a34a" },
] },
}],
popup: (c) => ({ title: c.datum.datum.label, content: "…" }),
});
Data: a tree of nodes {label, value, color, shortLabel, textColor, id, className, children: [...]}: one object
(its root is the centre) or an array of main branches (with root as the centre, or a hole without one). A leaf's
size is its value (1 without one), a branch's the sum of its children.
| Option | Default | Meaning |
|---|---|---|
layout |
"nested" |
"nested": each node within its parent's angle, sized by value; "even": every ring divided evenly over its nodes |
levels |
null |
data per level without parents, [[level 1 nodes], [level 2 nodes], …] with root as the centre (the even layout) |
root |
null |
the centre for levels or an array as data, e.g. {label: "Acme", color: "#1e3a8a"} |
startAngle, endAngle |
0, 360 |
degrees; e.g. -90 / 90 and 90 / 270 for two halves around one centre |
centerSize |
1 |
the centre's radius in ring widths |
showRoot |
true |
draw the centre; false keeps its room (for the second of two halves around one centre) |
innerRadius |
0.15 |
without a root: the hole, as a fraction of the radius |
ringGap, padAngle |
1.5, 0 |
pixels between rings, degrees between segments |
labels |
"auto" |
"auto" (horizontal when it fits, else along the radius, else only on hover), "horizontal", "radial", false |
labelFormat |
(node) => text; default the node's shortLabel or label |
|
lighten |
22 |
% each level lightens its branch's colour (towards the background); a node's own color is kept |
area |
null |
the series' part of the chart area shaded, with a label in its corner: {label: "Customer Chain"}, {color, label, labelPosition: "top-left" | "top-right" | "bottom-left" | "bottom-right"} or true (only the shade); the label goes top or bottom by where the part lies; color: "transparent" for a label without a shade |
zoom |
"auto" |
a click on a segment with children zooms into it (it becomes the centre), the centre zooms out; "auto": only without a popup option; never with data per level (levels has no parents) |
Colours: each main branch gets the next palette colour, deeper levels a lighter shade of it; text is dark or white
by its segment's colour. Each segment shows its path ("Steel Works › Ore Mining") and value on hover; a click gives
the part segment with {datum, key, depth, value, path} (and center); events branchToggle (legend) and zoom.
chart.resetZoom() zooms out. Customers and suppliers around one company: two series with layout: "even", the
same root, startAngle: -90, endAngle: 90 and startAngle: 90, endAngle: 270 (showRoot: false on the second),
with area: {label: "Customer Chain"} and area: {label: "Supply Chain", color: "transparent"};
see examples/sunburst.html.
#Waterfall
How a starting value becomes an end value: the emissions of 2025, the changes per cause, the emissions of 2026; or revenue, costs and the result. Each step floats from the running total before it to the running total after it; totals stand on zero.
new Plotissimo.WaterfallChart("#bridge", {
axes: { left: { title: "Emissions", unit: "t CO₂e" } },
series: [{
colors: { increase: "var(--pl-waterfall-decrease)", decrease: "var(--pl-waterfall-increase)" }, // more is worse
data: [
{ label: "2025", value: 1820, total: true }, // a starting point: a total with a value
["Green power", -140], ["Growth", 120], ["New site", 45],
{ label: "2026", total: true }, // the running total so far
],
}],
});
Data: [label, value] or {label, value, total, color}. An item with total: true is a bar from zero: without a
value it shows the running total so far (a subtotal or the end), with a value it sets the running total (a start).
| Option | Default | Description |
|---|---|---|
colors |
{increase, decrease, total} all null |
colours per kind; null takes the theme's --pl-waterfall-increase (green), -decrease (red), -total (slate) |
legendNames |
{increase: "Increase", decrease: "Decrease", total: "Total"} |
the legend's names; the legend only explains the colours (it does not hide anything) |
connectors |
true |
a dashed line from the end of each bar to the start of the next |
labels |
true |
the change above a rising bar and below a falling one (+120, −80), a total inside its bar |
format |
null |
(value, datum, kind) => text |
barPadding |
0.25 |
space between the bars, as a fraction of a category |
cornerRadius |
0 |
rounded corners in pixels |
gradient |
null |
as bars: true, "subtle", "strong" |
Events and popups: part "bar" with {datum, category, value (the change), from, to, kind}.
#Limit diagram
The capacity of every link of a process chain, in flow order: a production station (inflow, pumps, separation, export), a Power-to-X chain (power supply, electrolysers, compression, synthesis, storage), a supply chain. The lowest capacity is the capacity of the whole system, the IPSC (Integrated Production System Capacity): a line across all links, with the link that sets it (the bottleneck) outlined. Level lines show for instance the potential and the actual production; arrows on the right measure the gaps between neighbouring lines.
new Plotissimo.LimitDiagram("#chain", {
axes: { left: { title: "Capacity", unit: "t/d" } },
series: [{
unit: "t/d",
sources: ["Line A", "Line B"], // the stacked parts of each link
levels: [
{ label: "Demand", value: 520, lineStyle: "..." },
{ label: "Produced", value: 300, lineStyle: "--", color: "#0f766e" },
],
data: [
{ label: "Power supply", values: [420, 260] },
{ label: "Electrolysers", values: [240, 240], planned: 600, actual: 330, note: "A third stack planned" },
{ label: "Compression", values: [220, 180], actual: 320 }, // the bottleneck: IPSC 400
{ label: "Synthesis", values: [450], other: [{ label: "Test runs", value: 60 }] },
["Storage and export", 580],
],
}],
});
Data: [label, value] or {label, value, values, other, actual, planned, note, colors}:
valuethe capacity for one source, orvaluesthe capacity per source (stacked in the order ofsources);other[{label, value, color}]: other uses of the same equipment (e.g. water re-injection on export pumps), stacked on top; they are not part of the capacity;actualthe throughput now, a narrow bar inside the link;plannedthe capacity after planned changes, a dashed outline; when it moves the limit, a dashed line shows the IPSC after the changes;notewhat limits the link (hover text and data table);colorscolours per source for this link.
| Option | Default | Description |
|---|---|---|
sources |
[] |
names of the stacked parts of each link, e.g. two fields or two trains (the legend); their colours come from the palette |
unit |
"" |
after the values in the line labels, the description and the data table, e.g. "m³/d" |
limit |
true |
the IPSC line at the lowest capacity: true, false, or {label: "IPSC", plannedLabel: "IPSC planned"} for other names |
levels |
[] |
lines across the chart: [{label, value, lineStyle, color, className}], e.g. the potential and the actual production |
gaps |
true |
an arrow on the right between each pair of neighbouring lines (levels and IPSC) with the difference and its share of the upper line, e.g. −1,400 (10.4 %) |
flow |
true |
small arrows between the links, just above the axis: the direction of the flow |
labels |
true |
the capacity above each link (the bottleneck's in the IPSC colour), the value inside segments that are big enough |
format |
null |
(value, datum, kind) => text, kind "capacity", "segment", "actual", "planned", "line" or "gap"; default: grouped thousands (13,400) |
legendNames |
{actual: "Actual", planned: "Planned capacity"} |
the legend's names for the actual bars and the planned outlines; the legend only explains (it does not hide anything) |
barPadding |
0.4 |
space between the links, as a fraction of a category |
cornerRadius |
0 |
rounded corners in pixels |
The line labels sit on the left and the gap arrows on the right, in room the plot area keeps free for them. The
description and the data table name the IPSC, the bottleneck and the headroom of every other link. Colours of the
theme: --pl-limit-ipsc (the IPSC line and bottleneck), --pl-limit-level (level lines), --pl-limit-other,
--pl-limit-actual.
Events and popups: part "segment" with {datum, category, value, kind ("source" or "other"), source, capacity},
"actual" and "planned" with {datum, category, value}, "line" with {kind ("level", "limit" or "limit-planned"), label, value}.
#Sankey diagram
Flows between nodes as bands as wide as the flow: energy from sources to uses, materials through a value chain, emissions from activities to scopes. Nodes stand in columns from left to right; each node is as tall as the larger of what flows in and what flows out.
new Plotissimo.SankeyChart("#energy", {
series: [{
unit: "MWh",
nodes: [{ id: "grid", label: "Grid electricity" }, { id: "loss", label: "Losses", color: "#94a3b8" }],
links: [
{ source: "grid", target: "Electricity", value: 820 }, // ids or labels; unknown names become nodes
{ source: "Electricity", target: "Production", value: 690 },
{ source: "Electricity", target: "loss", value: 30 },
],
}],
popup: (c) => (c.part === "link" ? { title: `${c.datum.source.label} → ${c.datum.target.label}`, content: `${c.datum.value} MWh` } : null),
});
Data: links: [{source, target, value, color}] and optionally nodes: [{id, label, color, column, className}]. A
link's source and target are a node's id or label; names that are no node yet become one. A link that would
make a cycle is left out, with a warning in the console.
| Option | Default | Description |
|---|---|---|
nodeWidth |
14 |
the width of a node in pixels |
nodeGap |
12 |
pixels between the nodes of a column |
align |
"justify" |
"justify": nodes without outgoing flows in the last column; "left": every node as far left as its longest path from a source. A node's column (0, 1, …) wins |
iterations |
8 |
passes that move nodes towards the nodes they connect with, so fewer flows cross |
linkColor |
"source" |
"source", "target", "gradient" (from the source's to the target's colour), "neutral" (--pl-sankey-link), or a CSS colour; a link's own color wins |
labels |
true |
the node names beside the nodes: right of them in the left half, left of them in the right half |
showValues |
true |
the node's value after its name |
format |
null |
(value) => text |
unit |
"" |
after the values, e.g. "MWh" |
Nodes take the palette's colours in order (their own color wins). Hovering or focusing a node highlights its flows
(class pl-sankey-active, the others fade). Events and popups: part "node" with {datum, value, in, out} and part
"link" with {datum, source, target, value}.
#Histogram
How many values fall in each range, e.g. the distribution of company scores. The data are the raw values.
new Plotissimo.HistogramChart("#scores", {
axes: { bottom: { title: "Score" }, left: { title: "Suppliers" } },
series: [{ data: [72, 64, 58, 91, 45 /* … */], binWidth: 10, range: [0, 100], labels: true }],
});
| Option | Default | Description |
|---|---|---|
bins |
"auto" |
the number of bins (exactly that many, from the smallest to the largest value), or "auto" (Sturges' rule, rounded to a nice bin width on whole multiples) |
binWidth |
null |
a fixed bin width; wins over bins |
range |
null |
[min, max] of the bins; default the data's, widened to whole bin widths. The last bin includes its upper edge |
mode |
"count" |
"count" or "percent" (of all values) |
labels |
false |
the count above each bar |
gap, cornerRadius |
1, 0 |
pixels between the bars, rounded corners |
Data: numbers, or objects with a value. Events and popups: part "bin" with {x0, x1, count, value, values}.
#Box plot
The spread of values per group: the box from the first to the third quartile with the median, whiskers to the furthest values within 1.5 × the box's height (IQR), the values beyond as outliers.
new Plotissimo.BoxPlotChart("#sectors", {
series: [{ mean: true, data: [
{ label: "Construction", values: [58, 61, 44, 72 /* … */] },
{ label: "Food", min: 52, q1: 66, median: 71, q3: 75, max: 86, outliers: [32] }, // statistics of your own
] }],
});
| Option | Default | Description |
|---|---|---|
whisker |
1.5 |
whiskers reach the furthest value within this many IQRs from the box; null: the minimum and maximum |
outliers |
true |
draw the values beyond the whiskers |
mean |
false |
a ◆ at the mean |
points |
false |
every value as a dot beside the box (in a fixed pattern, the same on every draw) |
boxPadding |
0.4 |
the space around a box, as a fraction of a group |
Quartiles are interpolated linearly, as in spreadsheets (Plotissimo.quantile(sorted, q)). Events and popups: part
"box" with {label, min, q1, median, q3, max, mean, outliers, count}.
#Funnel
Stages that narrow down, e.g. suppliers invited → responded → verified → compliant.
new Plotissimo.FunnelChart("#assessment", {
series: [{ data: [["Invited", 240], ["Responded", 168], ["Verified", 86], ["Compliant", 64]] }],
});
| Option | Default | Description |
|---|---|---|
shape |
"funnel" |
"funnel": each stage narrows to the next one's width; "bars": straight centred bars |
percent |
"first" |
the share after the value: of the "first" stage, of the "previous" stage, or false |
colorBy |
"stage" |
a palette colour per stage, or "series": the series colour, lighter towards the end; a stage's color wins |
labels |
"inside" |
"inside" (beside the stage when it does not fit), "right", or false |
gap, minWidth, neck |
4, 24, 0 |
pixels between stages; the narrowest a stage is drawn, in pixels; the last stage's narrowing |
format |
null |
(value) => text |
Events and popups: part "stage" with {label, value, share}.
#Treemap
A tree as nested rectangles sized by value, e.g. emissions by scope and category. The data are as for the sunburst: one tree or an array of main branches.
new Plotissimo.TreemapChart("#emissions", {
series: [{ unit: "t", data: [
{ label: "Scope 1", children: [{ label: "Gas", value: 310 }, { label: "Vehicles", value: 160 }] },
{ label: "Scope 3", children: [{ label: "Purchased goods", children: [{ label: "Steel", value: 420 }] }] },
] }],
});
treemap.resetZoom();
| Option | Default | Description |
|---|---|---|
depth |
2 |
levels shown below the root (or the branch zoomed into); deeper levels count in their parent |
header |
20 |
the height of a branch's header with its name and value (0: none) |
padding, gap |
2, 1 |
pixels around a branch's children; between tiles |
lighten |
18 |
per level, how much lighter a branch's colour gets (percent towards the background) |
labels, showValues |
true, true |
name and value in tiles that are big enough (cut with "…") |
format, unit |
null, "" |
how values are written |
zoom |
"auto" |
a click on a branch zooms into it, the header above zooms out; "auto": only without a popup option |
Tiles are "squarified": as close to squares as the space allows, largest first (Plotissimo.squarify(items, rect)).
Main branches take the palette's colours in the order of the data, so a branch keeps its colour when zoomed into.
Events and popups: parts "branch", "leaf" and "back"; the event zoom with {focus}.
#Score card
A few scores at a glance: nested half rings, one per score, with a panel beside them that names each score and shows
its value in the colour of its band (low red, medium orange, high green). The first score is the outer ring; a score
with main: true gets a thicker ring and larger type, e.g. an overall score around its parts.
new Plotissimo.ScoreCardChart("#score", {
series: [{
data: [
{ label: "ValuechainScore™", value: 68, main: true },
{ label: "Company Score", value: 82, flag: "2 red flags" }, // a flag beside the name, the text on hover
{ label: "Supply Chain Score", value: null }, // no value: no ring, "N/A" in the panel
],
footer: "Acme Logistics B.V.",
image: "/images/logo.png", // in the middle of the rings
}],
});
Data: {label, value, main, flag, color, className} or [label, value]. flag is true or the text shown
on hover. A color gives that score its own colour instead of its band's.
| Option | Default | Meaning |
|---|---|---|
min, max |
0, 100 |
the scale of the scores; values outside it stop at its ends |
unit |
"%" |
after each value |
format |
a whole number | (value) => text |
missingText |
"N/A" |
shown for a score without a value |
bands |
low < 50, medium < 75, high | [{from, to, label, color, className}]; a value takes the last band it falls in. The default bands use the classes pl-score-low, pl-score-medium, pl-score-high and the theme's --pl-score-low, --pl-score-medium, --pl-score-high |
startAngle, endAngle |
-90, 90 |
degrees, 0 at 12 o'clock: a half circle |
ringWidth |
0.13 |
a ring's thickness, as a fraction of the radius |
mainRingWidth |
0.26 |
the thickness of a score with main: true |
ringGap |
0.07 |
the space between two rings, as a fraction of the radius |
rounded |
true |
round ends of the rings |
panel |
true |
the names and values beside the rings |
panelWidth |
0.55 |
the panel's share of the width |
footer |
"" |
a line at the bottom of the panel, e.g. the company name |
image |
null |
an image in the middle: a URL, or {href, size, alt} (size a fraction of the inner ring's radius, default 0.85) |
icon |
null |
an icon in the middle from SVG path data: {paths, viewBox, size, label, className}; paths is one d string or a list of them (or of {d, fillRule}), viewBox default "0 0 16 16", size as for image; it takes the theme's muted colour (CSS --pl-scorecard-icon) |
rangeLabels |
true |
min and max (e.g. 0% and 100%) under the ends of the outer ring |
Other boundaries, e.g. low below 51: bands: [{ to: 51, label: "Low", className: "pl-score-low" }, { from: 51, to: 75, label: "Medium", className: "pl-score-medium" }, { from: 75, label: "High", className: "pl-score-high" }].
Several score cards, e.g. one per category with its own icon, are separate charts side by side in a CSS grid,
like the detail cards in examples/scorecard.html. A card with only its main score shows a single ring (e.g. a
sector average without company and supply chain scores).
A click on a ring or a row of the panel gives the part score with {datum, index, value, band}, also for
popups. The rings draw themselves in on the first draw (animations).
#11. Materiality matrix
A double materiality matrix (CSRD / ESRS): financial materiality on x, impact materiality on y, a threshold that splits the plot area into four quadrants, and topics coloured by category.
const matrix = new Plotissimo.MaterialityMatrix("#dma", {
title: { text: "Materiality matrix" },
threshold: 4,
series: [{
name: "Topics",
data: [
{ category: "E", shortLabel: "E1", label: "E1 Climate change", x: 7.5, y: 8.2, subPoints: [
{ shortLabel: "E1.1", label: "Climate change adaptation", x: 6.5, y: 7 },
{ shortLabel: "E1.2", label: "Climate change mitigation", x: 8.2, y: 8.8 },
] },
{ category: "S", shortLabel: "S1", label: "S1 Own workforce", x: 6.2, y: 7.4 },
{ category: "G", shortLabel: "G1", label: "G1 Business conduct", x: 6.9, y: 4.6 },
],
}],
});
matrix.setThreshold(5);
Chart options
| Option | Default | Meaning |
|---|---|---|
threshold |
4 |
a number for both axes, or {x, y} |
thresholdLines |
true |
dashed lines at the threshold |
quadrants.show |
true |
colour the quadrants |
quadrants.labels |
true |
the quadrant names in their corner |
quadrants.notMaterial, .financial, .impact, .double |
theme colours | per quadrant {label, color, opacity, className}; without color the theme decides (--pl-quadrant-*, see themes) |
The scales run from 0 to 9; change them with scales: { x: { max: 5 }, y: { max: 5 } }. Your own plotArea.fills
and plotArea.lines are added after the quadrants.
Topics (the data) have x, y, category, shortLabel (inside the marker), label (the full name), an
optional id and optional subPoints (the same fields).
Series options
| Option | Default | Meaning |
|---|---|---|
categories |
E Environment, S Social, G Governance, O Other | [{key, name, color}]; a topic with an unknown category gets the last one |
radius, subRadius |
11, 8 |
marker sizes of topics and sub topics |
labels |
"hover" |
the full label: "hover", "always", false |
duplicates |
"branch" |
topics with the same scores: "branch" (each its own marker on a short line from a small hub at the real position) or "group" (one marker "#n" with the list of names) |
branchDistance |
28 |
pixels from the hub to a branched marker (more when needed) |
hubRadius |
5 |
|
countPrefix |
"#" |
the text before the number of a group marker |
Behaviour
- Hover a topic for its full name (with
labels: "hover"). - A topic with sub topics has a thick border; a click opens them (dashed lines to smaller markers), a second click closes them.
- A click on a topic without sub topics, a group marker or a sub topic keeps its label visible.
- A click on a legend item hides or shows that category.
#12. Gantt chart
Tasks as bars on rows along a time axis: project plans, validity periods (certificates, licences, contracts), schedules.
const plan = new Plotissimo.GanttChart("#plan", {
title: { text: "VSME report 2026" },
today: true,
series: [{
data: [
{ row: "Kick-off", start: "2026-09-01", milestone: true, label: "Kick-off" },
{ row: "Collect data", start: "2026-09-02", end: "2026-10-15", label: "Collect data", progress: 1 },
{ row: "Energy (B3)", start: "2026-10-01", end: "2026-11-20", label: "Energy", progress: 0.7 },
["Review", "2026-12-07", "2027-01-08", "Review"], // [row, start, end, label]
],
}],
});
Tasks (the data):
| Field | Meaning |
|---|---|
row |
the row; rows appear in the order of the data (or set scales.y.categories); several tasks can share a row |
start, end |
dates (a Date, a timestamp or a string such as "2026-03-31"); a missing start or end runs the bar to the edge of the plot area (e.g. a missing certificate over the whole row) |
label |
the text on (or next to) the bar |
status |
a key of the series' statuses: its colour, dashed border and legend item |
group |
a key of the series' groups (or any name): the rows of a group stay together under a header row with the group's icon and name, with a divider line between groups |
progress |
0–1: the done part of the bar is darker |
id |
the task's id, for links and parent (and for your own use, e.g. a database id) |
parent |
the id of its summary task: a task that other tasks name as parent is a summary, see below |
collapsed |
true: a summary task that starts collapsed |
milestone |
true: a diamond at start instead of a bar |
color, textColor, className |
this task only |
| any other field | kept, for your events and popups (e.g. an id) |
Series options
| Option | Default | Meaning |
|---|---|---|
statuses |
null |
{key: {label, color, textColor, dashed, className}}: the look per status; the legend then shows one item per status in the data, and a click on one hides / shows those tasks |
groups |
null |
{key: {label, icon, color, className}}: the name, icon and colour per group; icon is {paths, viewBox} with SVG path data (one d string or a list of them, or of {d, fillRule}; viewBox default "0 0 16 16"), drawn as paths in the group's color (or the theme's muted colour) |
groupHeaders |
true |
a header row with the group's icon and name above the rows of each group (not with fixed scales.y.categories) |
rowIcons |
true |
the group's icon at the start of each row, in a column the plot area keeps free (bars never cover it) |
iconSize |
16 |
the icons' size in pixels |
links |
null |
dependencies: [{from, to, type, lag, color, className}] or [from, to, type] with task ids; type "FS" (finish to start, the default), "SS" (start to start), "FF" (finish to finish), "SF" (start to finish); lag in days (negative: lead). An arrow from the predecessor's edge to the successor's, under the bars; a link whose condition the dates do not meet is red and dashed (class pl-gantt-link-conflict) |
labels |
"auto" |
"inside" (cut off with "…"), "outside" (after the bar), "auto" (inside when it fits, otherwise after the bar), false. With bars that overlap in a row (an old and a renewed certificate), a label stops where a later bar covers its bar, and an outside label never lies over another bar (without room it is left out; the hover text has the name) |
labelPadding |
8 |
pixels between the bar's edge and its label |
cornerRadius |
4 |
rounded corners in pixels; "full" for round ends |
milestoneSize |
80 % of the row | the diamond's size in pixels |
minWidth |
2 |
the smallest bar in pixels, so very short tasks stay visible |
tooltip |
true |
on hover: the task's name, dates and status, e.g. "ISO 9001 · 1 Mar 2026 – 28 Feb 2027 · Valid" (also the screen reader name) |
dateFormat |
null |
(date) => text for the hover text; default "1 Mar 2026" in the x scale's locale |
The text on a bar is dark on light colours and white on dark ones (in the browser); textColor on a status or task
sets it yourself.
Chart options (GanttChart)
| Option | Default | Meaning |
|---|---|---|
rowHeight |
36 |
pixels per row: the chart's height follows the number of rows; null keeps height |
filter |
false |
true: a filter bar above the chart (HTML): a search field, a chip per status and per group (pressed chips: only those; none: all), the number of tasks shown and Clear. {search, statuses, groups, placeholder} turns parts off or changes the placeholder |
today |
true |
a line at today's date with a "Today" badge above the plot area (the date on hover): true, a date, {date, label, labelPosition, shadePast} (shadePast: true greys the past; labelPosition: "inside" puts the label in the plot area), or false |
The preset puts the first row at the top, stripes the rows, shows the rows' names on the left axis (hide them with
axes: { left: { visible: false } } when the labels are on the bars) and months or quarters on the bottom axis. A
time axis on top as well: axes: { top: { visible: true, scale: "x" } }.
Certificate validity (as in ValuechainScore):
new Plotissimo.GanttChart("#certificates", {
today: { shadePast: true },
axes: { left: { visible: false } },
series: [{
cornerRadius: "full",
statuses: {
valid: { label: "Valid", color: "mediumaquamarine" },
progress: { label: "In progress", color: "mediumaquamarine", dashed: true },
expired: { label: "Expired", color: "lightcoral" },
missing: { label: "Missing", color: "#dc2626" },
},
data: [
{ row: "ISO 9001", start: "2025-03-01", end: "2028-03-01", status: "valid", label: "ISO 9001", id: 12 },
{ row: "ISO 27001", status: "missing", label: "ISO 27001 (missing)", certificateTypeId: 7 },
],
}],
popup: (c) => (c.part === "task" ? { title: c.datum.datum.row, content: "…", actions: [...] } : null),
});
Filtering: chart.filter({text, statuses, groups}) shows only the tasks with one of the statuses, one of the
groups and every word of text in their label, row, group or status; chart.filter((task) => …) uses your own
test; chart.filter(null) shows all again. Rows without a matching task close up (the chart gets lower), the time
axis stays the same. The filter bar does the same, and shows a filter set from code. The chart emits filterChange
with {filter}. A click on a group's header row gives the part group with {group, label}.
Summary tasks: a task that other tasks name as parent is a summary task (at any depth). Its own start,
end and progress are not used: its bar runs from the first to the last date of its tasks, and its progress is
theirs, weighted by duration. It is drawn as a thin bar with points down at both ends, its label after it; its hover
text adds the number of tasks. Before each summary row a toggle (▾ / ▸, one step to the right per level) collapses or
expands it: its tasks' rows close up. The toggle works with a click, and with Tab and Enter or Space. In code:
chart.collapse(id), chart.expand(id) (an id or a list), chart.collapseAll(), chart.expandAll(); the chart
emits taskToggle with {id, collapsed}; a click on a toggle gives the part toggle. With a filter, a summary stays
when one of its tasks matches. Put the tasks after their summary in the data: the rows follow the data's order. The
colour comes from --pl-gantt-summary (default the text colour) or the summary's status or color.
Dependencies (links): the arrow leaves the predecessor at its end (FS, FF) or start (SS, SF) and enters the
successor at its start (FS, SS) or end (FF, SF), in elbows like a project plan; when the successor's edge lies behind
the way out, the arrow runs along the row boundary around it. Milestones and open-ended bars link at their edges. A
link to a task that is filtered out or hidden is left out. The hover text says e.g. "Collect data → Energy (start to
start, +14 days)"; a click gives the part link with {link, from, to, type, lag, met}. The colour comes from
--pl-gantt-link (default the muted text colour) and --pl-gantt-conflict (default red), or a link's own color.
Plotissimo draws the plan as given: it does not move tasks to meet their links (no auto-scheduling).
chart.setToday(date) moves the today line. Click a task for its popup (see popups); with a popup,
tasks can also be reached with Tab and opened with Enter.
#13. Changing a chart after drawing
| Method | Does |
|---|---|
chart.update(options) |
change chart, title, legend, axes, plot area or scale options and redraw |
chart.addSeries(config) |
add a series (returns it) and redraw |
chart.removeSeries(series) |
remove a series and redraw |
chart.series[i].set(options) then chart.draw() |
change a series, e.g. new data |
chart.series[i].show() / .hide() / .toggle() |
show or hide a series |
chart.show(name) / hide(name) / toggle(name) / setVisible(name, visible) |
show or hide "title", "legend", "axis.left" (or "left"), "axis.bottom", ... |
chart.element(name) |
the element object, e.g. chart.element("legend").set({position: "bottom"}) then chart.draw() |
chart.setTheme(name) |
switch the theme |
chart.setPalette(colors) |
set the series colours (an array or a named palette: "colorblind", "blue", "blue-dark"), or null for the theme's palette again |
chart.setSize(width, height) |
change the size / proportions |
chart.draw() |
lay out and draw again |
chart.destroy() |
remove the chart and its event listeners |
matrix.setThreshold(value) |
materiality matrix only |
gantt.setToday(today) |
Gantt chart only: move or hide the today line |
gauge.setValue(value, index) |
gauge chart only: change a gauge's value |
chart.openPopup(content, {pageX, pageY}) / chart.closePopup() |
open or close a popup yourself |
chart.describe() / chart.dataTable() |
the description screen readers read / the data as tables, see accessibility |
chart.download(options) / toPNG(options) / toSVG(options) |
save or export the chart, see export |
#Animations
On the first draw bars and Gantt bars grow, lines are drawn from start to end, points, bubbles, pies, sunbursts and
gauges pop in, areas, heat map cells, treemap tiles and Sankey flows fade in, and the labels follow when the parts are
nearly in place. After a change (new data, a series hidden in the legend, update()), the parts that were there move
from their old place to their new one; the labels show again when they arrive, new parts fade in.
new Plotissimo.BarChart("#c", { animation: false, ... }); // none
new Plotissimo.BarChart("#c", { animation: { duration: 400, update: false }, ... }); // only the entrance, faster
chart.finishAnimations(); // end a running animation at once
There are no animations when the operating system asks for less motion (prefers-reduced-motion), and a chart that
only changes size (a resized window, setSize) is not animated. toSVG(), toPNG() and download() finish a
running animation first, so an export right after creating a chart shows the finished chart; for charts made only to
be exported (e.g. report images) animation: false saves the work.
chart.series[0].set({ data: newData });
chart.draw();
chart.update({ title: { text: "Energy use 2027" }, axes: { left: { unit: "GWh" } } });
#14. Events
Register handlers with chart.on(type, handler) (and remove them with chart.off(type, handler)). They keep working
after a redraw.
chart.on("series:point:click", (c) => console.log(c.datum.series.options.name, c.datum.datum));
chart.on("legend:item:click", (c) => { c.preventDefault(); /* the series is not toggled */ });
chart.on("axis.bottom:tick-label:click", (c) => console.log(c.datum.label));
Event names are <element>:<part>:<DOM event>, or <element>:<DOM event> for anywhere in the element.
| Element | Parts |
|---|---|
title |
text, subtitle |
legend |
item |
axis.bottom, axis.left, axis.top, axis.right |
line, tick, tick-label, title |
plotArea |
background, fill, fill-label, line, badge, category (radar) |
series |
point, line, area (line); bar; bubble, circle (bubble); topic, subpoint, hub, subhub (matrix); task (gantt); slice, center (pie); gauge (gauge); bullet (bullet); point, area (radar); item (slope); cell (heat map); segment, center (sunburst) |
DOM events: click, dblclick, contextmenu, mouseenter, mouseleave, mouseover, mouseout, mousemove,
mousedown, mouseup, pointerdown, pointerup, pointermove, keydown, keyup, focusin, focusout,
touchstart, touchend, wheel.
The handler's argument (c):
| Field | Meaning |
|---|---|
chart, element, part, node, event, type |
where it happened |
datum |
the data of the part, e.g. {datum, index, series} for a point or bar, {item, name, visible} for a legend item, {value, label} for a tick label, {members, category, value} for a matrix topic |
preventDefault() |
skip the built-in behaviour (legend toggle, show label, select bubble, open topic) |
stopPropagation() |
stop handlers of enclosing parts |
Chart events (no DOM event): beforeLayout, afterLayout, beforeDraw, afterDraw, visibilityChange,
seriesToggle, selectionChange (bubbles), categoryToggle, topicToggle, labelToggle (matrix), statusToggle
(gantt), sliceToggle (pie), popupOpen, popupClose.
#15. Popups
A popup is an HTML box next to the clicked part, with information, forms and buttons. Give the chart a popup
function: it receives the same context as an event handler (events) and returns the content, or
null for no popup.
const chart = new Plotissimo.GanttChart("#certificates", {
series: [...],
popup: (c) => {
if (c.part !== "task") return null; // only for tasks, not for the legend or the axes
const task = c.datum.datum;
return {
title: task.row, // text, safe for any value
content: `<div>Valid until ${Plotissimo.escapeHtml(task.end)}</div>`,
actions: [
{ label: "Go to certificate", href: `/?page=ShowCertificate&id=${task.id}` },
{ label: "Renew", onClick: (context, popup) => { renew(task); popup.close(); } },
],
};
},
});
Content can be:
| Content | Shown as |
|---|---|
{title, content, actions} |
a title (text), a body (HTML string or DOM node) and buttons: {label, href, target} gives a link, {label, onClick(context, popup)} a button |
| a string | HTML |
| a DOM node | the node itself, e.g. a <form> you built, with its own event listeners |
null |
no popup (and an open one closes) |
Security: HTML strings are inserted as they are. Put user data (names, labels) in through
Plotissimo.escapeHtml(value), as title (which is always text), or by building DOM nodes with textContent.
Behaviour: the popup opens on a click, or on Enter / Space on a focused part; it closes with its × button,
Escape, a click outside it, or a click on an empty part of the chart. It is placed next to the click and kept inside
the window. It is a <div class="plotissimo-popup"> in document.body, so the chart's container does not clip it,
and it has the chart's theme. The chart emits popupOpen and popupClose (with node and context).
The option can also be an object: popup: { content: fn, className: "my-popup" } adds your own class to the popup.
#16. Themes and styling
All colours, fonts and line styles are in plotissimo.css; the script only sets positions and class names.
Built-in themes: default, dark and minimal (no plot area background or border, very light grid).
new Plotissimo.Chart("#c", { theme: "dark", series: [...] });
chart.setTheme("minimal");
Your own theme: a theme is a set of CSS variables on .plotissimo.pl-theme-<name>. Define only what differs from
the default:
.plotissimo.pl-theme-corporate {
--pl-font: "Inter", sans-serif;
--pl-plot-bg: #f5f7fb;
--pl-color-0: #172554;
--pl-color-1: #f59e0b;
}
chart.setTheme("corporate");
| Variable | Used for |
|---|---|
--pl-font |
all text |
--pl-bg |
chart background (also the inside of line markers and the outline of data labels) |
--pl-text |
titles, legend, data labels |
--pl-muted |
subtitle, tick labels, zone labels |
--pl-plot-bg, --pl-plot-border |
plot area |
--pl-axis |
axis lines, ticks, reference lines |
--pl-grid-major, --pl-grid-minor |
gridlines |
--pl-color-0 … --pl-color-9 |
the series palette (series 11 uses colour 0 again) |
--pl-quadrant-not-material, --pl-quadrant-financial, --pl-quadrant-impact, --pl-quadrant-double |
the quadrants of the materiality matrix |
--pl-quadrant-label, --pl-threshold |
the quadrant names and the threshold lines |
#Palette from JavaScript
The palette option sets the series colours of one chart without CSS. Series without their own color take the
colours in order; a list shorter than ten colours repeats.
const chart = new Plotissimo.Chart("#c", {
palette: ["#172554", "#f59e0b", "#10b981"],
series: [{ name: "A", data: [...] }, { name: "B", data: [...] }],
});
chart.setPalette(["#0f766e", "#b45309"]); // other colours
chart.setPalette(null); // the theme's palette again
The palette is set on the chart's <svg> as the variables --pl-color-0 … --pl-color-9, so it wins over the theme:
the series keep these colours in every theme, while backgrounds, text and gridlines still follow the theme. Choose
colours that read well on the backgrounds of the themes you use.
palette: "colorblind" (or chart.setPalette("colorblind")) takes the Okabe-Ito colours, which people with the
common kinds of colour blindness (red-green, blue-yellow) can tell apart: #0072B2, #E69F00, #009E73,
#D55E00, #CC79A7, #56B4E9, #F0E442, #8C8C8C.
palette: "blue" and palette: "blue-dark" are shades of one blue, a calm look for data and technology pages:
"blue" for light backgrounds (#055494, #6291C3, #003365, #347DBD, #001638, #305B88), "blue-dark"
for dark backgrounds such as the dark theme (#A1C2F1, #267ABE, #E3EFFD, #347DBD, #B7D5FA, #72A2D8).
Every colour has at least 3:1 contrast with its background, and light and dark shades alternate so neighbouring
series differ. One hue tells only a few series apart: use them for up to five or six series, or for ordered
categories such as years; for more series, or when colour blindness matters most, use "colorblind".
Which colour wins, from strongest to weakest: a point's color, the series' color, the palette option, the
theme's palette.
The materiality matrix colours its topics by category (categories option), not with the palette.
#Effects and gradients
Effects (chart option effects, or chart.setEffects(...)) are CSS on top of any theme:
| Effect | Looks like |
|---|---|
"elevated" |
soft shadows under bars, slices, bubbles, Gantt tasks and filled markers; lines lifted a little; bars, tasks and bubbles rise a little on hover with a bigger shadow |
"glow" |
a glow in each element's own colour around lines, bars, slices, gauge arcs and markers; stronger on hover. Made for the dark theme |
new Plotissimo.BarChart("#c", { theme: "dark", effects: ["elevated", "glow"], series: [...] });
The shadow colour is the theme variable --pl-shadow (darker in the dark theme). Effects are CSS filters
(filter: drop-shadow(...)): fine for dozens of shapes, slower for many hundreds, so they are off by default. You
can add your own the same way, e.g. .plotissimo .pl-bar { filter: drop-shadow(0 2px 3px rgba(0, 0, 0, .25)); }.
Gradients (series option gradient on bar, line (area), pie and gauge series) are SVG gradients: CSS cannot fill
SVG shapes with a gradient. They use the series' colour (its palette colour follows the theme and the palette
option).
gradient |
Meaning |
|---|---|
true |
full colour fading to about half |
"subtle", "strong" |
a little / a lot of fading |
{direction, stops} |
your own: direction "down", "up", "left" or "right", the side with the full colour (a plot area zone's shade names the way it fades instead); stops [[offset, colour, opacity], ...] with colour null for the series' colour |
Bars are full at their end (also for negative and horizontal bars), areas fade out towards the bottom, pie slices are
full at the edge and lighter towards the middle, a gauge arc is lighter at its start. See examples/effects.html.
Popups are styled with .plotissimo-popup and its parts .pl-popup-title, .pl-popup-body,
.pl-popup-actions, .pl-popup-action and .pl-popup-close; they use the theme's variables.
Other styling: every part has a fixed class name (pl-title-text, pl-tick-label, pl-bar, pl-line, ...; see
class names below), so you can change anything with CSS:
.plotissimo .pl-line { stroke-width: 3; }
.plotissimo .pl-tick-label { font-size: 12px; }
#sales .pl-bar { fill-opacity: 0.85; }
You can also replace the whole stylesheet: Plotissimo.useStyleSheet("my-charts.css") loads it (or replaces the one
loaded before); call chart.draw() afterwards so the text is measured with the new fonts.
#Class names
All classes start with pl- and are part of the stable API.
| Element | Classes |
|---|---|
root <svg> |
plotissimo, pl-theme-<name>, extra className |
| chart background | pl-chart-bg |
| every element group | pl-element, pl-<kind> (pl-title, pl-legend, pl-axis, pl-plot-area), plus pl-hidden when hidden; its background rectangle pl-bg |
| title | pl-title-text, pl-subtitle-text |
| legend | pl-legend-title, pl-legend-item, pl-legend-symbol, pl-legend-label; an item of a hidden series or category pl-off |
| axis | pl-axis-bottom / -left / -top / -right, pl-axis-line, pl-tick pl-tick-major, pl-tick pl-tick-minor, pl-tick-label, pl-axis-title |
| plot area | a stripe pl-stripe (in pl-stripes); a fill pl-fill plus its own className, its label pl-fill-label; a reference line pl-ref-line, its label pl-ref-line-label, or its badge outside the plot area pl-ref-badge (pl-ref-badge-bg, pl-ref-badge-text, <className>-badge) |
| gantt | pl-gantt-task (pl-gantt-status-<status>, pl-gantt-dashed, pl-gantt-milestone, pl-gantt-open-start, pl-gantt-open-end), pl-gantt-bar, pl-gantt-progress, pl-gantt-diamond, pl-gantt-label (pl-gantt-label-inside / -outside), pl-gantt-group-divider, pl-gantt-group-header (pl-gantt-group-<group>), pl-gantt-group-icon, pl-gantt-group-label, pl-gantt-row-icon, pl-gantt-link (pl-gantt-link-fs / -ss / -ff / -sf, pl-gantt-link-conflict), pl-gantt-link-line, pl-gantt-link-arrow, pl-legend-gantt; today pl-today, the past pl-past |
| pie | pl-pie-slice (pl-selected), pl-pie-arc, pl-pie-label (pl-pie-label-inside / -outside), pl-pie-leader, pl-pie-center, pl-pie-center-label, pl-pie-center-sublabel, pl-pie-empty, pl-legend-pie |
| gauge | pl-gauge (pl-gauge-rounded), pl-gauge-track, pl-gauge-band (pl-gauge-band-outside), pl-gauge-value, pl-gauge-target, pl-gauge-tick (-major, -minor), pl-gauge-tick-label, pl-gauge-needle, pl-gauge-hub, pl-gauge-value-text, pl-gauge-label, pl-legend-gauge |
| bullet | pl-bullet, pl-bullet-range (pl-bullet-range-0 darkest … -4 lightest), pl-bullet-bar (pl-bullet-negative), pl-bullet-previous, pl-bullet-target, pl-bullet-label; legend pl-bullet-legend-<n>, pl-legend-bullet-range |
| radar | pl-radar-grid, pl-radar-ring, pl-radar-spoke, pl-radar-category, pl-radar-tick-label, pl-radar-area (pl-radar-no-fill), pl-radar-point, pl-radar-label, pl-legend-radar |
| slope | pl-slope-chart, pl-slope-column, pl-slope-column-name, pl-slope-item (pl-slope-up / -down / -flat, pl-slope-better / -worse), pl-slope-line, pl-slope-point, pl-slope-label (pl-slope-label-middle) |
| effects | on the root <svg>: pl-effects-elevated, pl-effects-glow (chart option effects); shadow colour --pl-shadow |
| heat map | pl-heatmap-cell (pl-heatmap-empty), pl-heatmap-rect, pl-heatmap-label, pl-legend-heatmap, pl-legend-heatmap-scale |
| sunburst | pl-sunburst, pl-sunburst-segment (pl-sunburst-depth-<n>, pl-sunburst-branch), pl-sunburst-arc, pl-sunburst-label, pl-sunburst-center (pl-sunburst-zoomed), pl-sunburst-center-disc, pl-sunburst-center-label, pl-sunburst-area, pl-sunburst-area-label, pl-legend-sunburst |
| popup (HTML) | plotissimo-popup, pl-theme-<name>, pl-popup-close, pl-popup-content, pl-popup-title, pl-popup-body, pl-popup-actions, pl-popup-action |
| waterfall | pl-waterfall-bar (pl-waterfall-increase / -decrease / -total), pl-waterfall-connector, pl-waterfall-label (pl-waterfall-label-inside) |
| limit diagram | pl-limit-link (pl-limit-bottleneck, pl-limit-next-bottleneck), pl-limit-segment (pl-limit-source-<n>, pl-limit-other), pl-limit-capacity, pl-limit-actual, pl-limit-planned, pl-limit-flow, pl-limit-line (pl-limit-line-level / -limit / -limit-planned), pl-limit-line-label, pl-limit-gap, pl-limit-gap-label, pl-limit-label (pl-limit-label-inside, pl-limit-capacity-label, pl-limit-bottleneck-label) |
| Sankey | pl-sankey-node, pl-sankey-rect, pl-sankey-label, pl-sankey-link; while one is in focus pl-sankey-focus and pl-sankey-active |
| histogram | pl-histogram-bar, pl-histogram-label |
| box plot | pl-boxplot, pl-boxplot-box, pl-boxplot-median, pl-boxplot-mean, pl-boxplot-whisker, pl-boxplot-cap, pl-boxplot-outlier, pl-boxplot-point |
| funnel | pl-funnel-stage, pl-funnel-shape, pl-funnel-label (pl-funnel-label-inside) |
| treemap | pl-treemap-tile (pl-treemap-leaf / pl-treemap-branch, pl-treemap-open), pl-treemap-rect, pl-treemap-header, pl-treemap-label, pl-treemap-value, pl-treemap-back |
| score card | pl-scorecard, pl-scorecard-ring (pl-scorecard-main, pl-scorecard-rounded), pl-scorecard-track, pl-scorecard-value, pl-scorecard-row, pl-scorecard-label (-main), pl-scorecard-value-text (pl-scorecard-value-main), pl-scorecard-flag, pl-scorecard-footer, pl-scorecard-range, pl-scorecard-image, pl-scorecard-icon; bands pl-score-low / -medium / -high, a missing score pl-score-missing |
| filter bar (HTML) | plotissimo-filter, pl-theme-<name>, pl-filter-search, pl-filter-chips, pl-filter-title, pl-filter-chip (aria-pressed), pl-filter-swatch, pl-filter-icon, pl-filter-count, pl-filter-clear |
| materiality matrix | pl-quadrant, pl-quadrant-<not-material / financial / impact / double>, pl-quadrant-label, pl-threshold, pl-matrix-topic (pl-matrix-category-<key>, pl-matrix-multiple, pl-has-subs, pl-open, pl-selected, pl-branched), pl-matrix-point, pl-matrix-short-label, pl-matrix-hub, pl-matrix-hub-point, pl-matrix-branch, pl-matrix-sub, pl-matrix-subpoint, pl-matrix-connector |
| series | pl-series, pl-series-<type>, pl-series-<index>, pl-color-<n> (palette colour), pl-off when hidden; parts: pl-line, pl-area, pl-point (with pl-marker pl-marker-<shape>, pl-marker-filled), pl-bar, pl-bubble, pl-data-label; a selected part pl-selected |
Series colours come from CSS variables: the theme defines --pl-color-0 … --pl-color-9; pl-color-<n> sets
--pl-c for a series, and its parts use var(--pl-c). A series option color sets --pl-c itself.
Colours in options win over the theme: a series color, a point color, a zone color, a quadrant color and
the matrix's category colours are fixed and do not change with the theme. Leave them out (the categories excepted) to
use the theme's colours.
#17. Accessibility
Every chart can be read by screen readers and used with the keyboard; nothing to switch on.
Name and description. The <svg> has role="img", an aria-label (the chart's title) and a <desc> that
describes it, made from the data: the kind of chart, the title, the axes and a summary per series, e.g. "Bar chart:
Energy use. Horizontal axis Month, vertical axis Energy (MWh). Rotterdam: 3 values, from 60 to 81." Pie charts give
their shares, Gantt charts the number of tasks, the period and the statuses, gauges the value and its band, sunbursts
the centre, rings and first ring. There is no <title> on the chart itself, because browsers would show it as a tooltip
over the whole chart.
new Plotissimo.BarChart("#c", {
accessibility: {
label: "Energy use per month", // the name (default: the title, else the kind of chart)
description: "Energy use rose by a third from January to March.", // or (chart) => text, or null for none
table: true, // the data as tables after the <svg>, for screen readers only
},
...
});
chart.describe(); // the automatic description, e.g. to show it as text on the page
chart.dataTable(); // [{caption, columns, rows}]: the data of the visible series, as texts
Write your own description when the message matters more than the numbers ("Emissions fell 15% since 2023").
table: true adds a <div class="pl-sr-only pl-data-tables"> with one <table> per series right after the
<svg>; it is hidden on screen (the class pl-sr-only in plotissimo.css) and rebuilt on every draw. It needs the chart
to be drawn into a container, not into your own <svg>.
Keyboard. Parts you can click are reachable with Tab: bars, points and bubbles when the chart has a popup;
bubbles with selectable, points with labels: "click", matrix topics, pie slices, Gantt tasks, sunburst segments,
legend items. Each has role="button" and an aria-label ("Rotterdam – Feb: 72"). In a chart:
| Key | Does |
|---|---|
| Tab / Shift+Tab | to the next / previous chart part (and on to the rest of the page) |
| Arrow keys | to the next / previous part of the same group: the legend, or the rest of the chart (wraps around) |
| Home / End | the first / last part of the group |
| Enter / Space | what a click does: open the popup, select, open sub topics, zoom |
| Escape | close the popup |
The focused part gets a ring in the text colour (:focus-visible); after a redraw (e.g. a toggle with Enter) the
focus stays on the same part.
Colour and motion. Use palette: "colorblind" for colours that people with colour blindness can tell apart, and
do not rely on colour alone: labels, the legend and the popups carry the values. With reduce motion switched on in
the operating system (prefers-reduced-motion), Plotissimo uses no transitions.
#18. Export: PNG and SVG
await chart.download(); // chart-title.png (2 pixels per chart pixel)
await chart.download({ format: "svg" }); // chart-title.svg
await chart.download({ format: "png", filename: "emissions.png", scale: 3, background: "white" });
const svgText = chart.toSVG(); // a stand-alone SVG document (a string)
const blob = await chart.toPNG({ scale: 2 }); // a PNG Blob, e.g. to upload
| Option | Default | Description |
|---|---|---|
format |
"png" |
download() only: "png" or "svg" |
filename |
from the title | download() only; download() returns the name |
scale |
2 |
PNG only: pixels per chart pixel (2 is sharp on most screens and in documents) |
background |
none | a colour behind the chart, e.g. "white"; the theme's background is already there when the chart has one (background: true, the default) |
styles |
true |
false: the SVG keeps only the class names, for use with plotissimo.css |
The export is what you see: the theme, palette, gradients, effects, hidden series and zoom of the moment, and the
watermark when the page has no valid licence key. The SVG carries the styles inline (as the browser computed them), so
it looks the same without plotissimo.css, e.g. in a document or a drawing program. Popups are not part of the chart and
are not exported. Fonts: the export uses the font names of the theme; a web font that is not installed on the computer
that opens an SVG file falls back to another font (in a PNG the text is already drawn). toPNG() and download() need
a browser; toSVG() works in any DOM.
#19. Spacing values
padding and margin take the same values as in CSS:
| Value | Means |
|---|---|
8 |
8 on all sides |
[8, 16] |
8 top and bottom, 16 left and right |
[4, 16, 8] |
top 4, left and right 16, bottom 8 |
[4, 16, 8, 12] |
top, right, bottom, left |
{top: 4, left: 12} |
missing sides are 0 |
#20. Troubleshooting
| Problem | Cause |
|---|---|
| The chart is black / has no colours | plotissimo.css is not loaded |
Plotissimo: target not found |
the target element does not exist (yet); create the chart after the element, e.g. at the end of <body> |
Plotissimo: target "…" matches 2 elements (a warning) |
the selector or id is on more than one element; the chart is in the first one. Give the element a unique id |
Plotissimo: unknown series type |
a series' type is not one of the series types (line, bar, pie, sankey, …) |
| Labels overlap after changing fonts | call chart.draw() (or setTheme) after the font has loaded, so text is measured again |
| Tick labels are missing | they would overlap: set labels.rotate, fewer ticks (ticks.major.spacing) or labels.overlap: "show" |
| Axis bounds are not what you want | set min, max or step on the scale |
| The matrix quadrants keep the same colours in every theme | a quadrants.<name>.color option is set; leave it out, or set --pl-quadrant-* in the theme |
A Gantt chart is taller than height |
rowHeight sets the height from the number of rows; use rowHeight: null to keep height |
| Dates are a day off | dates are UTC; give dates as "2026-03-31" (date only) or as UTC timestamps |
| No popup opens | the popup function returns null for that part (check c.part), or popup is not set on the chart |
More examples: the pages in examples/ (npm run serve, then http://localhost:8000/examples/).
#21. Building blocks
For extending Plotissimo (a new series type, an own preset) or using its parts on their own, Plotissimo (or the
ES module) also exports the pieces the charts are made of.
What is stable. From 1.0 on, these do not change within a major version (1.x): the chart classes and their options, the series options, the events and the methods in this guide, the class names, and the exports in the table below with the methods and arguments described there. Anything else, such as methods of the classes that this guide does not name, is internal and may change in any version. Options renamed before 1.0 still work in 0.x with a console warning ("… is now …") and are removed in 1.0.
| Export | What it is |
|---|---|
Chart, LineChart, BarChart, BubbleChart, PieChart, GaugeChart, BulletChart, SparklineChart, RadarChart, SlopeChart, HeatmapChart, SunburstChart, WaterfallChart, LimitDiagram, SankeyChart, HistogramChart, BoxPlotChart, FunnelChart, TreemapChart, GanttChart, MaterialityMatrix |
the chart and its presets (chart types); a preset is a subclass with static presets() |
SERIES_TYPES |
the series types by name (line, bar, …); add a class here to make type: "<name>" work |
Series, LineSeries, BarSeries, BubbleSeries, PieSeries, GaugeSeries, BulletSeries, RadarSeries, SlopeSeries, HeatmapSeries, SunburstSeries, WaterfallSeries, LimitSeries, SankeySeries, HistogramSeries, BoxPlotSeries, FunnelSeries, TreemapSeries, GanttSeries, MatrixSeries |
the series classes; a new series extends Series and implements static defaults(), includeDomain() and drawData(group, labels), and registers its drawn parts with this.bind(node, part, datum) for events |
ChartElement, Title, Legend, Axis, PlotArea |
the key elements; ChartElement holds the box model (padding, margin, visibility) |
LinearScale, BandScale, TimeScale, createScale, niceStep, TIME_INTERVALS, toTime |
the scales (scales): map(value) to a position, ticks(), format(value); niceStep (1, 2, 2.5 or 5 × a power of ten), the time intervals, a date as milliseconds |
arcPath, arcExtent, polar |
arcs: the path of a pie slice or ring segment, the part of a circle some angles cover, a point at an angle (0 at 12 o'clock, clockwise) |
quantile(sorted, q), squarify(items, rect) |
the box plot's quartiles (linear interpolation) and the treemap's layout (items with a value, rect {x, y, width, height}; returns [{item, x, y, width, height}]) |
colorAt, parseColor, COLOR_SCALES |
colours: the colour at 0–1 along colour stops, a colour as [r, g, b], the heat map's colour scales |
drawMarker, MARKERS, dashArray, LINE_STYLES |
markers (circle, square, triangle, star, x, +) and line styles (dash codes) |
Popup, escapeHtml |
the popup (popups) and text made safe for HTML |
DEFAULT_CATEGORIES |
the materiality matrix's default categories (E, S, G, Other) |
createSVGElement, SVG_NS, spacing |
an SVG element with attributes, the SVG namespace, a spacing value as {top, right, bottom, left} |
useStyleSheet(href), version |
load or replace the stylesheet; the library's version |
setLicenseKey(key), license(), previewWatermark(on) |
the page's licence key, its status, and the watermark shown on a development host too (licence key) |
#22. Frameworks
Laravel, React, Next.js, Vue, Angular and Svelte below; each example was tried in a new project of that framework. A chart needs no special integration: in any framework it comes down to four steps.
- Create the chart (
new BarChart(element, options)) after its element is in the page. - Call
chart.update({ series })when the data changes (the new series replace the old ones, changing a chart). - Call
chart.destroy()when the element leaves the page: it removes the chart's<svg>, its popup and its observers. - Call
setLicenseKey(…)once, when the application starts, not per chart (licence key).
Plotissimo can be imported on a server (server-side rendering): the import does not need a document. Creating a
chart does, so that happens in the browser only.
#Laravel
Laravel builds its scripts with Vite (resources/js/app.js). Install the package in the Laravel project:
npm install plotissimo
In resources/js/app.js, the licence key and one rule: every element with data-plotissimo becomes a chart, with
its options from the controller as JSON:
import * as Plotissimo from "plotissimo";
import "plotissimo/plotissimo.css";
// the key in .env: VITE_PLOTISSIMO_KEY=… (Vite passes variables that start with VITE_ to the browser)
if (import.meta.env.VITE_PLOTISSIMO_KEY) {
Plotissimo.setLicenseKey(import.meta.env.VITE_PLOTISSIMO_KEY);
}
// <div data-plotissimo="BarChart" data-options='{…}'> becomes a chart
document.querySelectorAll("[data-plotissimo]").forEach((element) => {
const ChartClass = Plotissimo[element.dataset.plotissimo];
new ChartClass(element, JSON.parse(element.dataset.options));
});
The controller builds the options as a PHP array, e.g. from the database:
public function show()
{
$quarters = ['Q1' => 60, 'Q2' => 72, 'Q3' => 81, 'Q4' => 68];
return view('energy', [
'energy' => [
'title' => ['text' => 'Energy use'],
'axes' => ['left' => ['title' => 'Energy', 'unit' => 'MWh']],
'series' => [[
'name' => '2026',
'data' => collect($quarters)->map(fn ($value, $quarter) => [$quarter, $value])->values(),
]],
],
]);
}
and the Blade view puts them on the element with @json:
<head>
@vite(['resources/js/app.js'])
</head>
<body>
<div data-plotissimo="BarChart" data-options='@json($energy)'></div>
</body>
- Use single quotes around
@json(…):@jsonescapes quotes,<,>and&in the data, so names with apostrophes or HTML stay plain text. - JSON has no functions. A chart with a
popup, aformatfunction or an event handler gets a script of its own, with only the data from the controller:
// resources/js/energy.js (also in the input list of vite.config.js)
import { LineChart } from "plotissimo";
const element = document.getElementById("energy-trend");
new LineChart(element, {
axes: { left: { title: "Energy", unit: "MWh" } },
series: JSON.parse(element.dataset.series),
popup: (c) => (c.part === "point" ? { title: c.datum.series.options.name, content: `${c.datum.datum.y} MWh` } : null),
});
@vite(['resources/js/app.js', 'resources/js/energy.js'])
…
<div id="energy-trend" data-series='@json($series)'></div>
Without Vite, a <script> tag works as in installation A: copy plotissimo.min.js and
plotissimo.css to public/ and write the options into the page the same way.
#React
One component for every chart type: it makes the chart when it appears, follows the series prop and removes the
chart when it disappears.
// src/PlotissimoChart.jsx
import { useEffect, useRef } from "react";
import * as Plotissimo from "plotissimo";
import "plotissimo/plotissimo.css";
export function PlotissimoChart({ type, options, series, className }) {
const element = useRef(null);
const chart = useRef(null);
useEffect(() => {
chart.current = new Plotissimo[type](element.current, { ...options, series });
return () => {
chart.current.destroy();
chart.current = null;
};
}, [type]); // made once per chart type; the series follow below
useEffect(() => {
chart.current?.update({ series });
}, [series]);
return <div ref={element} className={className} />;
}
// src/main.jsx: the licence key once, before the first chart
import { setLicenseKey } from "plotissimo";
setLicenseKey(import.meta.env.VITE_PLOTISSIMO_KEY);
// in a component
const series = useMemo(() => [{ name: "2026", data: quarters }], [quarters]);
<PlotissimoChart
type="BarChart"
options={{ title: { text: "Energy use" }, axes: { left: { title: "Energy", unit: "MWh" } } }}
series={series}
/>
- The cleanup function (
destroy()) is needed: React'sStrictModecreates every component twice during development, and without it there would be two charts in the element. - Give
serieswithuseMemo(or from state): a new array on every render redraws the chart on every render. - The chart does not change the data it gets, so frozen state (Redux Toolkit, Immer) works.
- To change other options than the series, call
chart.current.update({ title: … })in an effect of its own, or give the component akeythat changes: React then makes a new chart.
#Next.js
The React component works in Next.js (App Router) with "use client" as its first line. A page (a
server component) fetches the data and gives it to the component:
// app/PlotissimoChart.js: the React component above, with this first line
"use client";
// app/page.js
import PlotissimoChart from "./PlotissimoChart";
export default async function Page() {
const series = await getEnergy(); // on the server: a database, an API
return (
<PlotissimoChart
type="BarChart"
options={{ title: { text: "Energy use" }, axes: { left: { title: "Energy", unit: "MWh" } } }}
series={series}
/>
);
}
The stylesheet and the licence key go in the root layout; the key through a small client component, so it is set in the browser:
// app/layout.js
import "plotissimo/plotissimo.css";
import PlotissimoLicence from "./PlotissimoLicence";
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<PlotissimoLicence />
{children}
</body>
</html>
);
}
// app/PlotissimoLicence.js
"use client";
import { setLicenseKey } from "plotissimo";
if (typeof window !== "undefined") {
setLicenseKey(process.env.NEXT_PUBLIC_PLOTISSIMO_KEY); // NEXT_PUBLIC_ variables reach the browser
}
export default function PlotissimoLicence() {
return null;
}
- The page is rendered on the server with an empty
<div>; the chart is drawn in the browser. - What a server component passes to a client component must be plain data: options with functions (
popup,format) are written in the client component itself.
#Vue
The same component for Vue 3:
<!-- src/components/PlotissimoChart.vue -->
<script setup>
import { onBeforeUnmount, onMounted, ref, toRaw, watch } from "vue";
import * as Plotissimo from "plotissimo";
import "plotissimo/plotissimo.css";
const props = defineProps({
type: { type: String, default: "Chart" },
options: { type: Object, default: () => ({}) },
series: { type: Array, default: () => [] },
});
const element = ref(null);
let chart = null; // a plain variable, not ref(): Vue must not make the chart reactive
onMounted(() => {
chart = new Plotissimo[props.type](element.value, { ...props.options, series: toRaw(props.series) });
});
// deep: also when a value changes or a point is added inside the array
watch(() => props.series, (series) => chart?.update({ series: toRaw(series) }), { deep: true });
onBeforeUnmount(() => {
chart?.destroy();
chart = null;
});
</script>
<template>
<div ref="element" />
</template>
<!-- in a component -->
<script setup>
import { ref } from "vue";
import PlotissimoChart from "./components/PlotissimoChart.vue";
const series = ref([{ name: "2026", data: [["Q1", 60], ["Q2", 72], ["Q3", 81]] }]);
const options = { title: { text: "Energy use" }, axes: { left: { title: "Energy", unit: "MWh" } } };
</script>
<template>
<PlotissimoChart type="BarChart" :options="options" :series="series" />
</template>
// src/main.js: the licence key once, before the first chart
import { setLicenseKey } from "plotissimo";
setLicenseKey(import.meta.env.VITE_PLOTISSIMO_KEY);
- Keep the chart in a plain variable. In
ref()orreactive()Vue would wrap the whole chart object (its SVG elements, scales and series) in proxies. toRawgives the chart the data itself instead of Vue's proxy of it.- Both a new array (
series.value = […]) and a change inside it (series.value[0].data.push(…)) redraw the chart.
#Angular
A standalone component; the chart class is passed as the type:
// src/app/plotissimo-chart.ts
import { AfterViewInit, Component, ElementRef, Input, NgZone, OnChanges, OnDestroy, SimpleChanges, ViewChild, inject } from "@angular/core";
import { Chart, ChartOptions } from "plotissimo";
@Component({
selector: "plotissimo-chart",
template: "<div #element></div>",
})
export class PlotissimoChart implements AfterViewInit, OnChanges, OnDestroy {
@Input() type: typeof Chart = Chart;
@Input() options: ChartOptions = {};
@Input() series: ChartOptions["series"] = [];
@ViewChild("element") element!: ElementRef<HTMLDivElement>;
private chart: Chart | null = null;
private zone = inject(NgZone);
ngAfterViewInit(): void {
// outside Angular: the chart's own mouse and resize handlers need no change detection
this.zone.runOutsideAngular(() => {
this.chart = new this.type(this.element.nativeElement, { ...this.options, series: this.series });
});
}
ngOnChanges(changes: SimpleChanges): void {
if (changes["series"] && this.chart) {
this.zone.runOutsideAngular(() => this.chart?.update({ series: this.series }));
}
}
ngOnDestroy(): void {
this.chart?.destroy();
this.chart = null;
}
}
// in a component
import { BarChart, ChartOptions } from "plotissimo";
import { PlotissimoChart } from "./plotissimo-chart";
@Component({
selector: "app-energy",
imports: [PlotissimoChart],
template: `<plotissimo-chart [type]="BarChart" [options]="options" [series]="series" />`,
})
export class Energy {
BarChart = BarChart;
options: ChartOptions = { title: { text: "Energy use" }, axes: { left: { title: "Energy", unit: "MWh" } } };
series: ChartOptions["series"] = [{ name: "2026", data: [["Q1", 60], ["Q2", 72], ["Q3", 81]] }];
}
- The stylesheet: add
"node_modules/plotissimo/dist/plotissimo.css"tostylesinangular.json. - The licence key:
setLicenseKey(…)insrc/main.ts, beforebootstrapApplication. - Angular passes a new array to
ngOnChanges: assignthis.series = […]to redraw the chart; apushinto the same array is not seen.
#Svelte
An action: the chart is made when the element appears, follows the series and is removed with the element.
// src/lib/plotissimo.ts
import type { Action } from "svelte/action";
import { Chart, type ChartOptions } from "plotissimo";
import "plotissimo/plotissimo.css";
export const plotissimo: Action<HTMLElement, { type?: typeof Chart; options: ChartOptions }> = (node, { type = Chart, options }) => {
const chart = new type(node, options);
return {
update({ options }) {
chart.update({ series: options.series });
},
destroy() {
chart.destroy();
},
};
};
<!-- in a component (Svelte 5) -->
<script lang="ts">
import { BarChart } from "plotissimo";
import { plotissimo } from "$lib/plotissimo";
let series = $state([{ name: "2026", data: [["Q1", 60], ["Q2", 72], ["Q3", 81]] as [string, number][] }]);
const options = { title: { text: "Energy use" }, axes: { left: { title: "Energy", unit: "MWh" } } };
</script>
<div use:plotissimo={{ type: BarChart, options: { ...options, series: $state.snapshot(series) } }}></div>
$state.snapshotgives the chart plain data, and makes both a new array and a change inside it (series[0].data.push(…)) redraw the chart.- The licence key, in SvelteKit in
src/routes/+layout.svelte:import { browser } from "$app/environment"; if (browser) setLicenseKey(import.meta.env.VITE_PLOTISSIMO_KEY); - SvelteKit renders the page on the server; actions run in the browser only.