Events & custom drawing

Every chart in the package inherits one event surface and one drawing API from a common base class. The events are cancellable — a listener can veto the chart's built-in reaction — and the drawing API lets you paint your own annotations on top, in the chart's own coordinates, without forking anything.

Listening

chart.on(event, fn) registers a listener and returns a function that removes it. The handler receives one object carrying the payload's own fields plus the cancellation members — there is no detail wrapper, so a handler written against a payload (e.bar, e.index) reads exactly the same as it always did.

const off = chart.on('click', (e) => {
  console.log(e.meta, e.px, e.button);
  console.log(e.type, e.native, e.cancelable, e.defaultPrevented);
});

off(); // unsubscribe

Cancelling the default

Cancelling stops the chart from acting, not the other listeners from hearing about it — every registered handler still runs. That matters when one part of an app observes an event while another part governs it.

// Read-only chart: keep the view exactly where it was put.
chart.on('pan', (e) => e.preventDefault());
chart.on('zoom', (e) => e.preventDefault());

// Reject data that fails validation — the chart never rebuilds.
chart.on('dataAdd', (e) => {
  if (e.items.some(isOutOfRange)) e.preventDefault();
});

Event reference

These nine are on every chart. Each visual adds its own on top — hover everywhere, plus seriesFocus, seriesChange, select or highlight depending on the chart; see that chart's Events section.

Order of precedence

Charts that expose interaction.mouse hooks (the wind rose and candlestick) now have two override layers. They run in a fixed order, and each can stop the ones below it:

Data events fire first

The three data* events fire before the dataset changes, which is the only point at which a veto can mean anything — a listener that reverted the chart afterwards would still have paid for a rebuild and a visible frame. When a listener cancels, the call returns having done nothing at all.

chart.on('dataAdd', (e) => e.preventDefault());

chart.add({ x: 'F', y: 42 });
chart.getData().points.length; // unchanged

Drawing layers

A layer is a callback invoked once per frame with a 2D context and the projections needed to place things in the chart's own coordinates. Layers paint onto a dedicated canvas above the chart's axes and legend, so they never contend with the chart's own repaint schedule.

The returned handle has id, mutable z and visible, setDraw(fn) to swap the callback in place, and remove(). Adding a layer with an id that is already taken replaces it rather than stacking a second one.

const layer = chart.addLayer((c) => {
  // Mark the mean, in the chart's own data coordinates.
  const a = c.toDevice(0, mean);
  const b = c.toDevice(1, mean);
  c.ctx.strokeStyle = '#ff3b6b';
  c.ctx.lineWidth = 2 * c.dpr;
  c.ctx.beginPath();
  c.ctx.moveTo(a.x, a.y);
  c.ctx.lineTo(b.x, b.y);
  c.ctx.stroke();
}, { id: 'mean', z: 10 });

layer.visible = false;
layer.remove();

The context passed to draw:

Declarative elements

addElement covers the common annotations without writing canvas code. Every element accepts space, stroke, fill, lineWidth, lineDash, opacity, plus the layer options id, z and visible. Widths and dashes are in CSS px and are scaled for you.

// A target band, plus the rule and label that go with it.
chart.addElement({
  kind: 'rect', at: [0, 0.6], width: 1, height: 0.15,
  fill: 'rgba(56,189,248,0.12)',
});
chart.addElement({
  kind: 'line', from: [0, 0.75], to: [1, 0.75],
  stroke: '#38bdf8', lineDash: [4, 4],
});
chart.addElement({
  kind: 'text', space: 'plot', at: [0.02, 0.78],
  text: 'target', fill: '#38bdf8', font: '12px system-ui',
});

Coordinate spaces

Both addLayer's projections and every element take a space, defaulting to 'data':

In React

Every event above is a prop on the React components, and layers have a layers prop. See React → Standard events.

<BarChart
  data={data}
  layers={layers}
  onClick={(e) => e.preventDefault()}
  onDataAdd={(e) => console.log(e.action, e.items)}
/>