Heatmap Examples

Publication-quality heatmaps with configurable color scales, value labels, and interactive features.

Type Interface

import type { BaseChartProps, Formatter } from '../../types';

/**
 * Heatmap data structure
 */
export interface HeatmapData {
  /** 2D array of values (rows × columns) */
  data: number[][];
  /** Optional row labels (defaults to indices) */
  rowLabels?: string[];
  /** Optional column labels (defaults to indices) */
  columnLabels?: string[];
}

/**
 * Color scale configuration
 */
export type ColorScale = 'viridis' | 'plasma' | 'inferno' | 'magma' | 'blues' | 'oranges' | 'greens' | 'reds' | 'grays' | 'custom';

export interface HeatmapProps extends HeatmapData, Omit<BaseChartProps, 'legendFontSize'> {
  /** X-axis label */
  xLabel?: string;
  /** Y-axis label */
  yLabel?: string;
  /** Chart title */
  title?: string;
  /** Color scale to use */
  colorScale?: ColorScale;
  /** Custom color array (used when colorScale='custom') */
  customColors?: string[];
  /** Minimum value for color mapping (auto-calculated if not provided) */
  valueMin?: number;
  /** Maximum value for color mapping (auto-calculated if not provided) */
  valueMax?: number;
  /** Show value labels in cells */
  showValues?: boolean;
  /** Show color bar legend */
  showColorBar?: boolean;
  /** Cell border color */
  cellBorderColor?: string;
  /** Cell border width */
  cellBorderWidth?: number;
  /** Value formatter for cell labels */
  valueFormat?: Formatter;
  /** Custom overlays and children */
  children?: React.ReactNode;
  /** Callback when cell is clicked */
  onCellClick?: (row: number, col: number, value: number) => void;
  /** Callback when cell is hovered */
  onCellHover?: (row: number, col: number, value: number) => void;
}

Layout & Spacing

Heatmaps support flexible layout customization through margin and padding props:

• padding: Uniform spacing on all sides (shorthand)
• margin: Fine-grained control with { top, right, bottom, left }

Examples

// Uniform padding
<Heatmap padding={30} data={[[1, 2], [3, 4]]} />

// Custom margins per side
<Heatmap
  margin={{ top: 20, right: 100, bottom: 50, left: 60 }}
  data={[[1, 2], [3, 4]]}
/>

The padding prop provides a convenient shorthand for setting equal margins on all sides, while margin allows precise control over each side individually. When both are provided, margin takes precedence.

Default margin: { top: 40, right: 20, bottom: 50, left: 60 }

Basic Heatmap

A simple heatmap with a viridis color scale and color bar legend.

import { Heatmap } from '@vuer-ai/vuer-viz';

export default function BasicHeatmapExample() {
  // Generate sample correlation matrix data
  const data = [
    [1.0, 0.8, 0.3, -0.2, 0.1],
    [0.8, 1.0, 0.5, 0.1, 0.3],
    [0.3, 0.5, 1.0, 0.7, 0.4],
    [-0.2, 0.1, 0.7, 1.0, 0.6],
    [0.1, 0.3, 0.4, 0.6, 1.0],
  ];

  const labels = ['Feature A', 'Feature B', 'Feature C', 'Feature D', 'Feature E'];

  return (
    <Heatmap
      data={data}
      rowLabels={labels}
      columnLabels={labels}
      title="Feature Correlation Matrix"
      xLabel="Features"
      yLabel="Features"
      colorScale="viridis"
      valueMin={-1}
      valueMax={1}
      width={500}
      height={500}
    />
  );
}

Color Scales

The Heatmap component supports multiple built-in color scales inspired by matplotlib:

• viridis (default): Perceptually uniform, colorblind-friendly
• plasma: High contrast purple-yellow scale
• inferno: High contrast black-yellow scale
• magma: High contrast black-pink scale
• blues: Sequential blue scale
• oranges: Sequential orange scale
• greens: Sequential green scale
• reds: Sequential red scale
• grays: Sequential grayscale
• custom: Provide your own color array via customColors prop

import { Heatmap } from '@vuer-ai/vuer-viz';

export default function ColorScalesExample() {
  // Generate sample data
  const data = [
    [10, 20, 30, 40],
    [15, 25, 35, 45],
    [12, 22, 32, 42],
  ];

  const rowLabels = ['Row 1', 'Row 2', 'Row 3'];
  const columnLabels = ['Col A', 'Col B', 'Col C', 'Col D'];

  return (
    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '20px' }}>
      <Heatmap
        data={data}
        rowLabels={rowLabels}
        columnLabels={columnLabels}
        title="Viridis"
        colorScale="viridis"
        width={300}
        height={250}
      />
      <Heatmap
        data={data}
        rowLabels={rowLabels}
        columnLabels={columnLabels}
        title="Plasma"
        colorScale="plasma"
        width={300}
        height={250}
      />
      <Heatmap
        data={data}
        rowLabels={rowLabels}
        columnLabels={columnLabels}
        title="Inferno"
        colorScale="inferno"
        width={300}
        height={250}
      />
      <Heatmap
        data={data}
        rowLabels={rowLabels}
        columnLabels={columnLabels}
        title="Blues"
        colorScale="blues"
        width={300}
        height={250}
      />
    </div>
  );
}

