Sales dashboard
Eight charts: KPI cards, a combo chart, a donut, a heatmap and a funnel. Each chart takes a few options, and the monthly/quarterly switch is a single update().
26 canvas chart types, each drawn from one options object. One way to use them, with the same names and options in React, Vue, Svelte and jQuery.
@aeriz/chart draws 26 canvas chart types from one options object. Pass a container and your data; axes, legend, tooltips, animation and theme come from sensible defaults.
data, changes go through update(), states through setState(). Same in all 26 charts and five environments.New in 2.1.1 Links and buttons and your own content in tooltips, legend clicks you can take over, and the item under the pointer. Code for 2.1 runs as it is.
New in 2.1 Reference lines and bands, zoom and brush, sync, 100% stacking, error bars, more value axes, plus candlestick, treemap and sunburst, sankey, network and map. Code for 2.0 runs as it is.
Examples built like real product screens. They all run on this page, and the JS, HTML and CSS tabs hold all of the code behind each one. Every chart is new SomeChart(element, { data }) plus a few options. For each chart type on its own, see Chart types.
Eight charts: KPI cards, a combo chart, a donut, a heatmap and a funnel. Each chart takes a few options, and the monthly/quarterly switch is a single update().
Nine charts: a four-layer combo with a right axis, a stacked area, an ARR bridge, cohort retention, quartile distributions, 20,000 points and an 8,760-cell heatmap. One segment button calls update() on all of them.
Sign-ups (bars) and their 8-week average (area) use the left axis, conversion (line) the right % axis. Red dots mark weeks far off the average.
Click the legend to drop a channel. The rest restack.
From opening ARR through new, expansion, contraction and churn to closing.
Months that have not happened yet stay empty (null).
Quartiles and outliers computed from 8,000 sessions.
Six survey items, out of 10.
Colored by plan. Hover picks out a single user.
Counted from the same data as the cloud.
Weekends and commute hours stand out. Every cell has a tooltip.
Click a region bar and onClick switches the other charts to that region, then rebuilds and redraws 1,000,000 per-second transactions. The time it took is printed at the top.
A live line that moves every 0.1 s, three gauges and response time per API. Press "Simulate an outage".
Put the same charts on white paper and they read the text and background colors to switch to a light theme. Brand colors are two CSS variables.
Overall satisfaction is 4.3 out of 5, up 0.4 from last year. Scores rose in every age group, and faster delivery made the biggest difference.
Pick your package manager. Without a build step, use the CDN tab.
npm install @aeriz/chartpnpm add @aeriz/chartyarn add @aeriz/chart<!-- Everything (global Aeriz, about 38 KB gzip) -->
<script src="https://cdn.jsdelivr.net/npm/@aeriz/chart@2.1.1/dist/aeriz.min.js"></script>
<!-- One chart (ES module) -->
<script type="module">
import { BarChart } from 'https://cdn.jsdelivr.net/npm/@aeriz/chart@2.1.1/dist/esm/charts/bar.js';
</script>The npm package holds only the minified build (dist/) and the TypeScript types.
import → dist/esm/, one file per chartrequire → dist/aeriz.min.cjsdist/aeriz.min.jsMinifying only shortens local names. Option names, methods, chart names and error messages read as they are.
Tip Pin an exact version in CDN URLs, like @2.1.1. Those URLs never change, so they are cached for a year.
All you need is an element with a height and some data. Without a height the chart uses 320px.
<div id="sales" style="height: 260px"></div>
<script type="module">
import { BarChart } from '@aeriz/chart';
const chart = new BarChart('#sales', {
data: { Jan: 64, Feb: 42, Mar: 78, Apr: 55, May: 90, Jun: 71 },
});
chart.update({ data: { Jan: 30, Feb: 80 } }); // animates to the new values
</script>Hover a bar, or focus the chart and read the values with ← →.
Every chart uses the same four calls. There are no other names for the same thing.
| To | Use |
|---|---|
| Create | new BarChart(element or selector, options) |
| Change data or options | chart.update({ data, … }) — pass only what changed; values animate |
| Loading · empty · error | chart.setState('loading' | 'empty' | 'error', text?), and chart.setState(null) to close |
| Redraw right now | chart.render() — re-reads CSS variables and draws the final frame immediately, even off-screen |
| Remove | chart.destroy() — puts the element back as it was |
Only RealtimeChart adds push() to stream values and clear() to empty it.
Data always goes in the one data option. Its shape follows what the chart draws.
Bar, HBar, Line, Sparkline, Pie, Polar, Funnel, Treemap, Sunburst and Map take any of these three. They all mean the same.
new BarChart(el, { data: [64, 42, 78] }); // numbers → labels 1, 2, 3
new BarChart(el, { data: { Jan: 64, Feb: 42 } }); // object → keys are labels
new BarChart(el, { data: [{ label: 'Jan', value: 64 }] }); // rows
// Rows with other field names: say how to read them
new BarChart(el, { data: rows, label: (r) => r.month, value: (r) => r.sales });Area, StackedBar, GroupedBar, MultiLine, Radar and Composite take categories and series inside data. Each series has one value per category. For error bars and bands, add low and high to rows or series (Error bars).
new GroupedBarChart(el, {
data: {
categories: ['Q1', 'Q2', 'Q3'],
series: [
{ name: '2025', values: [120, 135, 150] },
{ name: '2026', values: [140, 160, 172] },
],
},
});| Chart | data |
|---|---|
| Scatter · Bubble | [{ x, y, size?, group?, label? }] — Scatter's size is the point radius in px; Bubble's size is a value drawn as the bubble's area |
| Heatmap | { x: [...], y: [...], values: [[...], …] } — values[y][x] |
| Boxplot | [{ label, min, q1, median, q3, max, outliers? }] |
| Waterfall | [{ label, value, total? }] — a total: true bar goes from zero to its value (subtotals, the end result) |
| Gauge | a number (data: 72) |
| Realtime | { series: [{ name }] } — values arrive with push() |
| Candlestick | [{ label, open, high, low, close }] |
| Treemap · Sunburst | one value per item; a row with children: [...] nests — Hierarchies |
| Sankey | { links: [{ source, target, value }], nodes?: [{ id, label?, color? }] } |
| Network | { nodes: [{ id, label?, group?, size? }], links: [{ source, target, value? }] } |
| Map | one value per item (the label is the region id), plus the map as the geo option — Map |
A wrong option or a data shape the chart can't read never turns into a silent empty chart. The browser console says what is wrong and how to fix it, once per message.
[aeriz] BarChart: unknown option "dat" — did you mean "data"?
[aeriz] BarChart: "color" is a 1.x option. In 2.0 use colors.
[aeriz] MultiLineChart: data must be { categories: [...], series: [{ name, values: [...] }] } — got an array.
[aeriz] MultiLineChart: series[1] "Sign-ups" has 5 values but there are 6 categories.
[aeriz] LineChart: rows need a "value" field, or pass value: (row) => row.amount.
[aeriz] PieChart: values can't be negative — "Refunds" is -3. It is drawn as 0.
[aeriz] BarChart: "zoom" is not available on this chart — it works on LineChart, MultiLineChart, AreaChart, CompositeChart, CandlestickChart and ScatterChart.
[aeriz] MapChart: 3 rows match no region (e.g. "Korea"). Keys are feature ids, or properties.name when a feature has no id.Calling a removed method throws with its replacement (chart.setData() was removed. Use chart.update({ data }).). With TypeScript, the editor catches the same mistakes first.
Every chart is its own module and the package has "sideEffects": false, so bundlers (Vite, webpack, Rollup, esbuild) drop the charts you don't use. Import as usual — also from the React, Vue and Svelte adapters.
import { BarChart, PieChart } from '@aeriz/chart'; // just these two plus the shared coreWithout a bundler, or to be sure you get exactly one chart, import its subpath.
import { BarChart } from '@aeriz/chart/bar';
import { SparklineChart } from '@aeriz/chart/sparkline';| Import | Size (min + gzip) |
|---|---|
| One chart without axes (Gauge, Pie, Funnel …) | about 12 KB |
| One hierarchy, flow or map chart (Treemap, Sunburst, Sankey, Network, Map) | about 12–13 KB |
| One chart with axes (Bar, Line, Composite …) | about 14–17 KB |
| Bar + Line + Pie | about 18 KB |
| All 26 types | about 35 KB (the CDN aeriz.min.js is about 38 KB) |
Zoom · sync (loaded separately the first time zoom or sync is used) | about 3 KB |
Tooltip links, buttons and custom content (loaded separately the first time tooltip: { … } is used) | about 2.4 KB |
| React · Vue · Svelte · jQuery adapters | 0.3–0.7 KB each |
Measured with esbuild. The shared core (canvas, theme, tooltip, legend, input, mistake warnings) is shared by every chart, so adding charts adds little.
Subpaths: bar hbar line area stacked-bar grouped-bar multi-line scatter bubble pie radar polar gauge heatmap boxplot funnel treemap sparkline realtime waterfall composite candlestick sunburst sankey network map
All five environments use the same chart names and options. Without a framework, use the classes directly.
import { LineChart } from '@aeriz/chart';
const chart = new LineChart('#trend', { data: [3, 7, 4, 9, 6, 12] });
chart.update({ data: [5, 8, 6, 11] });
chart.destroy(); // when the element leaves the pageImport the component with the chart's name from @aeriz/chart/react. Every option is a prop. Works with React 16.8 and later.
import { useRef } from 'react';
import { BarChart } from '@aeriz/chart/react';
export function Sales({ rows }) {
const chart = useRef(null); // chart.current = the chart instance
return (
<BarChart
data={rows}
format={{ style: 'currency', currency: 'USD' }}
onClick={(hit) => console.log(hit.label, hit.value)}
ref={chart}
style={{ height: 320 }}
/>
);
}update(). Inline objects and functions re-created on every render don't redraw when their values are the same.[...rows, row]).className, style, id, aria-* and data-* go to the wrapper <div>. StrictMode still creates one chart.Import the component with the chart's name from @aeriz/chart/vue. Options are props; onClick, onHover, onLegend and onZoom are the events @click, @hover, @legend and @zoom. Works with Vue 3.2 and later.
<script setup>
import { ref } from 'vue';
import { LineChart } from '@aeriz/chart/vue';
const rows = ref([3, 7, 4, 9]);
const add = () => (rows.value = [...rows.value, Math.random() * 10]);
const trend = ref(null); // trend.value.chart = the chart instance
</script>
<template>
<LineChart :data="rows" curve="linear" @click="(hit) => console.log(hit)" ref="trend" style="height: 300px" />
</template>Vue's reactive proxies are removed before the data reaches the chart, so large data stays fast. Replace data with a new value; changes made in place (rows.value.push()) are not detected.
@aeriz/chart/svelte has one action per chart (barChart, lineChart, multiLineChart …). The parameter is the options. No compiler setup, and the same in Svelte 3, 4 and 5.
<script>
import { barChart, chartOf } from '@aeriz/chart/svelte';
let rows = $state([{ label: 'A', value: 5 }, { label: 'B', value: 9 }]);
</script>
<div use:barChart={{ data: rows, onClick: (hit) => console.log(hit) }} style="height: 300px"></div>Use chartOf(element) when you need the chart instance.
Add the charts you use with install($, { … }), then create one by its subpath name ('bar', 'pie' …). The CDN script (aeriz.min.js) adds all 26 by itself when jQuery is loaded first.
import $ from 'jquery';
import { PieChart } from '@aeriz/chart/pie';
import { install } from '@aeriz/chart/jquery';
install($, { PieChart });
$('#share').aerizChart('pie', { data: { Chrome: 64, Safari: 19 }, innerRadius: 0.6 });<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@aeriz/chart@2.1.1/dist/aeriz.min.js"></script>
<script>
$('#share').aerizChart('pie', { data: { Chrome: 64, Safari: 19 } });
</script>$('#share').aerizChart('update', { data: { Chrome: 70, Safari: 20 } }); // setState · render · destroy work the same way
$('#share').aerizChart('instance'); // the chart instanceThese are live. Click a legend item to turn a series off and on.
| Class | Subpath | data | Notes |
|---|---|---|---|
BarChart | bar | one value per item | negatives grow down, dataLabels |
HBarChart | hbar | one value per item | horizontal, label column fits the labels |
LineChart | line | one value per item | curve, time axis, log axis, a million points, zoom, bands |
AreaChart | area | categories · series | stacked ('percent'), zoom |
StackedBarChart | stacked-bar | categories · series | negatives stack down, stacked: 'percent' |
GroupedBarChart | grouped-bar | categories · series | series side by side, error bars |
MultiLineChart | multi-line | categories · series | shared tooltip that follows the pointer, zoom, bands |
ScatterChart | scatter | [{ x, y }] | batched by color and size, zoom |
BubbleChart | bubble | [{ x, y, size }] | size is the area |
PieChart | pie | one value per item | donut with innerRadius, toggle slices from the legend |
RadarChart | radar | categories · series | tooltip per point |
PolarChart | polar | one value per item | area follows the value (scale: 'linear' for radius) |
GaugeChart | gauge | a number | update({ data }) moves on from the shown value |
HeatmapChart | heatmap | { x, y, values } | colors: { low, high } |
BoxplotChart | boxplot | [{ min, q1, median, q3, max }] | outlier dots |
FunnelChart | funnel | one value per item | conversion from the first stage |
TreemapChart | treemap | one value per item (+ children) | squarified layout; groups get a header |
SparklineChart | sparkline | one value per item | tiny trend line, no axes |
RealtimeChart | realtime | { series } + push() | scrolls through a fixed window |
WaterfallChart | waterfall | [{ label, value, total? }] | running total |
CompositeChart | composite | categories · series (type) | mix bars, lines, areas, dots; several value axes, stacked bars, zoom |
CandlestickChart | candlestick | [{ label, open, high, low, close }] | price-fitted axis, zoom, tens of thousands of candles |
SunburstChart | sunburst | one value per item (+ children) | one ring per level, share in the middle |
SankeyChart | sankey | { links, nodes? } | flow bands as thick as their value |
NetworkChart | network | { nodes, links } | force layout, neighbor highlight |
MapChart | map | one value per item + geo | colors GeoJSON regions, scale: 'log' |
Draws open, high, low and close for each period. The body runs from open to close (colors.up when the price rose, colors.down when it fell) and the wick from low to high. The value axis fits the visible prices instead of starting at zero.
new CandlestickChart('#stock', {
data: candles, // [{ label, open, high, low, close }]
zoom: true,
range: ['7/29', '10/22'], // start on the last three months
annotations: [{ y: 80, label: 'Target $80' }],
// colors: { up: '#ef4444', down: '#3b82f6' } for markets where red means up
});Drag to zoom in; hold Shift and drag, or scroll sideways, to pan. Double-click to see everything.
When candles get thinner than 3 px only the wicks are drawn, and the pointer finds the nearest candle per pixel column, so tens of thousands of candles stay light. The x axis takes labels ('8/3') or xScale: 'time' with ms timestamps. An open or close outside low–high is reported in the console.
TreemapChart and SunburstChart take the same data. A row with children becomes a group, and a group's value is the sum of its children. There is no depth limit.
const budget = [
{ label: 'Engineering', children: [{ label: 'Backend', value: 42 }, { label: 'Apps', value: 30 }, { label: 'Data', value: 18 }] },
{ label: 'Marketing', children: [{ label: 'Ads', value: 25 }, { label: 'Events', value: 9 }, { label: 'Content', value: 7 }] },
{ label: 'Operations', children: [{ label: 'Support', value: 14 }, { label: 'Office', value: 8 }] },
{ label: 'Other', value: 6 },
];
new TreemapChart('#budget-tree', { data: budget, onClick: (hit) => console.log(hit.path) }); // ['Engineering', 'Backend']
new SunburstChart('#budget-sun', { data: budget });{ JS: 42, TS: 30 }) draws exactly as in 2.0.Engineering › Backend: $42M), and onClick gets the same path as hit.path.Draws the flow between stages as bands as thick as their value. Nodes come from the links, and each node sits as many columns to the right as its longest path from a start. Nodes with no outgoing flow end in the last column.
new SankeyChart('#journey', {
data: {
links: [
{ source: 'Search', target: 'Product page', value: 520 },
{ source: 'Ads', target: 'Product page', value: 300 },
{ source: 'Product page', target: 'Cart', value: 410 },
{ source: 'Cart', target: 'Purchase', value: 330 },
// …
],
nodes: [{ id: 'Purchase', color: '#10b981' }], // only to change a label or color
},
});A link that loops back (a cycle) can't be drawn in a sankey, so it is left out and the console names it. Hovering a band or a node highlights its flow, and onClick's hit.row is the link row (the node row for a node).
Places nodes and links with a force layout: links pull their ends together and nodes push each other apart, settling over the first second. animate: false and render() draw the settled layout at once.
new NetworkChart('#services', {
data: {
nodes: [{ id: 'web', group: 0 }, { id: 'gateway', group: 1, size: 120 }, …], // group: color, size: area
links: [{ source: 'web', target: 'gateway', value: 80 }, …], // value: width
},
radius: [4, 14], // radius in px of the smallest and the largest size
});Hover a node to fade everything but its neighbors.
With 40 nodes or fewer every label is shown; with more, only the hovered node's neighborhood. New data through update() keeps the nodes that stay where they are, and only new nodes look for a place. A link that points to a missing node is reported in the console.
Colors regions by value. The package ships no map data, so pass GeoJSON as geo. A region is found by its feature id, or by properties.name when it has no id.
const geo = await fetch('/data/world-110m.json').then((r) => r.json());
new MapChart('#world', {
geo, // FeatureCollection (Polygon · MultiPolygon, lon/lat)
data: { KOR: 31846, JPN: 40247, USA: 65298 }, // region id → value (rows [{ label, value }] work too)
scale: 'log', // when values bunch up at one end (population, GDP …)
format: { style: 'currency', currency: 'USD', notation: 'compact' },
});GDP per person by country (2019, Natural Earth). The tooltip names each country from its properties.name.
projection: 'mercator' (default) and 'equirectangular'. The map is projected once per size, and the pointer follows the real shapes, holes and islands included.colors: { low, high }; regions with no value are a pale gray. A color legend sits below the map (legend: false hides it)."Korea" where "KOR" was meant). labelFormat: (id) => name renames regions in the tooltip.properties has the English name (name), the Korean name (ko) and GDP per person (gdp). Antarctica is left out.push() a value into a RealtimeChart and it appears on the right; values beyond window drop off the left.
const rt = new RealtimeChart('#cpu', { data: { series: [{ name: 'CPU' }, { name: 'Memory' }] }, window: 120, max: 100 });
setInterval(() => rt.push([cpu(), memory()]), 100);When a LineChart has far more points than pixels, it keeps only the minimum and maximum of each pixel column. The shape stays the same and tooltips show the original points. The result is reused until the data changes, so moving the mouse doesn't recompute it.
Press the button to generate the data and time the draw.
Charts with a value axis draw lines and bands from annotations. A single value is a dashed line; [from, to] is a band. y sits on the value axis and x on the x axis (labels, time or numbers).
new LineChart('#latency', {
data: latency, // response time per hour
annotations: [
{ y: 300, label: 'SLO 300 ms', color: '#ef4444' }, // target line
{ y: [80, 160], label: 'Normal range' }, // band
{ x: '14:00', label: 'Deploy' }, // vertical reference line
],
});y only). Other charts say so in the console.label sits above the right end of a horizontal line (under it when the line is at the top) and at the top of a vertical one; color is used for the line, the band and the text (a faint text color by default).x is the value and y the item label. CompositeChart picks the value axis of a line with axis (More value axes).update({ annotations }) redraws just the lines, without animation.With zoom: true the x axis can be zoomed and panned. LineChart, MultiLineChart, AreaChart, CompositeChart, CandlestickChart and ScatterChart take it. When zoomed, the value axis fits the visible data (axes with bars or areas start at zero).
const chart = new LineChart('#visits', {
data: visits, // [{ label: time (ms), value }]
xScale: 'time',
zoom: true,
range: [from, to], // the range to start with (all when left out)
onZoom: (range) => console.log(range), // [from, to] or null, whenever the user changes it
});
chart.update({ range: null }); // show everything from codeDrag across the chart.
| Mouse · trackpad | Touch | Keyboard (chart focused) | |
|---|---|---|---|
| Zoom in | drag to pick a range · Ctrl/⌘ + wheel · pinch | spread two fingers | + |
| Zoom out | Ctrl/⌘ + wheel · pinch | pinch two fingers | - |
| Pan | Shift + drag · scroll sideways | one-finger drag once zoomed in | Shift + ← → |
| Reset | double-click · the top-right button | the top-right button | 0 |
A plain wheel scrolls the page, and a one-finger drag on a chart that isn't zoomed shows the tooltip, so page scrolling is never blocked. range is in x-axis units: ['Mar', 'May'] on a label axis, ms on a time axis, numbers on a number axis (Scatter). range without zoom just shows that range.
Light by default The code for dragging, pinching and sync (about 3 KB) loads separately, the first time a chart with zoom or sync is created. Charts that don't zoom never load it.
A chart with zoom: 'brush' always shows everything, and the range you drag on it is shown zoomed in by the charts in the same sync group. Drag an edge of the selection to resize it, or its inside to move it.
new LineChart('#detail', { data, xScale: 'time', sync: 'traffic' });
new LineChart('#overview', { data, xScale: 'time', sync: 'traffic', zoom: 'brush', range: [from, to] });Charts with the same sync name share the crosshair and the zoom range. They match the same x value (label, time or number), so the chart types and data lengths can differ.
new MultiLineChart('#requests', { data: requests, sync: 'ops', zoom: true });
new AreaChart('#errors', { data: errors, sync: 'ops', zoom: true, stacked: true });
new CompositeChart('#cost', { data: cost, sync: 'ops', zoom: true });Hover one chart, or drag on it to zoom, and the other two follow.
range hands it to the group. update({ sync: null }) leaves the group.onZoom runs only on the chart the user touched, so handle it once per group.stacked: 'percent' scales each item's total to 100% and stacks the shares. The value axis runs 0–100%, and the tooltip shows the share next to the original value.
new StackedBarChart(el, { data, stacked: 'percent' }); // default true (values as they are)
new AreaChart(el, { data, stacked: 'percent' }); // true · false · 'percent'
new CompositeChart(el, { data, stacked: true }); // bars on the same axis ('percent' works too)100% stacking is a share of positive values, so negatives count as 0 and the console says so. StackedBarChart always stacks, so its stacked takes only true (default) and 'percent'.
Add low and high to a row and bars get an error bar, lines a band. Series data takes low and high arrays with one entry per value. The value axis widens to show the whole interval, and the tooltip reads value (low – high).
new BarChart(el, { data: [{ label: 'A', value: 0.031, low: 0.027, high: 0.035 }, …] });
new LineChart(el, { data: forecast }); // [{ label, value, low, high }] → line + band
new GroupedBarChart(el, {
data: { categories, series: [{ name: '2026', values, low: [...], high: [...] }] },
});BarChart and LineChart take them on rows; GroupedBarChart, MultiLineChart and CompositeChart on series (Composite draws error bars on bars and dots, bands on lines and areas). Other charts say in the console that they leave them out.
Give a CompositeChart series an axis name and each name gets its own value axis. 'left' (default) is on the left; other names go on the right in the order they appear, and series with the same name share an axis. stacked stacks the bars on the same axis.
new CompositeChart('#business', {
stacked: true,
data: {
categories: ['Jan', 'Feb', 'Mar', …],
series: [
{ type: 'bar', name: 'Online', values: online }, // left axis
{ type: 'bar', name: 'Store', values: store }, // same axis, so it stacks on top
{ type: 'line', name: 'Margin', values: margin, axis: 'margin', format: { style: 'percent' } },
{ type: 'line', name: 'Visitors', values: visitors, axis: 'visitors' },
],
},
});format. min and max apply to the left axis; the others fit their data.axis: 'right' works as before — 'right' is just another name.Every chart event is a function you pass as an option. There are no event-name strings and no addEventListener, and all 26 types use the same names and arguments. Swap a function any time with update({ onClick }); that doesn't replay the animation.
| Option | Called when | Use it for |
|---|---|---|
onClick(hit, chart) | an item is clicked, or Enter is pressed on the focused chart | opening a detail page, a popup, drill-down |
onHover(hit, chart) | the item under the pointer changes; hit is null when it leaves | a side panel, highlighting the same row in a table |
onLegend(index, visible, chart, event) | a legend item is clicked, before it changes | event.preventDefault() and do something else instead of the toggle |
onZoom(range, chart) | the user changes the range | keeping the range in the URL, lining up other views — zoom |
tooltip.actions(hit, chart) | a tooltip is made (once per item) | links and buttons under the tooltip |
tooltip.render(hit, chart) | a tooltip is made (once per item) | your own tooltip content |
hit has the same shape everywhere: index (position in your data), label, value, series (series index), row (the item you passed in) and, for hierarchies, path (the names from the top). Anything else you keep on a row, such as an id, is on hit.row. The names are the same in every framework.
new BarChart(el, { data: rows, onClick: open, onHover: show, tooltip: { actions } });<BarChart data={rows} onClick={open} onHover={setHovered} tooltip={{ actions }} /><BarChart :data="rows" :tooltip="{ actions }" @click="open" @hover="(hit) => (hovered = hit)" /><div use:barChart={{ data: rows, onClick: open, onHover: (hit) => (hovered = hit), tooltip: { actions } }}></div>$('#sales').aerizChart('bar', { data: rows, onClick: open, onHover: show, tooltip: { actions } });In React, passing a new function or tooltip object on every render doesn't redraw the chart.
The list tooltip.actions returns goes under the tooltip. An entry with href is a link; one with only onClick is a button. A click runs onClick(hit, chart, event) first, then the tooltip closes. Open a popup, a side panel or another page from that function.
new HeatmapChart('#orders', {
data: { x: hours, y: days, values }, // orders by weekday × hour
tooltip: {
actions: (hit) => [
{ label: 'Orders', href: `/orders?day=${hit.row.y}&hour=${hit.row.x}` },
{ label: '8-week trend', onClick: (hit) => openTrend(hit) }, // a modal, a panel … anything
],
},
});Point at a cell, then move the mouse to a button in the tooltip. Crossing other cells on the way doesn't move the tooltip.
href (for new tabs and copying the address), and in onClick call event.preventDefault(), then router.push(href).target: '_blank'. rel="noopener" is added for you.javascript: addresses are blocked, and the console says to use onClick.A tooltip with links or buttons waits for the mouse to reach it. There is nothing to set, and tooltips without links or buttons follow the mouse right away, as before.
What tooltip.render(hit, chart) returns becomes the tooltip. It runs once per item and isn't called again while the mouse stays on that item. With actions as well, the links and buttons go under your content.
| Return | Tooltip |
|---|---|
| a string or number | that text (never parsed as HTML) |
| a DOM node | that node as it is. With a link or button inside, it becomes a tooltip that waits for the mouse |
null | no tooltip for this item |
undefined | the usual tooltip |
const card = document.querySelector('#store-card'); // a <template>
new BarChart('#stores', {
data: stores, // [{ label, value, target, manager }]
tooltip: {
render: (hit) => {
const el = card.content.firstElementChild.cloneNode(true);
el.querySelector('.name').textContent = hit.label; // data goes in as textContent
el.querySelector('.meter i').style.width = `${(hit.value / hit.row.target) * 100}%`;
return el;
},
actions: (hit) => [{ label: 'Store page', href: `/stores/${hit.row.id}` }],
},
});Point at a bar to see its store card.
<template> and filling it with textContent works well. An HTML string shows as plain text, and the console says to return a node.--aeriz-tooltip-bg · --aeriz-tooltip-fg).Call update({ data }) from onClick and you have a drill-down. The new data animates in, and Enter does the same from the keyboard.
const chart = new BarChart('#sales', {
data: regions, // [{ label: 'West', value: 412, children: [...] }, ...]
onClick: (hit) => {
if (hit.row.children) chart.update({ data: hit.row.children });
},
});Click a bar to go from region to city to store; click the path above to go back.
A legend click calls onLegend(index, visible, chart, event) before anything changes.
visible — the state the item is about to get by default. true for the last visible one, which can't be hidden.event.preventDefault() — stops the default hide/show.event.target — the legend button that was clicked.The hidden option (the positions of the legend items to hide) says what is hidden. Set it from the start or with update({ hidden }); legend clicks update chart.options.hidden too, so you can save it and open the chart the same way next time.
new MultiLineChart('#traffic', {
data: { categories, series },
hidden: [3], // start with the fourth series hidden
onLegend: (i, visible, chart, event) => {
event.preventDefault(); // instead of hide/show: show only this one, click again for all
const others = series.map((_, j) => j).filter((j) => j !== i);
const alone = String(chart.options.hidden) === String(others);
chart.update({ hidden: alone ? [] : others });
},
});To open a menu at the legend item, use the position of event.target. In the demo below a legend click opens a menu, and the menu changes hidden. The menu is the browser's popover, so a click outside or Esc closes it.
onLegend: (i, visible, chart, event) => {
event.preventDefault();
const r = event.target.getBoundingClientRect(); // the legend button
menu.style.left = `${r.left}px`;
menu.style.top = `${r.bottom + 4}px`;
menu.showPopover(); // <div popover> … </div>
},Click the legend: a menu opens instead of the hide/show. From the keyboard, Tab to the legend and press Enter.
Turn the built-in legend off with legend: false, build the legend you want and connect it to update({ hidden }): a list with values and shares, checkboxes, table rows. Add onHover and the item under the pointer can light up in your legend too.
const chart = new PieChart('#share', {
data: browsers, colors, innerRadius: 0.6, legend: false,
onHover: (hit) => highlight(hit?.index), // hit is null when the pointer leaves
});
list.onclick = (e) => {
const i = +e.target.closest('button').dataset.i;
const hidden = chart.options.hidden ?? [];
chart.update({ hidden: hidden.includes(i) ? hidden.filter((j) => j !== i) : [...hidden, i] });
};Click the list on the right to hide and show. Point at a slice and its row lights up.
onHover(hit, chart) runs once each time the item under the pointer changes, and with null when the pointer leaves the chart. Mouse, touch and keyboard (← →) behave the same. Use it to show details in a side panel instead of a tooltip, to highlight the same row in a table, or to line up other views.
new CompositeChart('#revenue', {
data: { categories: months, series: [thisYear, lastYear] },
tooltip: false, // a side panel instead of the tooltip
onHover: (hit) => (hit ? showMonth(hit.index) : showYear()),
});Move the mouse over the chart. Leave it and the panel goes back to the year's total.
hit has only index and label. Read the values from your data by index.sync, only the chart the user points at calls onHover; the crosshairs that follow it don't.Without any setup the chart reads the text color, font and background of its element and derives grid and axis colors from them. So charts fit light and dark pages as they are, and re-read the theme when the OS switches dark mode. Override only what you want with CSS variables.
.dashboard {
--aeriz-color-1: #64c8ff; /* palette: --aeriz-color-1 … 12 */
--aeriz-color-2: #10b981;
--aeriz-text: #e7eef5; /* default: the element's color */
--aeriz-grid: rgba(100, 200, 255, 0.08);
--aeriz-font: 'Inter', sans-serif; /* default: the element's font-family */
--aeriz-font-size: 12px;
--aeriz-line-width: 2;
--aeriz-bar-radius: 4;
--aeriz-tooltip-bg: rgba(0, 0, 0, 0.9);
}If a script changes the variables, call chart.render(). To recolor one chart, use the colors: ['#f00', '#0f0'] option. To color a single bar, put color on its row.
| Variable | Default |
|---|---|
--aeriz-text | the element's text color |
--aeriz-muted · --aeriz-grid · --aeriz-axis | the text color at 62% · 9% · 30% |
--aeriz-bg | the nearest opaque background |
--aeriz-font · --aeriz-font-size | the element's font · 11 |
--aeriz-accent | #64c8ff (loading spinner) |
--aeriz-line-width · --aeriz-point-radius · --aeriz-bar-radius | 2 · 3 · 3 |
--aeriz-tooltip-bg · --aeriz-tooltip-fg | dark background · white text |
--aeriz-surface | transparent (canvas background) |
--aeriz-color-1 … 12 | the 8 PALETTE colors |
format formats values (tooltips and the value axis); labelFormat formats labels (x-axis labels and tooltip titles). There are no per-axis format options.
{ format: { style: 'currency', currency: 'USD' } } // $1,234.00
{ format: { style: 'percent' } } // 0.25 → 25%
{ format: (v) => v.toFixed(1) + '°C' } // a function
{ labelFormat: (t) => new Date(t).getHours() + 'h' } // time-axis labels12K, Korean 1.2만). To pin one, pass a function: format: (v) => v.toLocaleString('en-US')format per series, and the axis that series sits on uses it too.legend: false; hidden: [1] starts with that item hidden. To do something else on a click, see Legend events.tooltip: false; for your own content and for links or buttons, see Your own tooltip content and Links and buttons in tooltips.onClick and Esc to close. Tab moves into a tooltip's links and buttons. The value read is announced to screen readers.onClick(hit, chart) runs only when an item is clicked. hit has index, label, value, series (series index) and row (the item you passed in); hierarchies add path (the names from the top). The click that ends a zoom or brush drag doesn't count as an item click.new BarChart(el, {
data: rows,
title: 'Sales by month', // the name screen readers read
onClick: (hit) => openDetail(hit.row),
});chart.setState('loading', 'Loading…');
chart.setState('error', 'Network error');
chart.setState('empty'); // emptyText (default 'No data')
chart.setState(null); // closeEmpty data shows emptyText by itself and clears when data arrives. Animation starts when the chart scrolls into view, turns off with animate: false, and is always off for users with "reduce motion" turned on.
Every option has a default, so pass only what you need. Options for one chart type are under Chart options.
| Option | Type | Default | Description |
|---|---|---|---|
data | depends on the chart | — | see Data shapes |
title | string | the chart type's name | the name screen readers read; Gauge shows it below the value |
colors | string[] | CSS variables or PALETTE | this chart's colors (an object for Heatmap and Waterfall) |
format | Intl options | (v) => string | browser language | number format for tooltips and the value axis |
labelFormat | (label) => string | — | x-axis labels and tooltip titles (charts with axes) |
min · max | number | from the data | value-axis range (charts with axes, Gauge, Realtime) |
legend | boolean | shown for several series | false hides it |
hidden | number[] | [] | positions of the legend items to hide; legend clicks update it (charts with a legend) — Legend events |
tooltip | boolean | { render?, actions? } | true | false turns it off. render: the content, actions: links and buttons — Custom content · Links and buttons |
animate | boolean | true | animate the first draw and changes |
emptyText | string | 'No data' | text when there is no data |
onClick | (hit, chart) => void | — | an item was clicked or Enter was pressed |
onHover | (hit | null, chart) => void | — | the item under the pointer changed; null when it leaves — Side panel |
onLegend | (index, visible, chart, event) => void | — | a legend item was clicked, before it changes; event.preventDefault() keeps it as it is |
annotations | { x | y, label?, color?, axis? }[] | — | reference lines, target lines and bands (charts with a value axis) — Annotations |
zoom | boolean | 'brush' | false | zoom and pan, or a brush (Line, MultiLine, Area, Composite, Candlestick, Scatter) — Zoom |
range | [from, to] | null | everything | the x range to show (the charts above, with or without zoom) |
onZoom | (range, chart) => void | — | the user changed the range |
sync | string | — | share the crosshair and range with charts of the same name — Sync |
| Method | Returns | Description |
|---|---|---|
update(options) | this | merges options (data included) and redraws with animation |
setState(state, text?) | this | shows 'loading' · 'empty' · 'error'; null closes it |
render() | this | re-reads CSS variables and draws the final frame now (off-screen, print, export) |
destroy() | — | removes listeners and observers and restores the element |
push(v | v[]) · clear() | this | RealtimeChart only: add one sample (an array for several series) · remove all |
The package also exports Chart (extend it to write your own chart) and the default colors PALETTE. Nothing else.
| Chart | Options |
|---|---|
| One-value-per-item charts | label, value: functions that read a row ((row) => row.sales) |
| Bar | dataLabels: true or (value, row, index) => string. A row's low · high draw an error bar |
| Line | curve: 'smooth' · 'linear' · 'step', xScale: 'category' · 'time', yScale: 'linear' · 'log', fill, points. A row's low · high draw a band |
| MultiLine | curve, xScale |
| Area | stacked: true · false · 'percent' |
| StackedBar | stacked: true (default) · 'percent' |
| Bubble | radius: [min, max] px (default [4, 32]) |
| Pie | innerRadius: share of the radius 0–0.9 (0.6 = donut), center: center text or false |
| Polar | scale: 'sqrt' · 'linear' |
| Radar | max (the outer ring's value) |
| Gauge | min (0), max (100), unit |
| Heatmap | colors: { low, high } |
| Waterfall | colors: { up, down, total } |
| Funnel · Treemap · Sunburst | labelColor (#fff). Sunburst: center, the text in the middle, or false |
| Sparkline | fill, lastDot, min, max |
| Realtime | window (200), min, max |
| Composite | per series type: 'bar' · 'line' · 'area' · 'scatter', axis: a value-axis name ('left' by default), format, low · high; on the chart xScale, stacked: true · 'percent' |
| Candlestick | xScale, colors: { up, down } (#10b981 · #ef4444) |
| Network | radius: [min, max] px (default [4, 16]) |
| Map | geo: GeoJSON, projection: 'mercator' · 'equirectangular', scale: 'linear' · 'log', colors: { low, high }, labelFormat: region names |
TypeScript types are included, so your editor shows each chart's options and data shape as you type.
2.0 keeps one way to do each thing. When you use a 1.x name, the console tells you the new one, so open your pages and follow the warnings. To stay on 1.x, install npm install @aeriz/chart@1.
// 1.x
new MultiLineChart(el, { categories, series, interpolation: 'linear', yTickFormat: (v) => v + '%' });
chart.setData(rows);
chart.setLoading('…');
gauge.setValue(80);
// 2.0
new MultiLineChart(el, { data: { categories, series }, curve: 'linear', format: (v) => v + '%' });
chart.update({ data: rows });
chart.setState('loading', '…');
gauge.update({ data: 80 });| 1.x | 2.0 |
|---|---|
setData(d) | update({ data: d }) |
setLoading · setEmpty · setError · clearState | setState('loading' | 'empty' | 'error' | null, text?) |
invalidate() | render() |
Gauge setValue(v) · value · label | update({ data: v }) · data · title |
categories · series · layers · axes (options) | data: { categories, series } |
Heatmap xLabels · yLabels · data: [{ x, y, value }] | data: { x, y, values: [[…]] } |
Realtime series · windowSize · yMin · yMax · waitingText | data: { series } · window · min · max · emptyText |
ariaLabel | title |
palette · color | colors |
colorLow/High · colorUp/Down/Total | colors: { low, high } · colors: { up, down, total } |
yTickFormat · xTickFormat | format · labelFormat |
yLeftTickFormat · yRightTickFormat | format on each series |
interpolation ('step-after' …) | curve: 'smooth' · 'linear' · 'step' |
yMin · yMax | min · max (every chart with axes) |
minRadius · maxRadius | radius: [min, max] |
centerLabel: false · totalLabel | center: false · center: 'text' |
Pie innerRadius: 80 (px) · 'auto' | innerRadius: 0.6 (a ratio only) |
Waterfall isTotal | total |
Scatter r · Bubble z | size |
Composite dots values: [{ x, y }] | values: [value | null], like every series |
[['Jan', 64], …] pairs | { Jan: 64 } or [{ label, value }] |
Sparkline | SparklineChart |
onClick(hit, point, chart) (also called with null) | onClick(hit, chart) (only on an item); hit.data → hit.row |
React · Vue <AerizChart type={BarChart} options={…} /> | <BarChart data={…} {…options} /> (from /react · /vue) |
Svelte use:aeriz={{ type: BarChart, … }} · onReady | use:barChart={{ … }} · chartOf(node) |
jQuery install($) · .aerizChart(PieChart, …) · 'setData' | install($, { PieChart }) · .aerizChart('pie', …) · 'update' |
getFPS · getActiveCount · scheduler · Engine · drawCartesian · toRows · math | not exported (internal) |