Heatmap — Chart Controls

Data Shape

Heatmap data is an array of triplets: row label, column label, and value. The control builds the matrix automatically from unique row and column values:

// [{ row, col, value }, ...]
[
  { "row": "Mon", "col": "00:00", "value": 12 },
  { "row": "Mon", "col": "06:00", "value": 48 },
  { "row": "Mon", "col": "12:00", "value": 192 },
  { "row": "Tue", "col": "00:00", "value": 9  },
  { "row": "Tue", "col": "06:00", "value": 61 }
  // ...
]

Settings Reference

Setting	Type	Default	Description
`rowKey`	string	`"row"`	Property name for the row dimension
`colKey`	string	`"col"`	Property name for the column dimension
`valueKey`	string	`"value"`	Property name for the numeric value
`colorScale`	`blue` \| `green` \| `red` \| `orange` \| `custom`	`blue`	Colour palette for the gradient scale
`colorRange`	[string, string]	—	Custom colour range when `colorScale: "custom"`: `["#f0f9ff", "#1e40af"]`
`showCellLabels`	boolean	false	Show numeric value inside each cell
`cellGap`	number	2	Gap between cells in pixels
`showColorBar`	boolean	true	Show the colour scale legend bar
`minValue`	number	auto	Minimum value for colour scale (override auto-detection)
`maxValue`	number	auto	Maximum value for colour scale

Traffic Heatmap — Hour vs Day

{
  "id": "traffic-heatmap",
  "type": "chart-heatmap",
  "settings": {
    "height": "320px",
    "title": "Requests by Hour and Day of Week",
    "rowKey": "day",
    "colKey": "hour",
    "valueKey": "requests",
    "colorScale": "blue",
    "showColorBar": true,
    "cellGap": 3,
    "chartConfig": {
      "xAxis": { "label": "Hour of Day" },
      "yAxis": { "label": "Day" }
    },
    "binding": { "source": "$context", "path": "telemetry.hourlyTraffic" }
  }
}

// Data:
// [
//   { "day": "Mon", "hour": "00:00", "requests": 821  },
//   { "day": "Mon", "hour": "01:00", "requests": 432  },
//   { "day": "Mon", "hour": "09:00", "requests": 4210 },
//   ...
// ]

Correlation Matrix

Show the correlation coefficient matrix for a set of metrics. Values range from -1 to 1, so set colorScale: "custom" with a diverging colour scheme:

{
  "id": "correlation-matrix",
  "type": "chart-heatmap",
  "settings": {
    "height": "380px",
    "title": "Metric Correlation Matrix",
    "colorScale": "custom",
    "colorRange": ["#ef4444", "#f3f4f6", "#22c55e"],
    "minValue": -1,
    "maxValue": 1,
    "showCellLabels": true,
    "cellGap": 2,
    "binding": { "source": "$context", "path": "analytics.correlations" }
  }
}

// Data (row and col are metric names):
// [
//   { "row": "Revenue",    "col": "Revenue",    "value": 1.00 },
//   { "row": "Revenue",    "col": "Conversion", "value": 0.78 },
//   { "row": "Revenue",    "col": "Churn",      "value": -0.42 },
//   { "row": "Conversion", "col": "Revenue",    "value": 0.78 },
//   ...
// ]

GitHub-Style Activity Calendar

An activity calendar uses week number as the column and day of week as the row, coloured by commit or event count:

{
  "id": "activity-calendar",
  "type": "chart-heatmap",
  "settings": {
    "height": "160px",
    "title": "Workflow Executions — Last 12 Weeks",
    "rowKey": "dayOfWeek",
    "colKey": "week",
    "valueKey": "count",
    "colorScale": "green",
    "minValue": 0,
    "cellGap": 4,
    "showColorBar": false,
    "binding": { "source": "$context", "path": "activity.calendar" }
  }
}

Row and Column Ordering The heatmap renders rows and columns in the order they first appear in the data array. Sort your data server-side to ensure the correct display order — for example, sort days Monday through Sunday, and hours 00:00 through 23:00.

← Histogram Next: Radial Gauge →