Heatmap

ImportCopy Anchor Link

import { Heatmap } from '@nizivo/charts/heatmap';

Static or interactiveCopy Anchor Link

Server. Heatmap has no 'use client' and renders no island. The grid is hidden from assistive technology, which reads the data table instead: one row per row of the grid, one column per column, every value as text. Figma asks for focusable cells or a table alternative; the table is it, and tableView="details" shows it to everyone. How to choose.

ExamplesCopy Anchor Link

BasicCopy Anchor Link

import type { JSX } from 'react';
import { Heatmap } from '@nizivo/charts/heatmap';

interface Slot {
  day: string;
  hour: string;
  orders: number | null;
}

const DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];

const HOURS = ['00', '02', '04', '06', '08', '10', '12', '14', '16', '18', '20', '22'];

// Figma 03's heatmap: orders per two hours, a week, busiest at midday and in the evening.
const ORDERS: number[][] = [
  [2, 1, 1, 9, 18, 21, 24, 52, 38, 22, 12, 9],
  [3, 2, 8, 11, 19, 22, 36, 40, 37, 23, 20, 10],
  [2, 1, 6, 12, 20, 24, 35, 44, 41, 25, 18, 9],
  [3, 2, 7, 10, 21, 23, 37, 47, 39, 26, 19, 11],
  [4, 2, 6, 12, 22, 26, 39, 50, 46, 31, 24, 14],
  [11, 3, 10, 21, 24, 36, 38, 52, 51, 37, 22, 4],
  [9, 4, 3, 8, 16, 29, 34, 45, 40, 30, 21, 6],
];

const WEEK: Slot[] = DAYS.flatMap((day, d) =>
  HOURS.map((hour, h) => ({ day, hour, orders: ORDERS[d]?.[h] ?? null })),
);

export function HeatmapExample(): JSX.Element {
  return (
    <Heatmap
      title="Orders by hour"
      summary="Orders per two hours, Oct 5–11"
      data={WEEK}
      x="hour"
      y="day"
      value="orders"
      labels={{ row: 'Day' }}
    />
  );
}

Missing values and the tableCopy Anchor Link

import type { JSX } from 'react';
import { Heatmap } from '@nizivo/charts/heatmap';

interface Slot {
  day: string;
  hour: string;
  orders: number | null;
}

const DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];

const HOURS = ['00', '02', '04', '06', '08', '10', '12', '14', '16', '18', '20', '22'];

// Figma 03's heatmap: orders per two hours, a week, busiest at midday and in the evening.
const ORDERS: number[][] = [
  [2, 1, 1, 9, 18, 21, 24, 52, 38, 22, 12, 9],
  [3, 2, 8, 11, 19, 22, 36, 40, 37, 23, 20, 10],
  [2, 1, 6, 12, 20, 24, 35, 44, 41, 25, 18, 9],
  [3, 2, 7, 10, 21, 23, 37, 47, 39, 26, 19, 11],
  [4, 2, 6, 12, 22, 26, 39, 50, 46, 31, 24, 14],
  [11, 3, 10, 21, 24, 36, 38, 52, 51, 37, 22, 4],
  [9, 4, 3, 8, 16, 29, 34, 45, 40, 30, 21, 6],
];

const WEEK: Slot[] = DAYS.flatMap((day, d) =>
  HOURS.map((hour, h) => ({ day, hour, orders: ORDERS[d]?.[h] ?? null })),
);

export function HeatmapDetailsExample(): JSX.Element {
  return (
    <Heatmap
      title="Orders by hour"
      data={WEEK.map((slot) =>
        slot.day === 'Sun' && Number(slot.hour) < 10 ? { ...slot, orders: null } : slot,
      )}
      x="hour"
      y="day"
      value="orders"
      tableView="details"
      labels={{ row: 'Day', missing: 'Closed' }}
    />
  );
}

StatusCopy Anchor Link

import type { JSX } from 'react';
import { Heatmap } from '@nizivo/charts/heatmap';

interface Slot {
  day: string;
  hour: string;
  orders: number | null;
}

const DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];

const HOURS = ['00', '02', '04', '06', '08', '10', '12', '14', '16', '18', '20', '22'];

// Figma 03's heatmap: orders per two hours, a week, busiest at midday and in the evening.
const ORDERS: number[][] = [
  [2, 1, 1, 9, 18, 21, 24, 52, 38, 22, 12, 9],
  [3, 2, 8, 11, 19, 22, 36, 40, 37, 23, 20, 10],
  [2, 1, 6, 12, 20, 24, 35, 44, 41, 25, 18, 9],
  [3, 2, 7, 10, 21, 23, 37, 47, 39, 26, 19, 11],
  [4, 2, 6, 12, 22, 26, 39, 50, 46, 31, 24, 14],
  [11, 3, 10, 21, 24, 36, 38, 52, 51, 37, 22, 4],
  [9, 4, 3, 8, 16, 29, 34, 45, 40, 30, 21, 6],
];

