HeatmapChart

A row × column grid encoding magnitude as brand-color intensity, drawn as tiles or dots.

stable

Quick Preview

Best days & times to list

Listing success · last 90 days

HighLow

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

HighLow

Best days & times to list

Listing success · last 90 days

HighLow

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

HighLow

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/APITypeDefaultDescription
datareadonly T[]requiredOne row per row/column pair that has a value.
rowKey, columnKeystring or number fields of TrequiredRow and column category fields.
valueKeynumeric field of TrequiredValue encoded as intensity.
ariaLabelstringrequiredAccessible chart name.
type"cells" | "dots""cells"Filled tiles, or dots whose radius and opacity scale with value.
rows, columns(string | number)[]first-seen orderExplicit axis order; pairs outside it are omitted.
domain[number, number]zero (or a lower minimum) to the largest valueRange the five tiers divide into fifths.
size"sm" | "md" | "lg"inherited, otherwise "md"Cell size and type (HEATMAP_CHART_LAYOUT).
valueLabelsbooleanfalseValue inside every cell (cells only).
legendbooleantrueVertical tier legend beside the grid.
legendLabels{ high?, low? }High / LowLegend end labels.
tooltipbooleantrueHover and keyboard tooltip.
formatValue(value: number) => stringen-NG numberCell labels and tooltip values.
formatRow, formatColumn(value) => stringStringAxis labels.
emptyMessageReactNode"No data to display"Shown when no valid values exist.
Chart host propssee Chart-initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. Width and height come from the grid.
HeatmapChartLegendtype?, 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_SCALEhelpers-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 valueLabels for small grids.
  • Keep legend on whenever the scale's bounds are not stated elsewhere on the page.

On this page