Geoms

A geom is a factory geom(channels, options?) that returns a Geom<T>. Add geoms with .layer(...); multiple layers stack in declaration order. Every channel is an Aes<T, V> — a column name, an accessor, or a constant.

All geoms below are exported from insomni-plot:

aggregate, area, band, bar, boxplot, connectedScatter, histogram, interval, line, point, ribbon, ridgeline, rug, rule, smooth, statRolling, text, tile, violin.

point

Scatter / bubble marks. x and y are required.

Channel	Type	Required
x, y	number | Date	yes
color	any (categorical or continuous)	no
size	number	no
shape	categorical → shape palette	no
alpha	number	no
borderStyle	categorical → solid | open | dashed | dotted	no
overlayGlyph	categorical → secondary glyph	no
overlayScale	number	no

Options include fill, radius, stroke, strokeWidth, shape (PointShapeKind), borderStyle, overlayGlyph, overlayScale, label.

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

plot<Row>({ data }).layer(
  point({ x: "weight", y: "mpg", color: "origin", size: "hp" }, { radius: 3 }),
);

line

Connected polyline. A color channel splits the data into one stroke per category; order controls vertex order.

Channel	Type	Required
x, y	number | Date	yes
color	categorical	no
order	number | Date	no

Options: stroke, strokeWidth, curve (LineCurve), curveSamples, dashPattern, dashStyle (dashed \| dotted), nearestX, label.

import { line } from "insomni-plot";

plot<Row>({ data }).layer(
  line({ x: "date", y: "price", color: "ticker" }, { curve: "monotone-x" }),
);

connectedScatter

A line ordered by a third variable, optionally topped with points. Returns the composed line + point geoms.

Channel	Type	Required
x, y	number | Date	yes
order	number | Date	yes
color	categorical	no
size, alpha	number	no
shape	categorical	no

Options: line (LineOptions), point (PointOptions or false for a bare path).

area

Filled area from a baseline. A single y column draws 0 → y; an array of column keys draws a stacked area keyed by column name.

Channel	Type	Required
x	number | Date	yes
y	number | Date or (keyof T)[]	yes
color	categorical	no

Options: fill, stroke, strokeWidth, position ("identity" / "stack" / "fill"), order (StackOrder), nearestX, label.

import { area } from "insomni-plot";

plot<Row>({ data }).layer(area({ x: "date", y: ["us", "eu", "asia"] }, { position: "stack" }));

bar

Categorical bars. A single y column draws one bar per category; an array of column keys draws multi-series bars (position: stack / dodge / fill / identity). Orientation is auto-detected from scale types (band axis = category axis) and can be forced with orientation.

Channel	Type	Required
x	string | number | Date	yes
y	string | number | Date or (keyof T)[]	yes
color	categorical	no

Options: orientation, fill, stroke, strokeWidth, cornerRadius, borderStyle, position (BarPosition), order, groupPadding, showTotals, showValues, labelColor, labelFontSize, label.

import { bar } from "insomni-plot";

plot<Row>({ data }).layer(
  bar({ x: "quarter", y: ["q1", "q2", "q3", "q4"] }, { position: "dodge" }),
);

histogram

Bins one numeric variable. Provide exactly one of x (vertical bars) or y. A color channel splits the sample into per-group bins.

Channel	Type	Required
x or y	number	one of
color	categorical	no

Bin selection (in priority order): breaks → binwidth → bins → rule (sturges / rice / scott / fd). Other options: domain, nice, closed, y measure (count / frequency / density / proportion), position, mirror, fillAlpha, fill, stroke, strokeWidth, cornerRadius, gap, groupPadding, showCounts.

import { histogram } from "insomni-plot";

plot<Row>({ data }).layer(histogram({ x: "weight" }, { rule: "fd", y: "density" }));

smooth

A regression fit with an optional confidence ribbon. One curve per color group.

Channel	Type	Required
x	number | Date	yes
y	number	yes
color	categorical	no

Options: method (SmoothMethod — "lm" default, "poly", "loess"), degree, span, ci (true = 95%, a number for another level, false for none), samples, stroke, strokeWidth, ribbonFill, ribbonOpacity, label, nearestX.

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

plot<Row>({ data })
  .layer(point({ x: "weight", y: "mpg" }))
  .layer(smooth({ x: "weight", y: "mpg" }, { method: "loess", span: 0.6 }));

statRolling

A rolling-window statistic (moving average and friends) drawn as a line.

Channel	Type	Required
x	number | Date	yes
y	number	yes
color	categorical	no

