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

  1. Installation
  2. Your first chart
  3. Chart types
  4. Chart options
  5. Title
  6. Legend
  7. Axes
  8. Scales
  9. Plot area: grid, zones and reference lines
  10. Series
  11. Materiality matrix
  12. Gantt chart
  13. Changing a chart after drawing
  14. Events
  15. Popups
  16. Themes and styling
  17. Accessibility
  18. Export: PNG and SVG
  19. Spacing values
  20. Troubleshooting
  21. Building blocks
  22. 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]] }],
});

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>

Finding errors

Look in two places:

  1. The editor, while you type. Make // @ts-check the first line of your .js file (above the /// <reference …> or import line 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-check the editor still completes the options, but it may not report these mistakes. The check needs a separate .js file: 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.

  2. 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.

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}:

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

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.

  1. Create the chart (new BarChart(element, options)) after its element is in the page.
  2. Call chart.update({ series }) when the data changes (the new series replace the old ones, changing a chart).
  3. Call chart.destroy() when the element leaves the page: it removes the chart's <svg>, its popup and its observers.
  4. 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>
// 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}
/>

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

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

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

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>