Heatmap

The Heatmap component (ui:heatmap) renders a 2D grid of color-coded cells. It is designed for dense tabular data where the pattern — which rows run hot, which cells are outliers — is the insight.

Pick a sequential scale for non-negative data (contribution counts, latencies, freshness) and a diverging scale for signed data centered on a midpoint (deltas, sentiment, correlations).

Example — sequential scale

View Glyph Markdown source

```ui:heatmap
title: Data freshness across leaders
rows: [Alice, Bob, Carol, Dave]
cols: [Mongo, Sheets, HubSpot, GitHub, Sentry]
values:
  - [2, 8, 0.5, 1, 3]
  - [4, 1, 2, 12, 0.5]
  - [1, 0, 6, 3, 18]
  - [24, 1, 2, 4, 2]
scale: sequential
domain: [0, 24]
unit: hours
showValues: true
legend: true
```

Example — diverging scale with null cells

Use a diverging scale when values are signed around a midpoint. Cells with no data render with a diagonal-stripe pattern so that “unknown” is visually distinct from zero.

View Glyph Markdown source

```ui:heatmap
title: Feature correlations
rows: [revenue, signups, retention, churn, nps]
cols: [revenue, signups, retention, churn, nps]
values:
  - [1, 0.82, 0.65, -0.54, 0.41]
  - [0.82, 1, 0.58, -0.47, null]
  - [0.65, 0.58, 1, -0.71, 0.52]
  - [-0.54, -0.47, -0.71, 1, -0.39]
  - [0.41, null, 0.52, -0.39, 1]
scale: diverging
domain: [-1, 1]
showValues: true
legend: true
```

Properties

Property	Type	Required	Default	Description
title	string	No	—	Optional heading above the grid.
rows	string[]	Yes	—	Row labels (left edge).
cols	string[]	Yes	—	Column labels (top edge).
values	(number | null)[][]	Yes	—	Row-major matrix; dimensions must match rows.length × cols.length.
scale	'sequential' | 'diverging'	No	'sequential'	Color ramp style.
domain	[number, number]	No	auto	Min/max used for color scaling. Auto-computed from data when omitted.
unit	string	No	—	Suffix shown next to values in tooltips, the legend, and aria-labels.
showValues	boolean	No	false	Draw numeric values inside each cell.
legend	boolean	No	true	Render a horizontal color bar under the grid.

Color semantics

• Sequential — a single-hue gradient from --glyph-surface to --glyph-palette-color-1. Use for non-negative data.
• Diverging — a two-hue gradient: --glyph-palette-color-1 → --glyph-surface → --glyph-palette-color-2. Use for signed data.
• Null cells — rendered with a diagonal-stripe pattern on --glyph-surface-muted so that missing data reads differently from zero.
• Cell text contrast is chosen automatically via perceived luminance (0.299·r + 0.587·g + 0.114·b, threshold 128) so labels remain readable on both light and dark cells.

Accessibility

• The outer region uses role="region" with the title as its accessible name.
• The inner table is role="grid" with <th scope="col"> / <th scope="row"> headers.
• Every cell has an aria-label="{row}, {col}: {value} {unit}" so the data is readable by assistive technology even when showValues is off.
• The legend is role="img" with aria-label="Color scale: {min} to {max} {unit}".
• Color is never the sole differentiator — enable showValues: true when the numeric value is load-bearing for comprehension.