Options: window (RollingWindow — required), statistic (default "mean"), axis, filter, curve, stroke, strokeWidth, dashStyle, nearestX, label.

ribbon

A filled band between two y-bounds at each x.

Channel	Type	Required
x	number | Date	yes
y0, y1	number | Date	yes

Options: fill, stroke (both accept a Color or a theme accent key), strokeWidth, fillAlpha, label.

interval

Error bars / range marks. Bind either (yMin, yMax) for vertical intervals (then x is required) or (xMin, xMax) for horizontal (then y is required) — not both.

Channel	Type	Required
x	number | Date	when yMin/yMax set
y	number | Date	when xMin/xMax set
yMin, yMax	number | Date	vertical pair
xMin, xMax	number | Date	horizontal pair
color	categorical	no

Options: stroke (Color or accent key), strokeWidth, caps, capWidth, label.

band

A static reference band spanning an x- or y-range. Channels take a [start, end] tuple, not a data column.

Channel	Type	Required
x	[number | Date, number | Date]	one of
y	[number | Date, number | Date]	one of

Options: fill / stroke (Color or accent key), strokeWidth, alpha, label, labelColor.

rule

A reference line at a constant value. x draws a vertical line; y a horizontal one.

Channel	Type	Required
x or y	number | Date	one of

Options: stroke (Color or accent key — positive / negative / warn / info), strokeWidth, dashPattern, label, labelColor, labelInset.

rug

Marginal tick marks along the axes. side defaults to whichever channels are wired.

Channel	Type	Required
x	number | Date	no
y	number | Date	no
color	categorical	no

Options: side ("x" / "y" / "both"), length, strokeWidth, stroke, opacity, label.

text

Per-row text labels.

Channel	Type	Required
x, y	number | Date | string	yes
text	string	yes

Options: fontSize, color, align, offsetX, offsetY, box (rounded-rect background), collisionMode ("none" / "hide" / "stagger"), collisionPadding, label.

tile

Heatmap cells. fill is typically a numeric column driving the color scale (the legend renders as a continuous color bar); omit it and pass options.fill for a constant.

Channel	Type	Required
x, y	string | number | Date	yes
fill	any (continuous)	no

Options: fill, padding / paddingX / paddingY, stroke, strokeWidth, cornerRadius, showValues, labelColor, labelFontSize, minLabelCellPx, cellWidth, cellHeight, na, label.

boxplot

Box-and-whisker summary per category. The band axis is the category; the other is the distribution. A color channel dodges side-by-side within each band.

Channel	Type	Required
x	string | number | Date	yes
y	string | number | Date	yes
color	categorical	no

Options include orientation, width, varwidth, whisker (WhiskerRule), quantile (QuantileMethod), notched, notchWidth, points (PointsMode — "auto" / "always" / "none"), pointsThreshold, pointJitter, outliers, fill, fillAlpha, stroke, strokeWidth.

violin

KDE density per category, optionally with an inner annotation.

Channel	Type	Required
x	string | number | Date	yes
y	string | number | Date	yes
color	categorical	no

Options include orientation, width, bandwidth (KdeBandwidth), gridSize, kernel (KdeKernel), trim, scale ("width" / "area" / "count"), inner ("none" / "box" / "quartile" / "stick"), points, fill, stroke, showCounts.

ridgeline

Stacked, overlapping density ridges — one row per category. Provide a numeric value on x or y; the other axis carries the row category.

Channel	Type	Required
x, y	string | number	yes (one numeric, one category)
color	categorical	no

Options include orientation, geom ("kde" / "histogram"), overlap, scale, KDE/histogram pass-throughs, fillMode ("solid" / "gradient"), gradient, inner, baseline.

aggregate

Bins along an axis and reduces each bin to a summary, rendering an inner geom. Falls back to the raw geom when bins are too sparse (dissolveAt).

Channel	Type	Required
x, y	number | Date	yes

Options: binBy, binSize ("auto" default), summary (scalar like "mean" / "median", or a bundle like "mean+ci" / "median+iqr"), filter, dissolveAt, geom ("point" / "line" / "bar" / "interval" / "ribbon"), fill, stroke, radius, curve, ciLevel, caps, capWidth, fillAlpha, label.

import { aggregate } from "insomni-plot";

plot<Row>({ data }).layer(
  aggregate(
    { x: "timestamp", y: "latency" },
    {
      summary: "mean+ci",
      geom: "ribbon",
    },
  ),
);

See also

• Scales & aesthetics — how channels map to scales, and the categorical channels (shape, borderStyle, overlayGlyph).
• Axes & coordinates — axis config and coordinate systems.