Chart API and interactions

Entry points

Browser-only ChartOptions add responsive, progressiveRender, resizeTarget, interactions, and onX event callbacks. progressiveRender: true draws a skeleton phase before a full trace phase. resizeTarget is a DOM Element. Set dimensions explicitly when layout requires fixed pixels; resize(width, height) updates the instance. The optional style argument supplies color/lineWidth Canvas defaults.

Update data and state

Keep the returned instance. render() draws and returns the latest scene; resize(width, height) changes dimensions; updateOptions(partialOptions) applies chart options. Use setData(data) for the single-series form, setTraces(traces) to replace traces, or setTraceData(traceIndex, data) for one trace. appendData(data, { traceIndex, maxPoints }) supports a bounded sliding window. These operations return a scene when they render; methods declared Scene | undefined can return undefined when no valid change is applied.

import { createChart } from "fastplotjs";
const canvas = document.getElementById("chart");
const chart = createChart(canvas, {
  type: "line", engine: "ts",
  data: [{ x: 0, y: 2 }, { x: 1, y: 5 }],
  axes: { show: true },
});
chart.appendData([{ x: 2, y: 3 }], { maxPoints: 100 });
chart.on("dataUpdate", ({ mode, pointCounts }) => console.log(mode, pointCounts));
// On component teardown:
chart.destroy();

getDataState() returns { traceCount, traceData }; setDataState(state, { emit?: boolean }) applies a matching trace topology without replacing styles. getChartState()/setChartState(state, { emit?: boolean }) use ChartState fields chartType, data, viewport, traceVisibility, polarRotation, optional camera3d/cameras3d, dragMode, and optional pointSelection. State inputs and getters are snapshots; incompatible topology or stale state fails. { emit: false } prevents feedback loops when syncing charts while still applying valid state.

getTraceVisibility() returns { traceCount, visibleTraceIndexes, hiddenTraceIndexes }. Use setTraceVisibility(indexes, visible, { emit? }), setTraceVisibilityState(state, { emit? }), or resetTraceVisibility({ emit? }). At least one trace remains visible. getScene() reads the latest scene. Call destroy() when the Canvas leaves the page; subsequent updates are invalid.

Interaction options

All pointer features are opt-in. interactions accepts zoom, pan, polarRotate, camera3d, dragMode, tooltip, crosshair, pointClick, and pointSelection. Boolean true enables a feature's package defaults; an object sets individual fields. dragMode is zoom or pan.

Interaction distances, line widths, marker radii, drag thresholds, and label offsets are Canvas pixels. Degrees appear explicitly in rotation/camera option names. Ratios are unitless; opacity is 0…1. Callback formatters run for display text and should be pure.

Viewport, polar rotation, 3D camera

getViewport() returns x/y axis-id range maps. setViewport(viewport, { activeSubplotId, mode, emit? }) and zoom(viewport, ...) apply ranges. zoomIn/zoomOut take optional subplotId/mode/xAxes/yAxes/emit/factor/xRatio/yRatio. pan uses optional subplotId/mode/xAxes/yAxes/emit/xRatio/yRatio. resetZoom/autoscale use optional subplotId/mode/xAxes/yAxes/emit. getViewportControlState reports which directions/reset/autoscale are available for an external toolbar; its options contain optional zoom/pan/reset/autoscale/panStepRatio. getDragMode()/setDragMode(mode) switch zoom/pan left-drag behavior.

Wheel, drag-box, pinch, pan, and programmatic patches stay in an active subplot and can synchronize compatible named axes through viewportGroup. Axis zoom interactions and zoom helpers are no-ops for bar and polar; direct setViewport() can still update stored viewport state and emit an event. No built-in zoom toolbar is supplied. getViewportControlState() returns canZoomIn, canZoomOut, canPanLeft, canPanRight, canPanUp, canPanDown, canResetZoom, and canAutoscale flags.

getPolarRotation()/setPolarRotation({ startAngleDegrees }, { emit? }) control polar orientation. Experimental 3D uses getCamera3d(subplotId?), setCamera3d(camera, { subplotId, emit? }), orbitCamera3d({ yawDegrees, pitchDegrees, subplotId, emit? }), dollyCamera3d({ factor, subplotId, emit? }), panCamera3d({ xRatio, yRatio, subplotId, emit? }), and resetCamera3d({ subplotId, emit? }). A before-camera event can cancel a change.

const chart = createChart(canvas, {
  type: "line", engine: "ts", data: [{ x: 0, y: 2 }, { x: 1, y: 5 }],
  interactions: { zoom: true, pan: { modifierKey: "shift" } },
});
chart.on("viewportChange", ({ viewportAfter }) => console.log(viewportAfter));
chart.zoomIn({ mode: "x", factor: 2 });
chart.resetZoom();

Tooltip, crosshair, and selected points

