Ripl

Appearance

Heatmap Chart ​

The Heatmap Chart lays one value out across two categorical axes as a grid of cells, coloring each cell by its magnitude. Reach for it when the pattern across a pair of dimensions matters more than any single reading — time-of-day against day-of-week, cohort against week, sensor against hour. keyX, keyY and value bind the cells, xCategories and yCategories fix the axis order (a missing pair leaves a gap), and gradient takes a [low, high] color tuple that also drives the continuous color legend. borderRadius, labels and format handle the finish, and cells tween between colors on update. Canvas by default, SVG or a terminal by passing a context.

NOTE

For the full API, see the Charts API Reference.

Example ​

Usage ​

ts
import {
    createHeatmapChart,
} from '@ripl/charts';

const chart = createHeatmapChart('#container', {
    data: [/* ... */],
    keyX: 'hour',
    keyY: 'day',
    value: 'value',
    xCategories: ['9am', '10am', '11am'],
    yCategories: ['Mon', 'Tue', 'Wed'],
});

Data Format ​

Each item is one cell, identified by its x and y category and carrying the value that drives its color. xCategories and yCategories fix the axis order (and which cells exist), so a missing combination renders no cell:

ts
const data = [
    {
        day: 'Mon',
        hour: '9am',
        value: 42,
    },
    {
        day: 'Mon',
        hour: '10am',
        value: 71,
    },
    {
        day: 'Tue',
        hour: '9am',
        value: 18,
    },
];

const xCategories = ['9am', '10am', '11am'];
const yCategories = ['Mon', 'Tue', 'Wed'];

Options ​

A full configuration for this chart. The options every chart shares — padding, title, animation, theme and the rest — behave the same everywhere and are documented on Shared Options.

ts
createHeatmapChart('#container', {
    data,
    keyX: 'hour',
    keyY: 'day',
    value: 'sessions',
    xCategories: HOURS,
    yCategories: DAYS,
    // Color stops interpolated low→high: two for a simple ramp, or any number of stops —
    // a built-in `COLOR_SCHEME_*` palette works here too.
    gradient: ['#dbeafe', '#1d4ed8'],
    borderRadius: 4,
    labels: true,
    // A color-scale legend, not the per-series legend other charts use.
    legend: {
        orientation: 'horizontal',
        thickness: 12,
        segments: 6,
    },
    tooltip: true,
    axis: {
        x: { title: 'Hour' },
        y: { title: 'Day' },
    },
    format: 'number',
});

Events ​

Subscribe with chart.on(...). A handler receives an Event object, not the payload directly — the payload is on event.data, and carries the interacted datum plus its { x, y } anchor in chart pixels. event.target and event.stopPropagation() are also available.

ts
// Emitted when a cell is clicked.
chart.on('cellclick', event => console.log(event.data)); // event.data: HeatmapChartCellEvent
// Emitted when the pointer enters a cell.
chart.on('cellenter', event => console.log(event.data)); // event.data: HeatmapChartCellEvent
// Emitted when the pointer leaves a cell.
chart.on('cellleave', event => console.log(event.data)); // event.data: HeatmapChartCellEvent