How to Render HeatMap in Flutter CartesianChart?
This article explains how to render the HeatMap chart by utilizing the onCreateRenderer callback, which allows the creation of custom series and segments for a flexible visualization. The pointColorMapper property plays a crucial role in assigning different colors to each data point based on their values, enhancing the heatmap’s appearance.
Additionally, the borderColor and borderRadius properties are used to adjust the visual representation of specific data points. To improve axis labeling and provide better insights, multiLevelLabels are incorporated, allowing more detailed data representation on the chart.
The legend is customized with a gradient color bar to effectively indicate data ranges. Positioned at the top, it provides a clear visual reference for interpreting values. The legend’s appearance is further enhanced using a custom legendItemBuilder, which ensures a more intuitive understanding of the heatmap’s data distribution.
The following steps outline how to achieve a heatmap in Flutter CartesianChart.
Step 1: Define the data
Prepare a list of initial data points to displayed on the chart.
List<_HeatMapData>? _heatMapData;
@override
void initState() {
_heatMapData = <_HeatMapData>[
_HeatMapData('59%', 0.694, 0.277, 0.285, 0.76, 0.375, 0.53),
_HeatMapData('70%', 68.9, 43.2, 40.8, 69.5, 49.5, 53.7),
_HeatMapData('71%', 1.64, 1.68, 1.64, 1.61, 1.75, 1.68),
_HeatMapData('72%', 0.632, 0.973, 1.01, 0.747, 0.948, 0.956),
];
super.initState();
}
Step 2: Building the Flutter StackedBar100Series
The _buildHeatmapChart() method creates an SfCartesianChart with CategoryAxis for the primaryXAxis and NumericAxis for the primaryYAxis. The _buildHeatmapSeries() method generates six StackedBar100Series instances, each using _heatMapData as the data source. The xValueMapper assigns the percentage value from _HeatMapData, while the yValueMapper calculates the Y-axis value using _findValueByIndex().
The DataLabelSettings property is set to isVisible to true to display data labels on the bars.
@override
Widget build(BuildContext context) {
return Scaffold(
body: _buildHeatmapChart(),
);
}
SfCartesianChart _buildHeatmapChart() {
return SfCartesianChart(
primaryXAxis: CategoryAxis(),
primaryYAxis: NumericAxis(),
series: _buildHeatmapSeries(),
);
}
List<CartesianSeries<_HeatMapData, String>> _buildHeatmapSeries() {
return List.generate(6, (index) {
return StackedBar100Series<_HeatMapData, String>(
dataSource: _heatMapData,
xValueMapper: (_HeatMapData data, int index) => data.percentage,
yValueMapper: (_HeatMapData data, int index) => _findValueByIndex(data, index),
dataLabelSettings: DataLabelSettings(isVisible: true),
);
});
}
Step 3: Creating custom heatmap series renderer
To create a heatmap series renderer in SfCartesianChart, you need to use the onCreateRenderer callback. This allows you to define a custom renderer class, such as _HeatmapSeriesRenderer, which extends StackedBar100SeriesRenderer and customizes the rendering of heatmap segments with unique shapes.
Adjusting range:
To ensure equal height for each heatmap segment, we override the populateDataSource method in the _HeatmapSeriesRenderer class. First, we set the y-axis range from 0 to 102 to yMin and yMax to to keep values positive, even if negative data is provided.
Adjusting segments for equal height:
We calculate the top and bottom values for each segment using the _computeHeatMapValues() method, ensuring they are evenly distributed. The height of each segment is determined using the formula yValue = 100 / seriesLength, where seriesLength is the number of series dependent on the y-axis. For each series, we skip those that are not visible or have no data, then assign the bottom value based on its position and set the top value as stackValue + yValue.
Finally, we loop through the data points and apply these values, ensuring all segments maintain a consistent height across the heatmap.
StackedBar100Series<_HeatMapData, String>(
....
onCreateRenderer: (ChartSeries<_HeatMapData, String> series) {
return _HeatmapSeriesRenderer();
},
);
class _HeatmapSeriesRenderer extends StackedBar100SeriesRenderer<_HeatMapData, String> {
_HeatmapSeriesRenderer();
@override
void populateDataSource(
[List<ChartValueMapper<_HeatMapData, num>>? yPaths,
List<List<num>>? chaoticYLists,
List<List<num>>? yLists,
List<ChartValueMapper<_HeatMapData, Object>>? fPaths,
List<List<Object?>>? chaoticFLists,
List<List<Object?>>? fLists]) {
super.populateDataSource(yPaths, chaoticYLists, yLists, fPaths, chaoticFLists, fLists);
// Always keep positive 0 to 102 range even set negative value.
yMin = 0;
yMax = 102;
// Calculate heatmap segment top and bottom values.
_computeHeatMapValues();
}
void _computeHeatMapValues() {
if (xAxis == null || yAxis == null) {
return;
}
if (yAxis!.dependents.isEmpty) {
return;
}
// Get the number of series dependent on the yAxis.
final int seriesLength = yAxis!.dependents.length;
// Calculate the proportional height for each series
// (as a percentage of the total height).
final num yValue = 100 / seriesLength;
// Loop through each dependent series to calculate top and bottom values for
// the heatmap.
for (int i = 0; i < seriesLength; i++) {
// Check if the current series is a '_HeatmapSeriesRenderer'.
if (yAxis!.dependents[i] is _HeatmapSeriesRenderer) {
final _HeatmapSeriesRenderer current = yAxis!.dependents[i] as _HeatmapSeriesRenderer;
// Skip processing if the series is not visible or has no data.
if (!current.controller.isVisible || current.dataCount == 0) {
continue;
}
// Calculate the bottom (stack) value for the current series.
num stackValue = 0;
stackValue = yValue * i;
current.topValues.clear();
current.bottomValues.clear();
// Loop through the data points in the current series.
final int length = current.dataCount;
for (int j = 0; j < length; j++) {
// Add the bottom value (stackValue) for the current data point.
current.bottomValues.add(stackValue.toDouble());
// Add the top value (stackValue + yValue) for the current data point.
current.topValues.add((stackValue + yValue).toDouble());
}
}
}
}
}
Step 4: Heatmap appearance
You can customize each heatmap segment’s appearance using below properties in the StackedBar100Series.
- You can customize each heatmap segment’s color using the pointColorMapper property, which assigns colors based on data values.
- The width property controls the segment’s relative width, ensuring a structured layout.
- To enhance visibility, the borderColor is applied based on the segment index, creating clear boundaries. Additionally, the borderRadius property adds rounded edges for more visually appealing heatmap.
Color _buildColor(num value) {
if (value >= 50.0) return Colors.yellow.shade500;
if (value >= 40.0) return Colors.green.shade700;
if (value >= 30.0) return Colors.green.shade500;
if (value >= 5.0) return Colors.green.shade300;
if (value > 0.0) return Colors.green.shade200;
return Colors.red.shade800;
}
double _findValueByIndex(_HeatMapData data, int index) {
switch (index) {
case 0:
return data.hcwf;
case 1:
return data.nonicuf;
case 2:
return data.icuf;
case 3:
return data.hcwm;
case 4:
return data.nonicum;
case 5:
return data.icum;
default:
return 0;
}
}
StackedBar100Series<_HeatMapData, String>(
....
pointColorMapper: (_HeatMapData data, int index) => _buildColor(_findValueByIndex(data, index)),
animationDuration: 0,
width: 1,
borderWidth: 1,
borderColor: (index == 1 || index == 3 || index == 4) ? Colors.black : Colors.transparent,
borderRadius: const BorderRadius.all(Radius.circular(5)),
dataLabelSettings: DataLabelSettings(
.....
labelAlignment: ChartDataLabelAlignment.middle,
textStyle: const TextStyle(
fontSize: 20,
color: Colors.black,
fontWeight: FontWeight.bold,
),
),
);
Step 5: Axes configuration
The primaryXAxis is a CategoryAxis, which represents discrete categories instead of continuous values. The _buildCategoryLabels() method defines multi-level labels with a start and end value to position them correctly. These labels include “T cell number”, “T cells”, “TRAIL”, and “TGFa”. To keep the axis clean, unnecessary lines and ticks are removed by setting axisLine, majorGridLines, and majorTickLines to width: 0. The multiLevelLabels property in CategoryAxis applies _buildCategoryLabels(), to ensure custom categorical labels
Similarly, The primaryYAxis is a NumericAxis , which represents continuous numerical values. The _buildNumericLabels() method defines multi-level labels that group data into ranges. Each label has a start and end value, and some labels include a level property to create a hierarchy. For example, “6/277” is a top-level label, while “HCW” (Healthcare Workers) is a subgroup within that range. To keep the axis clean, unnecessary lines and ticks are removed by setting axisLine, majorGridLines, and majorTickLines to width: 0. The multiLevelLabels property in NumericAxis applies _buildNumericLabels() to ensure custom numeric labels and The maximumLabelWidth is 0, allowing labels to take up full space.
List<CategoricalMultiLevelLabel> _buildCategoryLabels() {
return [
CategoricalMultiLevelLabel(start: '59%', end: '59%', text: 'T cell number'),
CategoricalMultiLevelLabel(start: '70%', end: '70%', text: 'T cells'),
CategoricalMultiLevelLabel(start: '71%', end: '71%', text: 'TRAIL'),
CategoricalMultiLevelLabel(start: '72%', end: '72%', text: 'TGFa'),
];
}
List<NumericMultiLevelLabel> _buildNumericLabels() {
return [
NumericMultiLevelLabel(start: 0,end: 15, text: '6/277',),
NumericMultiLevelLabel(start: 0, end: 15, text: 'HCW', level: 1),
NumericMultiLevelLabel(start: 15, end: 35, text: '41/61'),
NumericMultiLevelLabel(start: 15, end: 35, text: 'Non-ICU', level: 1),
NumericMultiLevelLabel(start: 35, end: 48, text: '65/11'),
NumericMultiLevelLabel(start: 35, end: 48, text: 'ICU', level: 1),
NumericMultiLevelLabel(start: 48, end: 68, text: '28/87', level: 1),
NumericMultiLevelLabel(start: 48, end: 68, text: 'HCW'),
NumericMultiLevelLabel(start: 68, end: 80, text: '53/71', level: 1),
NumericMultiLevelLabel(start: 68, end: 80, text: 'Non-ICU'),
NumericMultiLevelLabel(start: 80, end: 102, text: '112/182'),
NumericMultiLevelLabel(start: 80, end: 102, text: 'ICU', level: 1),
];
}
ChartAxisLabel _formatLabel(MultiLevelLabelRenderDetails details) {
return ChartAxisLabel(details.text, const TextStyle(fontWeight: FontWeight.bold, fontSize: 14.0));
}
SfCartesianChart(
plotAreaBorderWidth: 0,
primaryXAxis: CategoryAxis(
axisLine: const AxisLine(width: 0),
majorGridLines: const MajorGridLines(width: 0),
majorTickLines: const MajorTickLines(width: 0),
labelStyle: const TextStyle(
fontWeight: FontWeight.bold,
fontSize: 14.0,
),
multiLevelLabelStyle: MultiLevelLabelStyle(borderColor: Colors.transparent),
multiLevelLabels: _buildCategoryLabels(),
multiLevelLabelFormatter: _formatLabel,
),
primaryYAxis: NumericAxis(
maximumLabelWidth: 0,
axisLine: const AxisLine(width: 0),
majorGridLines: const MajorGridLines(width: 0),
majorTickLines: const MajorTickLines(width: 0),
multiLevelLabelStyle: MultiLevelLabelStyle(borderColor: Colors.transparent),
multiLevelLabels: _buildNumericLabels(),
multiLevelLabelFormatter: _formatLabel,
),
....
);
Step 6: Legend customization
The legend property in SfCartesianChart is customized to enhance visual clarity.
- The isVisible property is set to true, ensuring the legend is displayed. It is positioned at the top using LegendPosition.top.
- Instead of the default design, the legendItemBuilder property is used to create a custom layout with legend text, series, point, and series index for better control.
- The isVisibleInLegend property ensures that only the legend for index 0 is visible.
SfCartesianChart(
....
legend: Legend(
isVisible: true,
position: LegendPosition.top,
legendItemBuilder: (legendText, series, point, seriesIndex) {
return Row(
children: [
const Text('Zero '),
const SizedBox(width: 5),
SizedBox(
width: 400,
height: 20,
child: DecoratedBox(
decoration: BoxDecoration(
gradient: LinearGradient(
colors: [
Colors.green.withValues(alpha: 0.2),
Colors.green.withValues(alpha: 0.9),
],
begin: Alignment.centerLeft,
end: Alignment.centerRight,
),
),
)),
const SizedBox(width: 5),
const Text('49.5'),
],
);
},
),
series: _buildHeatmapSeries(),
);
StackedBar100Series<_HeatMapData, String>(
....
isVisibleInLegend: index == 0,
....
);
By following provided code snippet, you can achieve a heatmap in Flutter CartesianChart
Go through the sample on GitHub.
Conclusion
I hope you enjoyed learning about how to render heatmap in Flutter CartesianChart.
You can refer to our Flutter CartesianChart feature tour page to know about its other groundbreaking feature representations. You can also explore our documentation to understand how to create and manipulate data.
For current customers, you can check out our components from the License and Downloads page. If you are new to Syncfusion®, you can try our 30-day free trial to check out our other controls.
If you have any queries or require clarifications, please let us know in the comments section below. You can also contact us through our support forums, Direct-Trac, or feedback portal. We are always happy to assist you!