interactions.tooltip is disabled by default. Its mode is default/custom; lineMode is points/segments; shared aggregates one visible trace per active subplot and x-axis; sharedXMode is exact (default) or nearest. formatter receives a source-aware ChartTooltipItem with subplotId/traceIndex/traceName/traceColor/pointIndex/xAxisId/yAxisId/x/y/xValue/yValue/xCategory/yCategory/value/z/colorValue/renderedColor/size/sizeValue/radius/opacity/opacityValue/renderedOpacity/normalizedValue/baseline/depth (the latter fields are optional), and optional shared items. It returns text. Tooltip style has text/backgroundColor/borderColor/borderWidth/borderRadius/padding; direct aliases are textStyle/backgroundColor/borderColor/borderWidth/borderRadius/padding. getTooltip(), setTooltip({ subplotId?, traceIndex, pointIndex }, { emit? }), and clearTooltip({ emit? }) manage transient state. A hidden or unrendered target has no hit.

crosshair.mode is x/y/xy; snap is none/nearest. style has color/lineWidth/lineDash. Its label is a boolean or show/formatter/font/lineHeight/color/backgroundColor/borderColor/borderWidth/padding/offset; formatter receives subplot, mode, snap, axis ids, numeric values, labels and default label. getCrosshair(), setCrosshair({ activeSubplotId?, xAxisId?, yAxisId?, xValue, yValue }, { emit? }), and clearCrosshair({ emit? }) manage the overlay.

pointClick emits one source-aware hit. pointSelection.mode is single/multiple; getPointSelection() returns { traceCount, selection, selections? }. setPointSelection(state, { emit? })/clearPointSelection({ emit? }) update persistent 2D highlights. Data changes retain valid identities. No public API returns every original point inside a drawn area, including points omitted by LOD; that source-point area query is planned, not implemented.

Events and callbacks

Subscribe with chart.on("eventName", handler); it returns an unsubscribe function. chart.off(name, handler) removes the same handler. ChartOptions offers a matching onX callback for every event below. A callback payload carries its type and event-specific state; optional source distinguishes pointer, API, legend, keyboard, or data where declared.

Callback names are onRenderStart, onRenderPhase, onRenderEnd, onBeforeRender, onRender, onResizing, onResize, onError, onBeforeZoom, onZoomStart, onZoom, onViewportChange, onZoomEnd, onZoomCancel, onDragModeChange, onPolarRotationChange, onBeforeCamera3dChange, onCamera3dChange, onTooltip, onTooltipClear, onCrosshairChange, onCrosshairClear, onPointClick, onPointSelectionChange, onTraceVisibility, onDataUpdate, and onChartStateChange.

Payload type glossary

These named values complete the event signatures below. AxisInteractionMode is "x" | "y" | "xy". AxisViewportPatch is { xAxes: Record<string, { min, max }>, yAxes: Record<string, { min, max }>, resetXAxes?: string[], resetYAxes?: string[] }, with scalar range endpoints. ChartZoomPointer is Canvas-pixel { x, y }; ChartZoomSelection has start and end pointers. ChartSize is pixel { width, height }. Scene contains dimensions, primitives, and optional 3D metadata.

ChartZoomSource: wheel, drag, pinch, pan, api. ChartZoomCancelReason: prevented, threshold, pointercancel. ChartCamera3dSource: api, pointer, wheel, pinch, keyboard. ChartCamera3dChangeReason: set, orbit, dolly, pan, pan-dolly, reset, rollback. ChartPolarRotationSource: api, pointer. ChartTooltipSource and ChartCrosshairSource: pointer, api. ChartPointSelectionSource: pointer, keyboard, api, data. ChartTraceVisibilitySource: legend, api. ChartDataUpdateMode: setData, setTraces, setTraceData, appendData, setDataState. ChartRenderPhase: skeleton, full.

Exact event payloads

The rows below reproduce the public 0.3.0 event field contracts. Each payload includes the literal type shown by its event name. State objects are described above; optional fields are marked ?. beforeZoom.preventDefault() and beforeCamera3dChange.preventDefault() cancel their respective changes.

All instance methods

The published interface groups methods by purpose. Methods returning Scene | undefined may fail closed on unsupported or unchanged state; getters may return undefined when the relevant state does not exist.

Exact method signatures

This is the public 0.3.0 ChartInstance contract. Scene | undefined means a call may make no valid change; state getters can be undefined when the feature is unavailable or inactive. on() returns an unsubscribe function. Option shapes are described in the sections above and in the published package declarations.

