Scatter chart

Sand settles into a small cloud around each point, then a solid marker glyph — circle, triangle, square or asterisk — resolves on top, the scatter analogue of the line chart's solid line and the bar chart's solid border. Both axes are continuous (numeric or time), and a swappable approximation strategy can fit a trend/connector line over each series' cloud.

Constructor

new ScatterChart(host: HTMLElement, config: ScatterChartConfig)

Mounts a canvas into host and boots the best backend (WebGPU → Canvas2D). Only data is required.

Config — top level

Mirrors the line chart's config field-for-field except for data (a MeshDataSet, not a DataSet), pointRadius (new, replaces lineThickness), line → marker, and the new approximation block.

grain

Same shape as the bar chart: sizePx (3), shape ('disc'), settleJitter (0.004). jitter (default 0.6) means something slightly different here — it scales how far grains spread across the point's cloud radius (0 collapses every grain onto the point center, 1 fills the whole pointRadius), the same way it scales the line chart's ribbon width. See bar chart → grain for the other properties.

animation

Same as the bar chart, with the line chart's two three-way twists renamed for markers:

marker — solid glyph MarkerStyleConfig

The scatter analogue of the line chart's solid line / bar chart's solid border. Off by default; a config without marker renders as pure sand. Shape/size cycle per series exactly like colors; the marker always uses the point's series color.

approximation — trend/connector fit ScatterApproximationConfig

Off by default. When set, each series' point cloud is fit independently and drawn as a stroked path once the markers resolve, colored by that series unless color overrides it.

Built-in kinds

Passing an object in place of a kind string plugs in a fully custom fitter without touching the chart:

interface FitPoint { x: number; y: number; }

interface Approximation {
  readonly kind: string;
  fit(points: FitPoint[]): FitPoint[];   // unordered cloud -> ordered path to connect with straight segments
}

Shared blocks

axes, legend, currentValue, fps, interaction.hover and interaction.dim take the same shape the bar chart uses. Full property tables: axes · legend · currentValue · fps · interaction.hover / interaction.dim.

Methods

It also implements the shared PanZoomable interface: getView(), setView(v), panBy(), panTo(), zoomBy(), zoomTo(), resetView(), isPanZoomEnabled().

Events

The hover event carries { point: ScatterMeta | null }, and — unlike the line chart, which highlights the whole hovered series — targets a single point.

// ScatterMeta — metadata for one drawn point
{
  pointId: number;
  seriesIndex: number;
  indexInSeries: number;   // position within its series — the morph identity key
  seriesKey: Scalar | undefined;
  xValue: Scalar;
  yValue: Scalar;
  meshValue: MeshValue | undefined;  // the point's z payload, if any
  cx: number; cy: number;      // layout-space position [0,1]
  color: RGBA;
}

seriesFocus carries { index: number | null } — same shape as the bar chart's. See bar chart → Events.

Examples

Solid markers over a point cloud

new ScatterChart(el, {
  data,
  pointRadius: 0.02,
  marker: { shape: 'circle', size: 7, reveal: { duration: 500, grainsTo: 0.1 } },
  axes: { x: { show: true }, y: { show: true, gridLines: true } },
});

Trend line via least-squares

new ScatterChart(el, {
  data,
  marker: { shape: 'circle', size: 5, opacity: 0.85 },
  approximation: { kind: 'leastSquares', width: 2 },
});

Custom approximation strategy

const movingAverage: Approximation = {
  kind: 'movingAverage',
  fit(points) {
    const sorted = [...points].sort((a, b) => a.x - b.x);
    return sorted.map((p, i) => {
      const window = sorted.slice(Math.max(0, i - 4), i + 5);
      return { x: p.x, y: window.reduce((s, w) => s + w.y, 0) / window.length };
    });
  },
};

new ScatterChart(el, { data, approximation: { kind: movingAverage } });

Per-series marker shapes

new ScatterChart(el, {
  data,   // MeshDataSet: series: [{ key: 'A', points: [...] }, { key: 'B', points: [...] }]
  marker: { shapes: ['circle', 'triangle', 'square'], sizes: [6, 8, 6] },
  legend: { show: true },
});

Streaming: appended points settle without a pour

const chart = new ScatterChart(el, {
  data,
  marker: { shape: 'circle' },
  animation: { enter: 'continue' },   // no pour — marker appears settled
});

setInterval(() => {
  chart.add({ x: Date.now(), y: nextSample() }, 0);   // series 0
}, 1000);

Hover

chart.on('hover', ({ point }) => {
  if (point) label.textContent = `(${point.xValue}, ${point.yValue}) · ${point.seriesKey}`;
});

Series dimming — click a legend entry to isolate it

new ScatterChart(el, {
  data,
  legend: { show: true, interactive: true },
  approximation: { kind: 'leastSquares' },   // trend lines dim along with their series' markers
  interaction: { dim: { opacity: 0.15 } },
});