Skip to content
insomni

Plot overview

insomni-plot is a grammar-of-graphics layer over the insomni renderer. You describe a chart declaratively — data, geoms, scales, axes, coordinate system — and it compiles that spec into insomni layers and draws them on the GPU. The builder is immutable: every method (.layer(), .scale(), .axes(), …) returns a new Chart. Nothing renders until you call .mount(canvas), .render(target), or .toSVG().

Quick start

Section titled “Quick start”

plot(spec) takes a PlotSpec<T> — at minimum { data } — and returns a Chart<T>. Geoms (point, line, bar, …) are added with .layer(...).

import { plot, point } from "insomni-plot";


type Row = { weight: number; mpg: number; cylinders: number };


const data: Row[] = [
  { weight: 3.2, mpg: 21, cylinders: 6 },
  { weight: 1.6, mpg: 39, cylinders: 4 },
  { weight: 4.1, mpg: 15, cylinders: 8 },
];


// A WebGPU device is required at mount time.
const device = await (await navigator.gpu.requestAdapter())!.requestDevice();
const canvas = document.querySelector("canvas")!;


const chart = plot<Row>({ data })
  .layer(point({ x: "weight", y: "mpg", color: "cylinders" }))
  .axes({ x: { title: "Weight" }, y: { title: "MPG" } })
  .title("Fuel economy");


const mounted = chart.mount(canvas, { device });


// later — swap the data, then tear down
mounted.setData(data);
mounted.destroy();

Aesthetic mappings

Section titled “Aesthetic mappings”

Aesthetic channels (x, y, color, size, …) accept three forms, unified by the Aes<T, V> type:

  • a column-name string — x: "weight"
  • an accessor (row, index) => value — x: (d) => d.weight * 2
  • a constant — color: "#888" or size: 4

Column-name autocomplete is type-narrowed: a key whose value type doesn’t match the channel’s expected type is rejected at compile time. See Scales & aesthetics for the full channel list.

Two entry points

Section titled “Two entry points”
  • insomni-plot — the grammar API. plot(spec) returns an immutable Chart; compose it with geoms, coordinate systems (coordCartesian / coordPolar / coordRadial), theme, faceting, annotations, color palettes, and statistics helpers (bin, kde, linearFit, …).
  • insomni-plot/core — the lower-level imperative primitives the grammar is built on: scales (linearScale, bandScale, timeScale, logScale, …), axis builders (bottomAxis, leftAxis, …), mark builders (pointMark, lineMark, barMark, areaMark, stacking), legends, color scales/palettes, formatters, the data viewport, and the data navigator. Reach for /core when you want to hand-wire a render without the Chart builder.

Map of this section

Section titled “Map of this section”