Overview
The Heat Map chart type renders a two-dimensional grid of cells. Each cell's color intensity represents the magnitude of a value at the intersection of an X-category and a Y-category. Unlike cartesian charts, the axes are both categorical — there is no continuous scale unless you bind a date or numeric field that the chart treats as ordered categories.
Tip: A heatmap works best when you have many combinations of two categories with a numeric signal at each intersection (e.g., day × hour, agent × queue, product × region). If there are very few X or Y values, a grouped bar chart may be clearer.
Required Data Shape
Each record in the bound data must have at least three fields:
A field bound to the X Axis (one categorical or date dimension)
A field bound to the Y Axis (a second categorical dimension)
A numeric field bound to the Value (the measurement that drives color)
Sample data shape for an activity heatmap
[ { "day": "Mon", "hour": "9am", "tickets": 12 }, { "day": "Mon", "hour": "10am", "tickets": 18 }, { "day": "Tue", "hour": "9am", "tickets": 7 }, ... ]
Bind day → X Axis, hour → Y Axis, tickets → Series Value.
Content Properties
| Property | Description |
| Data Source | The array of records to render as a grid. |
| X Axis → Value | The field to distribute along the horizontal axis. Each unique value becomes a column. |
| X Axis → Type | Axis scale. Category (default) for text labels; Time for dates (enables date grouping). |
| X Axis → Tick labels / Rotate | Controls label visibility, angle, and font on the X axis header row. |
| Y Axis → Value | The field to distribute along the vertical axis. Each unique value becomes a row. |
| Series → Value | The numeric field driving cell color intensity. One series only on a Heat Map. |
| Series → Label | The display name used in the tooltip and legend. |
| Tooltip | Customizable header and body for hover tooltips. Can reference the row's X value, Y value, and numeric value. |
Appearance Properties
| Property | Options / Default | Description |
| Color Scale | gradient picker | Defines the color range from minimum to maximum cell value. Often a single-hue gradient (e.g., white → dark blue) or a diverging palette (blue → white → red). |
| Color Min / Max | numeric | Override the automatic min/max of the color scale. Useful when you want cells below a threshold to show the same "low" color, or to align multiple heatmaps on the same scale. |
| Legend Position | top, right, bottom, left, remove | Position of the color scale gradient legend. |
| Show Cell Labels | toggle | Renders the numeric value inside each cell. Useful for dense comparison tables where hover is inconvenient. |
| Chart Colours | color assignment | Controls the color palette for the scale steps. Often configured as a two-stop gradient. |
| styles | style set | Block dimensions, padding, overflow. |
Events & Methods
| Event | Description |
| On Data Point Click | Fires when a cell is clicked. The payload contains the full record for that cell's X/Y intersection. Use to drill down into the detail rows behind the aggregated cell value. |
Behavior & Gotchas
⚠ Missing cells are blank, not zero
If your data has no record for a given X/Y intersection, the cell renders as blank (no fill). To show a "zero" cell, include a record with value 0 in your data source.
⚠ Color scale uses the data range by default
The color scale automatically spans the minimum and maximum values in the bound data. If your data changes (filtered, refreshed), the scale re-centers and visual comparisons can shift. Pin Color Min / Max to a fixed range for stable comparisons.
⚠ One series per heatmap
A Heat Map supports exactly one value field. To compare two metrics, use two separate Chart blocks side by side with linked legends.
⚠ Axis order follows data row order
X and Y axis categories appear in the order they are first encountered in the data. Sort your data source before binding to control axis ordering.
Common Patterns
Activity Calendar (Day × Hour)
Prepare aggregated data: Query your data source to aggregate records by day-of-week and hour-of-day, summing or counting the metric of interest. Return one row per day/hour pair.
Bind axes: Set X Axis Value = day-of-week field, Y Axis Value = hour-of-day field, Series Value = count field.
Configure color scale: Choose a single-hue gradient (light = low, dark = high). Pin Color Min = 0 to keep the scale stable across different data loads.
Add drill-down: On On Data Point Click, open a drawer or modal filtered to the clicked day + hour to show the underlying records.
Correlation Matrix
Compute correlations: Pre-compute a correlation matrix (or similarity table) server-side, returning rows like
{ metricA, metricB, correlation }.Use diverging color scale: Set a diverging palette: blue for negative correlation, white for zero, red for positive. Pin Color Min = -1, Color Max = 1.
Enable cell labels: Toggle Show Cell Labels on so readers can see exact correlation values without hovering.
Related Pages
| Page | Relationship |
| Scatter & Bubble Charts | Another distribution chart type — for continuous X/Y instead of categorical |
| Bar & Column Charts | Alternative for comparing categories when the grid would be sparse |
| Data Labels & Annotations | Adding text labels to data points on other chart types |