Learn the tool by building with it.

Describe the result, not the drawing steps

The options tree keeps data, layout, labels, and behavior together. Global defaults go in plotOptions.series; type-specific defaults go in plotOptions.column, plotOptions.line, and so on.

new FacetViz('#chart', {
  chart: { type: 'column' },
  xAxis: { categories: ['A', 'B', 'C'] },
  plotOptions: { column: { borderRadius: 5 } },
  series: [{ name: 'Orders', data: [12, 18, 15] }],
});

Choose from 35+ focused renderers

Cover comparison, change, distribution, relationship, flow, hierarchy, schedules, finance, and compact KPI views. Set one default type on the chart or override it per series.

Group, stack, normalize, or overlap

Series group side-by-side by default. Use 'normal' for totals, 'percent' for shares, a stack id for independent groups, or grouping: false for target-vs-actual overlays.

plotOptions: {
  column: { stacking: 'percent' },
},
series: [
  { name: 'Organic', data: [40, 55, 62] },
  { name: 'Paid', data: [60, 45, 38] },
]

Categories, numbers, dates, and logs

Axes infer sensible scales, while type makes intent explicit. Add a crosshair, reverse a scale, rotate crowded labels, or place reference lines and bands at domain values.

xAxis: {
  type: 'datetime',
  crosshair: true,
},
yAxis: {
  type: 'log', min: 1,
  labels: { format: '{value:,.0f}' },
}

Start from a theme, then override tokens

Use 'light', 'dark', 'high-contrast', or 'pastel'. A custom theme can extend a built-in and define palette, typography, axes, labels, legend, and tooltip colors.

theme: {
  base: 'dark',
  backgroundColor: '#0b1021',
  colors: ['#00f5d4', '#f15bb5', '#fee440'],
  axis: { gridLineColor: '#1c2540' },
}

Reveal detail without crowding the chart

Place the legend on any side and click its items to toggle series or slices. Tooltips can be shared across a category or customized per series with a format string or formatter.

legend: { layout: 'vertical', align: 'right' },
tooltip: {
  shared: true,
  format: '<b>{series.name}</b>: {y:$,.0f}',
}

Move from overview to detail

Enable drag-to-zoom on numeric or datetime axes. For categorical detail, connect a point’s drilldown id to a child series; FacetViz adds the return path.

chart: { type: 'line', zoom: 'x' },
xAxis: { type: 'datetime', crosshair: true },

// Or on a point:
{ name: 'Apples', y: 12, drilldown: 'apples' }

Connect chart gestures to your product

Handle point clicks, hover, legend toggles, render cycles, and drill-down. Event payloads include series, point indexes, coordinates, the original point object, and DOM event.

const chart = new FacetViz('#chart', options);

const off = chart.on('point:click', (event) => {
  openDetails(event.point.customerId);
});

// Later: off();

Change the config when space changes

The SVG never overflows its parent and charts reflow when their container resizes. Add size conditions to hide secondary content, rotate labels, or simplify a small view.

responsive: [{
  condition: { maxWidth: 480 },
  options: {
    legend: { enabled: false },
    xAxis: { labels: { autoRotation: [0, -45] } },
  },
}]

Switch dense series to canvas automatically

Point and line series cross a configurable threshold into canvas rendering, with line decimation for dense signals. SVG export still embeds the canvas image.

chart: {
  type: 'scatter',
  boost: { enabled: true, threshold: 1500 },
},
series: [{ data: oneHundredThousandPoints }]

Catch bad configuration before it renders

Validate unknown input without side effects, or enable automatic checks on construction and data updates. Issues include a stable code, severity, option path, message, and suggested fix.

import { validateChartOptions } from 'facetviz';

const result = validateChartOptions(candidate);
if (!result.valid) console.table(result.errors);

new FacetViz('#chart', { ...options, validation: { mode: 'error' } });

Ship only the renderer families you use

The full entrypoint registers every chart type. For a smaller application bundle, import the core and register selected series families through side-effect imports.

import { FacetViz } from 'facetviz/core';
import 'facetviz/series/line';
import 'facetviz/series/pie';

new FacetViz('#chart', options);

Update a series without rebuilding your UI

Replace, append, or batch several changes into one render. maxPoints makes a rolling window simple, and nested batches roll back safely if an update fails.

chart.appendData(0, incomingPoints, { maxPoints: 120 });

chart.batchUpdate(() => {
  chart.setData(0, revenue);
  chart.update({ title: { text: 'Live revenue' } });
});

Export the chart your user already sees

Serialize a standalone SVG, trigger SVG or PNG downloads, or receive a PNG Blob for your own upload and sharing flow.

const svg = chart.getSVG();
chart.downloadSVG('quarterly-revenue.svg');
chart.downloadPNG('quarterly-revenue.png', 2);

const blob = await chart.toPNGBlob(2);