Bar chart

Sand grains pour in from above and settle into bars. Optionally a solid fill + border resolves as the sand fades out. Supports live update / add / remove with a smooth morph, plus hover interaction.

Constructor

new BarChart(host: HTMLElement, config: BarChartConfig)

Mounts a canvas into host and boots the best available backend (WebGPU → Canvas2D). The only required field is data; everything else has a default. Await chart.whenReady() if you need the backend initialized before your next step.

Config — top level

grain — grain appearance

animation — timing

interaction.hover

interaction.dim — legend click-to-isolate tuning

Has no effect until a series is actually isolated — via a click on an legend.interactive entry, or a call to focusSeries(index). Both are the same code path, so a click and a programmatic call always agree and both fire seriesFocus.

new BarChart(el, {
  data,
  legend: { show: true, interactive: true },   // click an entry to isolate it
  interaction: { dim: { opacity: 0.1, fadeMs: 300 } },
});

axes.x / axes.y — AxisConfig

Each axis is off until you set show: true. Both axes share the same shape.

legend — LegendConfig

currentValue

bars — solid fill + border BarStyleConfig

Off by default; a config without bars renders as pure sand. When present, a solid shape crossfades in as the grains fade out. Fill and border always use the bar's series color — only opacity, width and which sides are configurable.

bars.fill

bars.border

bars.reveal — particle→solid crossfade

fps — FpsConfig

panZoom — PanZoomConfig

Drag to pan, wheel / on-chart buttons to zoom, or drive it from code via the shared PanZoomable interface — one transform moves the grains and all chrome together. Off by default.

new BarChart(el, {
  data,
  panZoom: { enabled: true, axes: 'x', maxZoom: 20,
    controls: { position: 'top-right' } },
});

Methods

Events

hover carries { bar: BarMeta | null } (null on pointer-leave).

// BarMeta — metadata for one drawn bar
{
  barId: number;
  seriesIndex: number;
  seriesKey: Scalar | undefined;
  xValue: Scalar;         // number | Date | string
  yValue: number;
  x0: number; x1: number;  // layout-space extents [0,1]
  height: number;
  color: RGBA;            // [r,g,b,a] in 0..1
}

seriesFocus fires whenever the isolated series changes — from a legend click or a focusSeries() call, both the same code path.

// SeriesFocusPayload
{
  index: number | null;   // null = every series shown at full opacity
}

Examples

Solid bars that resolve from sand

new BarChart(el, {
  data,
  bars: {
    fill: { opacity: 0.85 },
    border: { top: true, width: 1.5 },   // only the top edge
    reveal: { start: 'afterPour', duration: 600, grainsTo: 0.12 },
  },
});

Axes, grid, legend and value readout

new BarChart(el, {
  data,
  axes: {
    x: { show: true, label: 'Quarter' },
    y: { show: true, ticks: 5, gridLines: true, label: 'Revenue' },
  },
  legend: { show: true, position: 'top', align: 'end' },
  currentValue: {
    show: true,
    format: (bar) => `${bar.xValue}: €${bar.yValue}k`,
  },
});

Live data — update, add, remove

// Set y on existing points (matched by x, and z if given):
chart.update([{ x: 'Q2', z: 'EU', y: 175 }]);

// Append points; new bars grow in:
chart.add([{ x: 'Q3', y: 60, z: 'EU' }, { x: 'Q3', y: 45, z: 'US' }]);

// Remove by {x,z?} match or by index:
chart.remove([{ x: 'Q1' }]);   // drop every series bar at Q1
chart.remove([-1]);          // drop the last point

Reacting to hover

const off = chart.on('hover', ({ bar }) => {
  if (!bar) return;                // pointer left the plot
  tooltip.textContent = `${bar.seriesKey} · ${bar.yValue}`;
});
// later: off();  // unsubscribe

Series dimming — click a legend entry to isolate it

const chart = new BarChart(el, {
  data,
  legend: { show: true, interactive: true },
  interaction: { dim: { opacity: 0.15 } },
});

chart.on('seriesFocus', ({ index }) => {
  readout.textContent = index === null ? 'all series shown' : `isolated: series ${index}`;
});

// Or drive it from code — same effect, same event, as clicking the legend:
clearButton.addEventListener('click', () => chart.focusSeries(null));