HeatmapChart
A row × column grid encoding magnitude as brand-color intensity, drawn as tiles or dots.
Quick Preview
Best days & times to list
Listing success · last 90 days
Usage
import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
import { HeatmapChart } from "@giddaa-housing/ui/heatmap-chart";
<ChartCard>
<ChartHeader><ChartTitle>Listing inquiries</ChartTitle></ChartHeader>
<HeatmapChart
data={[
{ area: "Lekki", month: "Jan", count: 42 },
{ area: "Lekki", month: "Feb", count: 58 },
{ area: "Yaba", month: "Jan", count: 21 },
{ area: "Yaba", month: "Feb", count: 26 },
]}
rowKey="area"
columnKey="month"
valueKey="count"
ariaLabel="Inquiries by neighbourhood and month"
/>
</ChartCard>HeatmapChart encodes a value across two categorical dimensions (rowKey ×
columnKey). Pass one row per pair that has a value; pairs must be unique. Rows
and columns default to first-seen order; pass rows and columns to fix the order
or include categories with no data. Missing pairs show an outlined "no data" cell.
Both types paint one token, bg-brand, at five fixed opacity tiers (8, 22, 44,
70, 100%) for 0–19, 20–39, 40–59, 60–79, and 80–100% of domain, so the
dark-mode swap carries the whole scale. Never use the categorical chart-1…4
tokens here; they encode identity, not amount. Tiles are fixed squares; grids
wider than their container scroll, and row labels stay put while they do. The
vertical legend runs High to Low beside the grid. Compose title and description
with ChartCard.
Examples
Cells and dots
type="cells" (the default) fills each tile as a classic heatmap; type="dots"
scales radius and opacity with value, which reads lighter on sparse grids.
Best days & times to list
Listing success · last 90 days
Best days & times to list
Listing success · last 90 days
Values in cells
valueLabels prints the formatted value inside every cell, for a small, dense
matrix where the reader wants every figure at a glance. Pin domain so a scale
tied to real thresholds is not stretched by whatever range the data covers.
Repayment collection rate
By branch and quarter · % of scheduled repayments collected
Wide grid, no legend
Explicit rows and columns fix order and coverage, domain keeps the scale
comparable across datasets, and legend={false} drops the key when the card
caption already states the scale. Every column label is kept; wide grids scroll
inside the card.
Site visits
By day and hour · sessions, last 30 days
Props
| Prop/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | One row per row/column pair that has a value. |
rowKey, columnKey | string or number fields of T | required | Row and column category fields. |
valueKey | numeric field of T | required | Value encoded as intensity. |
ariaLabel | string | required | Accessible chart name. |
type | "cells" | "dots" | "cells" | Filled tiles, or dots whose radius and opacity scale with value. |
rows, columns | (string | number)[] | first-seen order | Explicit axis order; pairs outside it are omitted. |
domain | [number, number] | zero (or a lower minimum) to the largest value | Range the five tiers divide into fifths. |
size | "sm" | "md" | "lg" | inherited, otherwise "md" | Cell size and type (HEATMAP_CHART_LAYOUT). |
valueLabels | boolean | false | Value inside every cell (cells only). |
legend | boolean | true | Vertical tier legend beside the grid. |
legendLabels | { high?, low? } | High / Low | Legend end labels. |
tooltip | boolean | true | Hover and keyboard tooltip. |
formatValue | (value: number) => string | en-NG number | Cell labels and tooltip values. |
formatRow, formatColumn | (value) => string | String | Axis labels. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid values exist. |
| Chart host props | see Chart | - | initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. Width and height come from the grid. |
HeatmapChartLegend | type?, size?, labels? | - | The tier legend on its own. |
createHeatmapChartDefinition(options) | function | - | Same options plus rowLabels; returns an extensible TanStack definition. |
heatmapTier, measureHeatmapChart, HEATMAP_CHART_PALETTE, HEATMAP_DOT_SCALE | helpers | - | Tier lookup, grid measurement, and the ramp. |
Accessibility
- Provide a meaningful
ariaLabel; focus the chart and use arrow keys to move between cells. The tooltip shows row, column, and value. - "No data" cells are outlined, not filled, so absence is not read as zero.
- Do not communicate magnitude with color alone; keep the legend, or
valueLabelsfor small grids. - Keep
legendon whenever the scale's bounds are not stated elsewhere on the page.