Heatmap

Basic usage

Pass an array of objects to Datum.heatmap()and identify the properties containing the X category, Y category, and cell value.

import { Datum, Color } from '@psdpainter/datum-js';

const days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
const hours = ['9 AM', '11 AM', '1 PM', '3 PM', '5 PM', '7 PM'];

const values = Array.from(
    { length: days.length * hours.length },
    (_, index) => ({
        day: days[index % days.length],
        hour: hours[Math.floor(index / days.length)],
        activity: Math.floor(Math.random() * 80) + 10
    })
);

Datum.chart({
    target: '#heatmap-example',
    height: 320,
    datum: [
        Datum.heatmap(values, {
            x: 'day',
            y: 'hour',
            value: 'activity',
            minColor: '#e0f2fe',
            maxColor: Color.Blue,
            showValues: true
        })
    ]
});

Syntax

Datum.heatmap(data, {
    x,
    y,
    value,
    minColor,
    maxColor,
    stroke,
    strokeWidth,
    rx,
    showValues,
    valueColor,
    tooltip
});

Data

By default, Datum expects each cell to containx, y, and valueproperties.

const values = [
    { x: 'Mon', y: 'Morning', value: 18 },
    { x: 'Tue', y: 'Morning', value: 32 },
    { x: 'Wed', y: 'Morning', value: 24 },
    { x: 'Mon', y: 'Afternoon', value: 38 },
    { x: 'Tue', y: 'Afternoon', value: 52 },
    { x: 'Wed', y: 'Afternoon', value: 47 }
];

Datum.heatmap(values);

Data keys

Use x, y, and valueto map custom property names.

const values = [
    { day: 'Mon', hour: '9 AM', activity: 18 },
    { day: 'Tue', hour: '9 AM', activity: 32 },
    { day: 'Wed', hour: '9 AM', activity: 24 }
];

Datum.heatmap(values, {
    x: 'day',
    y: 'hour',
    value: 'activity'
});

Matrix data

Heatmaps can also be created from a two-dimensional array of numeric values.

const values = [
    [18, 32, 24],
    [38, 52, 47],
    [27, 45, 61]
];

Datum.heatmap(values);

Datum automatically converts matrix rows and columns into Y and X positions beginning with 1.

Color range

Use minColor and maxColor to control the color range used to represent cell values.

Datum.heatmap(values, {
    minColor: '#e0f2fe',
    maxColor: Color.Blue
});

Values between the minimum and maximum are automatically interpolated between the two colors.

Values

Set showValues to true to display the numeric value in the center of each cell.

Datum.heatmap(values, {
    showValues: true
});

Use valueColor to control the text color used on lighter cells.

Datum.heatmap(values, {
    showValues: true,
    valueColor: '#1e293b'
});

Cell styling

Use stroke, strokeWidth, andrx to customize the appearance of individual heatmap cells.

Datum.heatmap(values, {
    stroke: '#ffffff',
    strokeWidth: 2,
    rx: 3
});

The rx option controls the corner radius of each cell.

Tooltips

Heatmap cells support discrete tooltips containing the cell coordinates and value.

Tooltips can be disabled for the layer withtooltip: false.

Datum.heatmap(values, {
    tooltip: false
});

Options

{
    x: 'x',
    y: 'y',
    value: 'value',
    minColor: '#e0f2fe',
    maxColor: Color.Blue,
    stroke: '#ffffff',
    strokeWidth: 2,
    rx: 3,
    showValues: false,
    valueColor: '#1e293b',
    tooltip: null
}