Components / Charts

DensityChart

A canvas density plot for 10^5 to 10^6 points: a binned heatmap when zoomed out, individual markers when zoomed in, with pan, zoom, hit-test tooltip and a binned table view.

@ruckc/truss-chart Charts

Import

import { DensityChart } from '@ruckc/truss-chart';
import '@ruckc/truss-chart/charts.css'; // series palette

Playground

API

Prop	Type	Default	Description
points	DensityPoint[]	—	Object input, convenient up to ~10^5 points. `group` picks the palette colour of markers and a legend entry (max 8).
xs	ArrayLike<number>	—	Typed-array input for 10^5 to 10^6+ points (used as-is, no copy); wins over `points` when both `xs` and `ys` are set.
ys	ArrayLike<number>	—
groupIds	Uint8Array	—	Optional palette slot (0-7) per point for typed-array input, with `groupNames` naming the slots.
groupNames	string[]	—
title	string	—	Heading text.
subtitle	string	—	Secondary text under the title.
height	number | 'fill'	320	Plot height in px (default 320), or `'fill'` to size to the container's height. `'fill'` measures the parent with a ResizeObserver, so the parent needs a definite height (e.g. `height: 360px`, or a grid/flex track with a fixed size). A parent with `height: auto` collapses to the 120px minimum.
xLabel	string	—
yLabel	string	—
xFormat	(n: number) => string	fmtValue	Formats x-axis numbers.
yFormat	(n: number) => string	fmtValue	Formats value-axis numbers and tooltip values.
cellSize	number	8	Heatmap cell edge in CSS px.
markerThreshold	number	2	Switch from heatmap to individual markers once the visible points number at most this many per heatmap cell. Colour ramp: `--trc-seq-1` … `--trc-seq-9` (low to high count); falls back to a built-in colour-blind-safe ramp.
markerSize	number	3	Marker edge in CSS px.
highlight	DensityHighlight	—	A small set of notable points that stay drawn as markers on top of the heatmap at every zoom, with their own legend entry (toggleable), tooltip hit-testing and a table section. Pass them separately from `points` / `xs`: highlights are not part of the bin counts, so do not repeat them in the main data. Cost is linear in the highlight count per frame, so keep the set small (thousands, not 10^5).
highlightSize	number	9	Highlight marker diameter in CSS px (a surface-coloured halo is added around it).
tooltip snippet	Snippet<[item: DensityHover]>	—	Replaces the default tooltip body. Receives the hovered point (index, x, y, group, highlight flag) or bin (count and ranges).
colorKey	boolean	true	Show a colour key (points per cell, 1 to the busiest cell in view) under the plot while in heatmap mode.
maxCount bindable	number	0	Bindable: the busiest cell's point count in the current view (heatmap mode; 0 while drawing markers). Cells are coloured on a log scale from 1 to this value.
ramp bindable	string[]	[]	Bindable: the resolved heatmap ramp, low to high, as CSS colours (from `--trc-seq-*` or the built-in fallback).