Heatmaps and Densities

Heatmaps and density charts answer where values concentrate across two dimensions. A matrix uses explicit row and column categories or intervals. Contours summarize a regular scalar grid or an estimated point field; spatial bins summarize local observations. Choose the representation that preserves the question instead of defaulting to one color per raw observation.

Choose the comparison#

Data and Channels explains interval and color channels. Legends and Color covers continuous color meaning and accessible legend design.

Start with a labeled matrix#

An ordinal matrix uses categories on both axes and one quantitative value for each cell. Direct labels preserve exact values while color makes broad patterns visible.

import { cell, colorGradientLegend, defineChart, text } from '@tanstack/charts'
import { scaleBand } from '@tanstack/charts/scales/band'
import { scaleLinear } from 'd3-scale'
import { quarters, scores, teams } from './data'

export default defineChart({
  marks: [
    cell(scores, {
      x: 'quarter',
      y: 'team',
      color: 'score',
      key: (row) => `${row.team}-${row.quarter}`,
      inset: 1,
    }),
    text(scores, {
      x: 'quarter',
      y: 'team',
      text: (row) => row.score.toFixed(0),
      fill: '#0f172a',
      fontWeight: 650,
    }),
  ],
  scales: {
    x: {
      scale: () => scaleBand<string>().domain(quarters).padding(0.04),
      axis: { label: 'Quarter' },
    },
    y: {
      scale: () => scaleBand<string>().domain(teams).padding(0.04),
      axis: { label: 'Team' },
    },
  },

  color: {
    scale: () =>
      scaleLinear<string>().domain([60, 100]).range(['#eff6ff', '#60a5fa']),
    legend: colorGradientLegend({ label: 'Score', steps: 8 }),
  },
})

export const quarters = ['Q1', 'Q2', 'Q3', 'Q4']
export const teams = ['Core', 'Cloud', 'Mobile']

export const scores = [
  { team: 'Core', quarter: 'Q1', score: 72 },
  { team: 'Core', quarter: 'Q2', score: 78 },
  { team: 'Core', quarter: 'Q3', score: 84 },
  { team: 'Core', quarter: 'Q4', score: 88 },
  { team: 'Cloud', quarter: 'Q1', score: 66 },
  { team: 'Cloud', quarter: 'Q2', score: 74 },
  { team: 'Cloud', quarter: 'Q3', score: 81 },
  { team: 'Cloud', quarter: 'Q4', score: 86 },
  { team: 'Mobile', quarter: 'Q1', score: 82 },
  { team: 'Mobile', quarter: 'Q2', score: 79 },
  { team: 'Mobile', quarter: 'Q3', score: 91 },
  { team: 'Mobile', quarter: 'Q4', score: 94 },
]

Bin events into a calendar#

A contribution-style calendar exposes both long-term activity and weekday rhythm without drawing one long daily time axis. This example aggregates raw, session-level token events into a complete twelve-month UTC day domain, then maps Sunday weeks to columns and weekdays to rows.

Token Usage Calendar

EditRun

The example uses binTimeX with D3's utcDay interval and an explicit twelve-month domain. Each output row contains the day interval, the summed token count, the session count, and source lineage. Empty bins become real zero-value days and share one consistent neutral treatment.

Calendar placement is a second, explicit step: utcSunday.count produces the week column and date.getUTCDay() selects the row. A categorical usage scale creates contribution-style levels, while the accessible chart description and cell color explain the zero-to-high usage range. The compact focus tooltip keeps the visible detail to the exact token total and date. Keep all calendar calculations in one time basis—UTC here—to avoid moving events between days around daylight-saving transitions.

Aggregate into quantitative cells#

A two-dimensional binned heatmap makes density bounded: the number of rendered cells depends on the chosen grid, not directly on the number of raw points.

Quantitative Binned Heatmap

EditRun

Prepare explicit x and y interval endpoints plus the aggregate value. Use thresholds that are stable across comparable views and a color domain that states whether absolute count or normalized density is being shown. See Scales for binning and scale ownership.

Trace levels through a scalar grid#

A scalar-grid contour shows where a sampled field crosses chosen values. The input is a regular row-major grid rather than a set of x/y observations.

Contour Topography

EditRun

The optional contour mark accepts the raw grid, dimensions, value channel, and levels. It owns marching-squares topology and structured polygons; the chart definition retains the metric and threshold choices. Keep grid orientation and dimensions explicit when changing the sample window.

Estimate point concentration with density contours#

Density contours turn many points into nested level sets. They are useful for revealing cluster shape and overlap when raw dots would occlude one another.

Density Contours

EditRun

Bandwidth and thresholds change the visible shape. Treat them as analytical parameters, keep them stable for comparisons, and explain them when they affect interpretation. The optional densityContour mark maps the source channels through final scales, owns responsive estimation, and emits structured polygons and holes without case-owned path construction.

Retain local structure with hexagonal bins#

Hexagonal bins aggregate nearby points in pixel space and encode each bin's count or statistic. They provide a compact alternative when a rectangular grid would impose stronger horizontal and vertical edges.

Hexbin Density

EditRun

Pixel-space binning is responsive work: a changed container changes the spatial layout. The optional hexbin mark owns that resolved-layout step, reducer channels, source lineage, and hexagon scene output without a duplicated scale.

Production checks#

• State whether color represents count, proportion, rate, or another aggregate.
• Choose a sequential, diverging, or threshold scale that matches the data semantics.
• Keep missing, zero, and out-of-domain cells visually distinct.
• Add direct labels only when cells remain large enough to read. A labeled ordinal matrix is demonstrated in Themes and Styling.
• Prefer aggregation over rendering an unbounded raw point layer. See Large Data.