type ChartInstance = {
  render(): Scene;
  resize(width: number, height: number): Scene;
  updateOptions(options: Partial<ChartOptions>): Scene;
  setData(data: DataPoint[]): Scene;
  setTraces(traces: TraceInput[]): Scene;
  setTraceData(traceIndex: number, data: DataPoint[]): Scene;
  appendData(data: DataPoint[], options?: ChartAppendDataOptions): Scene | undefined;
  getDataState(): ChartDataState | undefined;
  setDataState(state: ChartDataState, options?: ChartDataStateUpdateOptions): Scene | undefined;
  getChartState(): ChartState | undefined;
  setChartState(state: ChartState, options?: ChartStateUpdateOptions): Scene | undefined;
  getPointSelection(): ChartPointSelectionState | undefined;
  setPointSelection(state: ChartPointSelectionState, options?: ChartPointSelectionUpdateOptions): Scene | undefined;
  clearPointSelection(options?: ChartPointSelectionUpdateOptions): Scene | undefined;
  setViewport(viewport: AxisViewportState | undefined, options?: ChartViewportUpdateOptions): Scene | undefined;
  zoom(viewport: AxisViewportState, options?: ChartViewportUpdateOptions): Scene | undefined;
  zoomIn(options?: ChartProgrammaticZoomOptions): Scene | undefined;
  zoomOut(options?: ChartProgrammaticZoomOptions): Scene | undefined;
  pan(options?: ChartProgrammaticPanOptions): Scene | undefined;
  resetZoom(options?: ChartViewportScopeOptions): Scene | undefined;
  autoscale(options?: ChartViewportScopeOptions): Scene | undefined;
  getViewportControlState(options?: ChartViewportControlStateOptions): ChartViewportControlState;
  getDragMode(): ChartDragMode;
  setDragMode(mode: ChartDragMode): void;
  getPolarRotation(): ChartPolarRotationState | undefined;
  setPolarRotation(state: ChartPolarRotationState, options?: ChartPolarRotationUpdateOptions): Scene | undefined;
  getCamera3d(subplotId?: string): ChartCamera3dState | undefined;
  setCamera3d(state: ChartCamera3dState, options?: ChartCamera3dUpdateOptions): Scene | undefined;
  orbitCamera3d(options?: ChartCamera3dOrbitOptions): Scene | undefined;
  dollyCamera3d(options: ChartCamera3dDollyOptions): Scene | undefined;
  panCamera3d(options?: ChartCamera3dPanOptions): Scene | undefined;
  resetCamera3d(options?: ChartCamera3dUpdateOptions): Scene | undefined;
  getTooltip(): ChartTooltipState | undefined;
  setTooltip(target: ChartTooltipTarget, options?: ChartTooltipUpdateOptions): ChartTooltipState | undefined;
  clearTooltip(options?: ChartTooltipUpdateOptions): void;
  getCrosshair(): ChartCrosshairState | undefined;
  setCrosshair(position: ChartCrosshairPosition, options?: ChartCrosshairUpdateOptions): ChartCrosshairState | undefined;
  clearCrosshair(options?: ChartCrosshairUpdateOptions): void;
  getTraceVisibility(): ChartTraceVisibilityState;
  setTraceVisibility(traceIndexes: number | number[], visible: boolean, options?: ChartTraceVisibilityUpdateOptions): Scene | undefined;
  setTraceVisibilityState(state: ChartTraceVisibilityState, options?: ChartTraceVisibilityUpdateOptions): Scene | undefined;
  resetTraceVisibility(options?: ChartTraceVisibilityUpdateOptions): Scene | undefined;
  on<Type extends ChartEventType>(type: Type, handler: ChartEventHandler<Type>): () => void;
  off<Type extends ChartEventType>(type: Type, handler: ChartEventHandler<Type>): void;
  getScene(): Scene | undefined;
  getViewport(): AxisViewportState | undefined;
  destroy(): void;
};

Browser, Node, and export

Browser charts need a real Canvas and DOM. The published TypeScript module supports engine: "ts" without extra initialization; auto selects an available compatible engine. Optional Node native and browser WASM engines use initNodePlotEngine/hasNodePlotEngine and initWasmPlotEngine/hasWasmPlotEngine/getWasmPlotEngineStatus/getLastWasmInitError. engine: "rust" requires an initialized compatible capability and fails if unavailable. Experimental 3D remains TypeScript-only for geometry.

import { plot, renderScene3dToSVG } from "fastplotjs";
const options = {
  type: "scatter3d", engine: "ts", width: 640, height: 400,
  data: [{ x: 0, y: 0, z: 0 }, { x: 1, y: 2, z: 1 }],
};
const scene = plot(options); // renderer-neutral primitives and 3D metadata
const svg = renderScene3dToSVG(options); // static SVG string
console.log(scene.primitives.length, svg.length);

renderScene3dToPNG(options) needs the optional native Node addon. It rejects unsupported chart types, dimensions, unavailable native capability, and raster failures with Scene3dNodePngExportError and a typed failure code. Real PNG output has been validated on Windows only; no browser PNG promise follows from the package API. renderToPNG(options) returns UTF-8 JSON scene bytes in a Uint8Array, despite its historical name; it is not a PNG file or general image export. Static exports omit pointer interaction, live camera controls, and hit-testing.

Other package-root exports serve advanced integrations: applyAxisViewportState, mergeAxisViewportState, resolveAxisBoxZoomInteractionPatch, resolveAxisPanInteractionPatch, resolveAxisZoomInteractionPatch, resolveInteractionBindingsFromPlotOptions, resolveSharedAxisInteractionPatch, and viewportStateToAxesOptions are low-level viewport helpers. DEFAULT_TRACE_COLORS is the default palette; getLastLineAxisLayoutDiagnostics is a diagnostic accessor. Scene3dWebgl2CapabilityError and Scene3dNodePngExportError expose typed capability/export failures. Use the chart-instance methods for ordinary browser navigation.