Heatmap Chart

Demo & usage

More examples

When to use

• Showing intensity across two categorical dimensions (hour × day, region × metric).
• You want to spot hot/cold patterns in a matrix at a glance.
• For date-based daily activity, use the Heatmap Calendar.

Async states

• loading
• empty
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `cells`, `loading` and `error`.
• Set `filtered` when a search or filter is active. It is the difference between "you have no orders" and "no orders match this filter" — telling a customer with 4,000 orders the first one reads as a bug.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Four variants and nine colour schemes: three perceptually uniform ramps (viridis, magma, cividis) and six single-hue ones. The uniform three run dark-to-bright already, so they are not re-picked for the dark glow variant — doing that would break the very uniformity they are chosen for.
• Configurable cell shape and scale.
• Ambient glow on hover.
• `valuePolicy` decides what happens to a square whose reading this chart cannot plot — `NaN` from a blank source cell, `Infinity` from a division by zero. A negative is not one of these: this is a colour ramp, so −12 °C sits on it perfectly well. `render` (default) draws the square as missing — a hatch, plus a key for the hatch in the legend — which is the honest answer a pie cannot offer, because a matrix already has a way to say "this square has no colour". `omit` leaves a hole and discloses the count; `reject` refuses the matrix. `clamp` is not offered: a missing reading pushed to 0 lands on a real point of the ramp and looks like a measurement.

Best practices

• Do: Pick a perceptually uniform colorScheme — viridis, magma or cividis — so intensity reads linearly. Each is eleven stops sampled from the published matplotlib tables, so every tenth of the ramp is an even step (within ±8%) in CAM02-UCS lightness, the space they were designed in; the spec recomputes it. They used to be three stops joined in sRGB, which kept the ends right and bent the middle — viridis's dark end rose a quarter as fast as its centre. This advice used to have nothing to point at: the six named hues are single-hue lightness ramps, better than a rainbow but not evenly spaced in perceptual terms, so an equal difference in value did not produce an equal difference in appearance and the middle of the scale compressed.
• Do: Reach for cividis when the reader may have a colour-vision deficiency, and for viridis on anything where magnitude has to be judged from colour rather than the hot corner merely spotted. All three stay monotonic in greyscale, so they survive being printed — a ramp that is not stops encoding magnitude the moment it leaves the screen.
• Tip: The default stays blue rather than moving to viridis. A default is the one thing a host cannot opt out of having already shipped, and changing it would restyle every existing dashboard without anybody asking.
• Do: Provide min/max labels or a legend for the color scale.
• Tip: Enable `showValues` for small matrices where exact numbers matter.

Accessibility

• Each cell is a keyboard-focusable `role="button"` with a row/column/value `aria-label`; the grid is a labelled `role="group"`.
• Tooltip content is available on focus and Enter/Space emits `cellSelect`. Cells expose row, column and value.
• A missing square announces "no reading" rather than a number, and is a focus stop like any other — the hatch is the visual half of the same fact, and the legend key names it in words so it is not colour-only.
• Whatever `valuePolicy` did is stated under the grid, not only in `console.warn`. One `NaN` used to reach the ramp interpolator and come back as the literal `#NaNNaNNaN`, which browsers discard — blanking the entire matrix with no error anywhere.
• Every square is its own tab stop, so a large matrix is a long walk by keyboard. Past `cellCeiling` squares (2,500 — a 50 × 50 grid) a note under the grid names the real count and that cost; the chart still draws every square. Aggregate or split a matrix that has to be navigable.