Heatmap with Value Labels

Display the actual values in each cell by setting showValues={true}.

import { Heatmap } from '@vuer-ai/vuer-viz';

export default function WithValuesExample() {
  // Sample confusion matrix data
  const data = [
    [95, 3, 1, 1],
    [2, 88, 8, 2],
    [0, 5, 92, 3],
    [1, 2, 4, 93],
  ];

  const labels = ['Class A', 'Class B', 'Class C', 'Class D'];

  return (
    <Heatmap
      data={data}
      rowLabels={labels}
      columnLabels={labels}
      title="Confusion Matrix"
      xLabel="Predicted Label"
      yLabel="True Label"
      colorScale="blues"
      showValues={true}
      cellBorderColor="#cccccc"
      cellBorderWidth={1}
      width={500}
      height={500}
    />
  );
}

Interactive Heatmap

Handle cell clicks and hovers for interactive data exploration.

import { useState } from 'react';
import { Heatmap } from '@vuer-ai/vuer-viz';

export default function InteractiveExample() {
  const [selectedCell, setSelectedCell] = useState<{
    row: number;
    col: number;
    value: number;
  } | null>(null);

  // Generate sample data (temperature readings over time)
  const data = [
    [22.1, 23.5, 25.2, 26.8, 27.3, 26.1],
    [21.8, 22.9, 24.5, 25.9, 26.5, 25.3],
    [20.5, 21.3, 22.8, 24.1, 24.8, 23.9],
    [19.2, 20.1, 21.5, 22.7, 23.3, 22.5],
  ];

  const rowLabels = ['Sensor 1', 'Sensor 2', 'Sensor 3', 'Sensor 4'];
  const columnLabels = ['0:00', '4:00', '8:00', '12:00', '16:00', '20:00'];

  const handleCellClick = (row: number, col: number, value: number) => {
    setSelectedCell({ row, col, value });
  };

  return (
    <div>
      <Heatmap
        data={data}
        rowLabels={rowLabels}
        columnLabels={columnLabels}
        title="Temperature Readings (°C)"
        xLabel="Time of Day"
        yLabel="Sensor Location"
        colorScale="oranges"
        onCellClick={handleCellClick}
        width={600}
        height={350}
      />
      {selectedCell && (
        <div
          style={{
            marginTop: '20px',
            padding: '15px',
            backgroundColor: '#f5f5f5',
            borderRadius: '8px',
            fontFamily: 'DejaVu Sans, sans-serif',
            fontSize: '14px',
          }}
        >
          <strong>Selected Cell:</strong> {rowLabels[selectedCell.row]} at{' '}
          {columnLabels[selectedCell.col]}
          <br />
          <strong>Temperature:</strong> {selectedCell.value.toFixed(1)}°C
        </div>
      )}
    </div>
  );
}

Event Handling API

Heatmap supports interactive callbacks for cell interactions:

Cell Click Events

import { Heatmap } from '@vuer-ai/vuer-viz';

function MyHeatmap() {
  const handleCellClick = (row: number, col: number, value: number) => {
    console.log(`Clicked cell at (${row}, ${col}) with value ${value}`);
  };

  return (
    <Heatmap
      data={[[1, 2], [3, 4]]}
      rowLabels={['A', 'B']}
      columnLabels={['X', 'Y']}
      onCellClick={handleCellClick}
    />
  );
}

Cell Hover Events

import { Heatmap } from '@vuer-ai/vuer-viz';

function MyHeatmap() {
  const handleCellHover = (row: number, col: number, value: number) => {
    console.log(`Hovering over cell at (${row}, ${col}) with value ${value}`);
  };

  return (
    <Heatmap
      data={[[1, 2], [3, 4]]}
      onCellHover={handleCellHover}
    />
  );
}

API Reference

Props

Color Scale Reference

Perceptually Uniform (Recommended)

• viridis: Blue to green to yellow
• plasma: Purple to pink to yellow
• inferno: Black to red to yellow
• magma: Black to purple to pink to white

Sequential

• blues: White to dark blue
• oranges: White to dark orange
• greens: White to dark green
• reds: White to dark red
• grays: White to black

Custom

Provide your own color array with the customColors prop:

<Heatmap
  data={myData}
  colorScale="custom"
  customColors={['#ffffff', '#ff0000', '#000000']}
/>

The component will interpolate between your provided colors to create a smooth gradient with 256 color steps.