Heatmap Chart API
Complete API reference for the Heatmap Chart, including data format, configuration options, custom parts, and context methods.
Data Format
A matrix of values indexed by x-labels (columns) and y-labels (rows). Values[yIndex][xIndex] represents the intensity at that cell.
type HeatmapData = {
xLabels: string[];
yLabels: string[];
// segments are 2-dimensional array [yIndex][xIndex]
values: number[][];
};AG Style Config
Heatmap
| Property | Type | Default | Description |
|---|---|---|---|
| heatmap.colorRange | [string, string, string] | ["#1D4ED8", "#FDE047", "#DC2626"] | Three-color gradient range [low, mid, high] for mapping values. |
| heatmap.segment.gap | number | 0 | Gap between heatmap cells in pixels. |
Toast Style Config
Heatmap
| Property | Type | Default | Description |
|---|---|---|---|
| heatmap.colorRange | [string, string, string] | ["#FDE68A", "#F97316", "#B91C1C"] | Three-color gradient range [low, mid, high] for mapping values. |
| heatmap.segment.gap | number | 0 | Gap between heatmap cells in pixels. |
Custom Parts
Override any visual element by providing a custom builder function: (args, context) => Widget
| Part | Args | Description |
|---|---|---|
| layout | { title: Widget; legend: Widget; plot: Widget } | Top-level layout composing title, legend, and the plot area. |
| plot | { xAxis: Widget; yAxis: Widget; dataView: Widget; axisCorner: Widget; tooltipArea: Widget } | The plot area composing axes, data view, and tooltip. |
| xAxis | { line: Widget; labels: Widget[]; tick: Widget } | The complete x-axis assembly. |
| yAxis | { line: Widget; labels: Widget[]; tick: Widget } | The complete y-axis assembly. |
| xAxisLabel | { name: string; index: number } | Individual x-axis label. |
| yAxisLabel | { name: string; index: number } | Individual y-axis label. |
| xAxisLine | undefined | X-axis line. |
| yAxisLine | undefined | Y-axis line. |
| axisCorner | undefined | Corner element where x and y axes meet. |
| xAxisTick | undefined | X-axis tick mark. |
| yAxisTick | undefined | Y-axis tick mark. |
| dataView | { segments: Widget[][] } | Container for all heatmap cells (2D array). |
| segment | { value: number; xIndex: number; yIndex: number; isHovered: boolean } | Individual heatmap cell. |
| legend | undefined | Color scale legend element. |
| title | undefined | Chart title element. |
| tooltip | { label: string; items: { legend: string; color: string; value: number }[] } | Tooltip content widget. |
| tooltipArea | { tooltip: Widget | null; hoveredSegment: HeatmapHoveredSegmentRect | null } | Tooltip positioning area. |
Context: HeatmapContext
Available in every custom builder via the second argument.
| Name | Type | Kind | Description |
|---|---|---|---|
| data | HeatmapData | property | Current chart data. |
| width | number | property | Current chart width in pixels. |
| height | number | property | Current chart height in pixels. |
| scale | HeatmapScale | property | Computed scale with min and max values. |
| hoveredSegment | HeatmapHoveredSegment | null | property | Currently hovered cell info. |
| config | TConfig | property | The resolved chart configuration object. |
| hoverSegment(xIndex, yIndex, anchorKey) | (xIndex: number, yIndex: number, anchorKey: GlobalKey) => void | method | Set hover state on a cell. |
| unhoverSegment(xIndex, yIndex) | (xIndex: number, yIndex: number) => void | method | Clear hover if the specified cell is currently hovered. |
| unhoverAllSegments() | () => void | method | Clear all cell hover state. |
| isSegmentHovered(xIndex, yIndex) | (xIndex: number, yIndex: number) => boolean | method | Check if a specific cell is hovered. |
| setSize(width, height) | (width: number, height: number) => void | method | Update chart dimensions. |
Custom Part Example
import { ToastHeatmapChart } from "@/components/flitter/charts/toast-heatmap-chart";
<ToastHeatmapChart
data={data}
config={{
heatmap: {
colorRange: ["#dbeafe", "#3b82f6", "#1e3a5f"],
segment: { gap: 2 },
},
}}
/>