Skip to main content

HeatmapChart

HeatmapChart

Matrix data visualization with color intensity

Tags: chart matrix density correlation activity

View Demo

The HeatmapChart displays data in a matrix format where values are represented by color intensity. It's excellent for showing patterns across two dimensions, such as activity over time, correlation matrices, or geographic data density.

Reporting props marked Svelte only (valueFormat, showDataTable, exportable, reference lines, data zoom and so on) are available in @classic-homes/charts-svelte; React support is pending.

Import​

<script>
  import { HeatmapChart } from '@classic-homes/charts-svelte';
</script>
// React
import { HeatmapChart } from '@classic-homes/charts-react';

Basic Usage​

<script>
  import { HeatmapChart } from '@classic-homes/charts-svelte';

  const xAxis = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
  const yAxis = ['12a', '6a', '12p', '6p'];

  const data = {
    data: [
      [0, 0, 5],
      [0, 1, 1],
      [0, 2, 0],
      [0, 3, 2],
      [1, 0, 1],
      [1, 1, 0],
      [1, 2, 3],
      [1, 3, 4],
      // ... more data points
    ],
    min: 0,
    max: 5,
  };
</script>

<HeatmapChart title="Activity Heatmap" {data} {xAxis} {yAxis} showValues height={400} />

Props​

Chart-Specific Props​

Prop Type Default Description
data HeatmapData required Matrix data with coordinates and values
xAxis string[] required X-axis labels
yAxis string[] required Y-axis labels
showValues boolean false Display values in cells
labelFormatter string | ((params: LabelFormatterParams) => string) - Data label template or function
xAxisConfig AxisConfig - Horizontal axis name, tick formatter, rotation and range
yAxisConfig AxisConfig - Vertical axis name, tick formatter, rotation and range
onClick (params: HeatmapEventParams) => void - Callback when clicked

Inherited Base Props​

Prop Type Default Description
title string required Chart title for accessibility
height number | string 400 Chart height
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
showTooltip boolean true Show tooltip on hover
tooltipFormatter string | ((items: TooltipFormatterParams[]) => string) - Custom tooltip template or HTML function
tooltipValueFormatter (value: number) => string - Format values in the default tooltip
option EChartsOption - Raw ECharts option deep-merged over the generated one
description string - Optional description for screen readers
minHeight number - Minimum height in pixels; also bounds an 'auto' height
maxHeight number - Maximum height in pixels; also bounds an 'auto' height
loading boolean false Show loading skeleton; over existing data a loading overlay is shown instead (Svelte)
error string | null - Error message to display
onRetry () => void - Show a Retry button on the error state, calling this (Svelte only)
emptyMessage string - Message shown when data is empty
valueFormat ValueFormatPreset | Intl.NumberFormatOptions | ((value: number) => string) - How values are written in value axes, tooltips, labels and the data table: 'number', 'integer', 'compact', 'currency', 'currencyCents', 'percent', 'percentValue', 'days', Intl options or a function (Svelte only)
locale string 'en-US' Locale for valueFormat (Svelte only)
onReady (chart: EChartsType) => void - Called with the ECharts instance when it is created (Svelte only)
events Record<string, (params) => void> - Raw ECharts event handlers keyed by event name, e.g. datazoom (Svelte only)
showDataTable boolean | 'sr-only' 'sr-only' Render the data as a table: 'sr-only' for screen readers, true adds a visible "Show data" toggle, false for none (Svelte only)
exportable boolean | ChartExportConfig false Show PNG and CSV download buttons; or { image, csv, filename } (Svelte only)
patterns boolean false Fill series with decal patterns as well as colour, for colour-blind readers (Svelte only)
class string - Custom CSS class
animation boolean true Enable/disable animations (respects prefers-reduced-motion)
showLegend boolean - Show chart legend
showGrid boolean - Show grid lines (where applicable)

Data Structure​

interface HeatmapData {
  data: [number, number, number][]; // [xIndex, yIndex, value] tuples
  min?: number; // Minimum value for color scale
  max?: number; // Maximum value for color scale
}

Examples​

GitHub-style Activity​

<HeatmapChart
  title="Commit Activity"
  {data}
  xAxis={['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']}
  yAxis={['12a', '4a', '8a', '12p', '4p', '8p']}
/>

Correlation Matrix​

<HeatmapChart
  title="Feature Correlation"
  {data}
  xAxis={['Price', 'Size', 'Age', 'Rooms']}
  yAxis={['Price', 'Size', 'Age', 'Rooms']}
  showValues
/>

Accessibility​

  • Title provides context for the data
  • Color intensity conveys magnitude
  • Optional value labels for exact numbers
On this page