const WEEK: Slot[] = DAYS.flatMap((day, d) =>
  HOURS.map((hour, h) => ({ day, hour, orders: ORDERS[d]?.[h] ?? null })),
);

export function HeatmapStatusExample(): JSX.Element {
  return (
    <div>
      <Heatmap
        title="Orders by hour"
        status="loading"
        data={[] as Slot[]}
        x="hour"
        y="day"
        value="orders"
      />
      <Heatmap title="Orders by hour" data={[] as Slot[]} x="hour" y="day" value="orders" />
      <Heatmap title="Orders by hour" status="error" data={WEEK} x="hour" y="day" value="orders" />
    </div>
  );
}

The rampCopy Anchor Link

The colours are Figma's: chart/primary at 8, 25, 45, 70 and 100 %, over the surface in light and dark. heatmapStep(value, max) is the rule, exported so a server can bucket the same way:

1. Five equal widths over 0 to the largest value: 0 to 20 % of it is step 1, up to 40 % step 2, and so on, the largest value step 5.
2. 0 and negative values are step 1; when the largest value is 0, every value is step 1.
3. A value that is not a finite number is a cell with no value: drawn as a hairline only, and labels.missing ("—") in the table.

Rows and columns come in the order they first appear in data (heatmapGrid).

PropsCopy Anchor Link

Server component. Props: HeatmapProps<T>. Source: src/heatmap/heatmap.tsx.

• Also takes every <figure> attribute except children, title.

render takes an element, or, in client code, a function of the props and this state (ChartFrameState):

x (the column, such as an hour), y (the row, such as a day) and value are an Accessor, as in every chart. xTicks labels every every-th column, or at most max of them (default 6: every other column of twelve).

labels takes Partial<HeatmapLabels>, on top of ChartFrame's:

Other exportsCopy Anchor Link

HEATMAP_STEPS constant

import { HEATMAP_STEPS } from '@nizivo/charts/heatmap'

The ramp's steps: chart/primary at 8, 25, 45, 70 and 100 % (Figma).

const HEATMAP_STEPS: number

HeatmapLabels type

import type { HeatmapLabels } from '@nizivo/charts/heatmap'

Heatmap's strings (§16.4), with ChartFrame's. Never concatenated: each is a whole label.

Name	Type	Default	Description
fewerrequired	string	–	Before the scale's lightest swatch.
missingrequired	string	–	In the table for a cell with no value.
morerequired	string	–	After its strongest swatch.
rowrequired	string	–	The data table's corner header, over the row names (for example "Day").

HeatmapProps type

import type { HeatmapProps } from '@nizivo/charts/heatmap'

Heatmap's props: its data and formats in the charts' one shape (_core/api.ts) and ChartFrame's, the <figure>'s attributes included. It draws its own labels and scale, is never mirrored and makes no keyboard claim, so axes, legend, xDirection and interaction are its own.

The props of Heatmap, listed above.

heatmapGrid function

import { heatmapGrid } from '@nizivo/charts/heatmap'

The rows and columns in the order they first appear, and each cell's value.

function heatmapGrid(cells: ReadonlyArray<{ row: string; column: string; value: number | null; }>): { rows: string[]; columns: string[]; values: Map<string, number | null>; max: number; }

heatmapLabels constant

import { heatmapLabels } from '@nizivo/charts/heatmap'

English defaults (§16.4); pass labels to translate per instance.

const heatmapLabels: HeatmapLabels

heatmapStep function

import { heatmapStep } from '@nizivo/charts/heatmap'

A value's step on the ramp, 1 to 5, or null for no value: five equal widths over 0 to max. 0 and below are step 1, max is step 5; with max at 0 or below every value is step 1.

function heatmapStep(value: number | null, max: number): number | null

Data attributes and slotsCopy Anchor Link

Inside the ChartFrame root, which carries nz-heatmap (with axes="none" and interaction="none"):

CSS hooksCopy Anchor Link

Layers: nz.components. Classes: .nz-chart-frame-body, .nz-heatmap, .nz-heatmap-cell, .nz-heatmap-column, .nz-heatmap-grid, .nz-heatmap-label, .nz-heatmap-row, .nz-heatmap-scale, .nz-heatmap-swatch.

Cells are square, at most 32 px, and shrink together in a narrow chart. While loading, empty or failed the body keeps Figma's seven-row height.