Heatmap · Kind UI charts

Loading chart…

Support requests by day and hour
Day	Hour	Requests
Mon	08:00	12
Mon	10:00	34
Mon	12:00	48
Mon	14:00	39
Mon	16:00	27
Mon	18:00	8
Tue	08:00	16
Tue	10:00	42
Tue	12:00	56
Tue	14:00	45
Tue	16:00	31
Tue	18:00	0
Wed	08:00	11
Wed	10:00	29
Wed	12:00	No report
Wed	14:00	41
Wed	16:00	24
Wed	18:00	6
Thu	08:00	18
Thu	10:00	47
Thu	12:00	60
Thu	14:00	52
Thu	16:00	33
Thu	18:00	No report

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";

const rows = ["Mon", "Tue", "Wed", "Thu"];
const columns = ["08:00", "10:00", "12:00", "14:00", "16:00", "18:00"];
const data: readonly Chart.HeatmapDatum[] = [
  { row: "Mon", column: "08:00", value: 12 },
  { row: "Mon", column: "10:00", value: 34 },
  { row: "Mon", column: "12:00", value: 48 },
  { row: "Mon", column: "14:00", value: 39 },
  { row: "Mon", column: "16:00", value: 27 },
  { row: "Mon", column: "18:00", value: 8 },
  { row: "Tue", column: "08:00", value: 16 },
  { row: "Tue", column: "10:00", value: 42 },
  { row: "Tue", column: "12:00", value: 56 },
  { row: "Tue", column: "14:00", value: 45 },
  { row: "Tue", column: "16:00", value: 31 },
  { row: "Tue", column: "18:00", value: 0 },
  { row: "Wed", column: "08:00", value: 11 },
  { row: "Wed", column: "10:00", value: 29 },
  { row: "Wed", column: "12:00", value: null },
  { row: "Wed", column: "14:00", value: 41 },
  { row: "Wed", column: "16:00", value: 24 },
  { row: "Wed", column: "18:00", value: 6 },
  { row: "Thu", column: "08:00", value: 18 },
  { row: "Thu", column: "10:00", value: 47 },
  { row: "Thu", column: "12:00", value: 60 },
  { row: "Thu", column: "14:00", value: 52 },
  { row: "Thu", column: "16:00", value: 33 },
];
const scale = Chart.createHeatmapScale({
  domain: [0, 60],
  colors: ["#eff6ff", "#93c5fd", "#2563eb", "#1e3a8a"],
});

export function SupportHeatmap() {
  return (
    <Chart.HeatmapChart
      rows={rows}
      columns={columns}
      data={data}
      scale={scale}
      animate
      missingLabel="No report"
    >
      <Chart.HeatmapGrid
        caption="Support requests by day and hour"
        style={{ borderCollapse: "separate", borderSpacing: 3 }}
        cellProps={() => ({ style: { height: "2rem" } })}
      />
      <Chart.HeatmapLegend label="Requests per two-hour interval" />
      <Chart.HeatmapTooltip valueAnimation="shuffle" />
      <Chart.HeatmapDataTable
        caption="Support requests, exact values"
        style={{
          position: "absolute",
          width: 1,
          height: 1,
          padding: 0,
          overflow: "hidden",
          clipPath: "inset(50%)",
          whiteSpace: "nowrap",
        }}
      />
    </Chart.HeatmapChart>
  );
}

Usage

HeatmapChart owns the matrix model and inspection. Supply ordered domains, numeric records and one scale; compose the grid, legend and tooltip as children.

Composition

<Chart.HeatmapChart
  rows={rows} columns={columns} data={data} scale={scale}
  animate missingLabel="No report"
>
  <Chart.HeatmapGrid caption="Support requests by day and hour" />
  <Chart.HeatmapLegend label="Requests per two-hour interval" />
  <Chart.HeatmapTooltip valueAnimation="shuffle" />
</Chart.HeatmapChart>

Domain order determines equal-cell layout. Missing records and null use patterned cells; zero remains measured. Compose one grid and at most one tooltip per chart.

Compact activity grid

layout gives contributions fixed square cells and visual header controls. The grid keeps row/column headers and explicit cell associations when labels are hidden.

Loading chart…

Contributions by day and week
Day	Week	Contributions
Mon	Week 1	0
Mon	Week 2	1
Mon	Week 3	2
Mon	Week 4	3
Mon	Week 5	4
Mon	Week 6	0
Mon	Week 7	1
Mon	Week 8	2
Mon	Week 9	3
Mon	Week 10	4
Mon	Week 11	0
Mon	Week 12	1
Mon	Week 13	2
Mon	Week 14	3
Mon	Week 15	4
Mon	Week 16	0
Mon	Week 17	1
Mon	Week 18	2
Mon	Week 19	3
Mon	Week 20	4
Mon	Week 21	0
Mon	Week 22	1
Mon	Week 23	2
Mon	Week 24	3
Mon	Week 25	4
Mon	Week 26	0
Tue	Week 1	1
Tue	Week 2	2
Tue	Week 3	3
Tue	Week 4	4
Tue	Week 5	0
Tue	Week 6	1
Tue	Week 7	2
Tue	Week 8	3
Tue	Week 9	4
Tue	Week 10	0
Tue	Week 11	1
Tue	Week 12	2
Tue	Week 13	3
Tue	Week 14	4
Tue	Week 15	0
Tue	Week 16	1
Tue	Week 17	2
Tue	Week 18	3
Tue	Week 19	4
Tue	Week 20	0
Tue	Week 21	1
Tue	Week 22	2
Tue	Week 23	3
Tue	Week 24	4
Tue	Week 25	0
Tue	Week 26	1
Wed	Week 1	2
Wed	Week 2	3
Wed	Week 3	4
Wed	Week 4	0
Wed	Week 5	1
Wed	Week 6	2
Wed	Week 7	3
Wed	Week 8	4
Wed	Week 9	0
Wed	Week 10	1
Wed	Week 11	2
Wed	Week 12	3
Wed	Week 13	4
Wed	Week 14	0
Wed	Week 15	1
Wed	Week 16	2
Wed	Week 17	3
Wed	Week 18	4
Wed	Week 19	0
Wed	Week 20	1
Wed	Week 21	2
Wed	Week 22	3
Wed	Week 23	4
Wed	Week 24	0
Wed	Week 25	1
Wed	Week 26	2
Thu	Week 1	3
Thu	Week 2	4
Thu	Week 3	0
Thu	Week 4	1
Thu	Week 5	2
Thu	Week 6	3
Thu	Week 7	4
Thu	Week 8	0
Thu	Week 9	1
Thu	Week 10	2
Thu	Week 11	3
Thu	Week 12	4
Thu	Week 13	0
Thu	Week 14	1
Thu	Week 15	2
Thu	Week 16	3
Thu	Week 17	4
Thu	Week 18	0
Thu	Week 19	1
Thu	Week 20	2
Thu	Week 21	3
Thu	Week 22	4
Thu	Week 23	0
Thu	Week 24	1
Thu	Week 25	2
Thu	Week 26	3
Fri	Week 1	4
Fri	Week 2	0
Fri	Week 3	1
Fri	Week 4	2
Fri	Week 5	3
Fri	Week 6	4
Fri	Week 7	0
Fri	Week 8	1
Fri	Week 9	2
Fri	Week 10	3
Fri	Week 11	4
Fri	Week 12	0
Fri	Week 13	1
Fri	Week 14	2
Fri	Week 15	3
Fri	Week 16	4
Fri	Week 17	0
Fri	Week 18	1
Fri	Week 19	2
Fri	Week 20	3
Fri	Week 21	4
Fri	Week 22	0
Fri	Week 23	1
Fri	Week 24	2
Fri	Week 25	3
Fri	Week 26	4
Sat	Week 1	0
Sat	Week 2	1
Sat	Week 3	2
Sat	Week 4	3
Sat	Week 5	4
Sat	Week 6	0
Sat	Week 7	1
Sat	Week 8	2
Sat	Week 9	3
Sat	Week 10	4
Sat	Week 11	0
Sat	Week 12	1
Sat	Week 13	2
Sat	Week 14	3
Sat	Week 15	4
Sat	Week 16	0
Sat	Week 17	1
Sat	Week 18	2
Sat	Week 19	3
Sat	Week 20	4
Sat	Week 21	0
Sat	Week 22	1
Sat	Week 23	2
Sat	Week 24	3
Sat	Week 25	4
Sat	Week 26	0
Sun	Week 1	1
Sun	Week 2	2
Sun	Week 3	3
Sun	Week 4	4
Sun	Week 5	0
Sun	Week 6	1
Sun	Week 7	2
Sun	Week 8	3
Sun	Week 9	4
Sun	Week 10	0
Sun	Week 11	1
Sun	Week 12	2
Sun	Week 13	3
Sun	Week 14	4
Sun	Week 15	0
Sun	Week 16	1
Sun	Week 17	2
Sun	Week 18	3
Sun	Week 19	4
Sun	Week 20	0
Sun	Week 21	1
Sun	Week 22	2
Sun	Week 23	3
Sun	Week 24	4
Sun	Week 25	0
Sun	Week 26	1

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";

const rows = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
const columns = Array.from({ length: 26 }, (_, index) => `Week ${index + 1}`);
const data = rows.flatMap((row, r) =>
  columns.map((column, c) => ({ row, column, value: (r + c) % 5 })),
);
const scale = Chart.createHeatmapScale({ domain: [0, 4], colors: ["#eef4eb", "#327448"] });

export function CompactActivityHeatmap() {
  return (
    <Chart.HeatmapChart rows={rows} columns={columns} data={data} scale={scale}>
      <Chart.HeatmapGrid
        caption="Contributions by day and week"
        layout={{ cellSize: 12, gap: 3, rowLabels: "hidden", columnLabels: "hidden" }}
        Cell={() => <span aria-hidden="true" />}
      />
      <Chart.HeatmapTooltip />
    </Chart.HeatmapChart>
  );
}

Numbers use pixels; valid CSS lengths such as "1rem" work too. Omit cellSize for fluid sizing. A width-constrained host retains horizontal scrolling; custom content or native cell styles can enlarge cells. Use min-width: 0 when a flex/grid host must shrink.

Signed comparisons

A symmetric [-20, 20] scale centers zero between below-target orange and above-target blue. Keep the same domain for comparisons; out-of-range values clamp to endpoint colors.

Loading chart…

Regional orders versus monthly target
Region	Month	Difference (%)
North	Apr	-12
North	May	-6
North	Jun	0
North	Jul	14
South	Apr	4
South	May	11
South	Jun	18
South	Jul	7
East	Apr	-20
East	May	-9
East	Jun	-3
East	Jul	No report
West	Apr	2
West	May	0
West	Jun	9
West	Jul	20

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";

const rows = ["North", "South", "East", "West"];
const columns = ["Apr", "May", "Jun", "Jul"];
const data: readonly Chart.HeatmapDatum[] = [
  { row: "North", column: "Apr", value: -12 },
  { row: "North", column: "May", value: -6 },
  { row: "North", column: "Jun", value: 0 },
  { row: "North", column: "Jul", value: 14 },
  { row: "South", column: "Apr", value: 4 },
  { row: "South", column: "May", value: 11 },
  { row: "South", column: "Jun", value: 18 },
  { row: "South", column: "Jul", value: 7 },
  { row: "East", column: "Apr", value: -20 },
  { row: "East", column: "May", value: -9 },
  { row: "East", column: "Jun", value: -3 },
  { row: "East", column: "Jul", value: null },
  { row: "West", column: "Apr", value: 2 },
  { row: "West", column: "May", value: 0 },
  { row: "West", column: "Jun", value: 9 },
  { row: "West", column: "Jul", value: 20 },
];
const scale = Chart.createHeatmapScale({
  domain: [-20, 20],
  colors: ["#9a3412", "#fff7ed", "#1e40af"],
});
const formatValue = (value: number) => `${value > 0 ? "+" : ""}${value}%`;

export function RegionalHeatmap() {
  return (
    <Chart.HeatmapChart
      rows={rows}
      columns={columns}
      data={data}
      scale={scale}
      formatValue={formatValue}
      missingLabel="No report"
      animate
    >
      <Chart.HeatmapGrid
        caption="Regional orders versus target"
        style={{ borderCollapse: "separate", borderSpacing: 3 }}
        cellProps={() => ({ style: { height: "2rem" } })}
      />
      <Chart.HeatmapLegend label="Difference from monthly target" />
      <Chart.HeatmapTooltip valueAnimation="shuffle" />
      <Chart.HeatmapDataTable
        caption="Regional orders versus target, exact values"
        style={{
          position: "absolute",
          width: 1,
          height: 1,
          padding: 0,
          overflow: "hidden",
          clipPath: "inset(50%)",
          whiteSpace: "nowrap",
        }}
      />
    </Chart.HeatmapChart>
  );
}

Use sequential palettes for nonnegative counts. Calendar layouts require consumer-owned day/week domains, date parsing and labels.

Cell materials

Choose plain, paper, clay or glow on cell edges. The central 84% retains the exact scale color; missing cells retain their pattern. Consumer paint overrides can change encoding.

Loading chart…

Support requests by day and hour
Day	Hour	Requests
Mon	08:00	12
Mon	10:00	34
Mon	12:00	48
Mon	14:00	39
Mon	16:00	27
Mon	18:00	8
Tue	08:00	16
Tue	10:00	42
Tue	12:00	56
Tue	14:00	45
Tue	16:00	31
Tue	18:00	0
Wed	08:00	11
Wed	10:00	29
Wed	12:00	No report
Wed	14:00	41
Wed	16:00	24
Wed	18:00	6
Thu	08:00	18
Thu	10:00	47
Thu	12:00	60
Thu	14:00	52
Thu	16:00	33
Thu	18:00	No report

example.tsx

"use client";
import * as Chart from "@kind-ui/charts";
import "@kind-ui/charts/styles.css";

const rows = ["Mon", "Tue", "Wed", "Thu"];
const columns = ["08:00", "10:00", "12:00", "14:00", "16:00", "18:00"];
const data: readonly Chart.HeatmapDatum[] = [
  { row: "Mon", column: "08:00", value: 12 },
  { row: "Mon", column: "10:00", value: 34 },
  { row: "Mon", column: "12:00", value: 48 },
  { row: "Mon", column: "14:00", value: 39 },
  { row: "Mon", column: "16:00", value: 27 },
  { row: "Mon", column: "18:00", value: 8 },
  { row: "Tue", column: "08:00", value: 16 },
  { row: "Tue", column: "10:00", value: 42 },
  { row: "Tue", column: "12:00", value: 56 },
  { row: "Tue", column: "14:00", value: 45 },
  { row: "Tue", column: "16:00", value: 31 },
  { row: "Tue", column: "18:00", value: 0 },
  { row: "Wed", column: "08:00", value: 11 },
  { row: "Wed", column: "10:00", value: 29 },
  { row: "Wed", column: "12:00", value: null },
  { row: "Wed", column: "14:00", value: 41 },
  { row: "Wed", column: "16:00", value: 24 },
  { row: "Wed", column: "18:00", value: 6 },
  { row: "Thu", column: "08:00", value: 18 },
  { row: "Thu", column: "10:00", value: 47 },
  { row: "Thu", column: "12:00", value: 60 },
  { row: "Thu", column: "14:00", value: 52 },
  { row: "Thu", column: "16:00", value: 33 },
];
const scale = Chart.createHeatmapScale({
  domain: [0, 60],
  colors: ["#eff6ff", "#93c5fd", "#2563eb", "#1e3a8a"],
});

export function MaterialHeatmap({ material = "paper" }: { material?: Chart.HeatmapMaterial }) {
  return (
    <Chart.HeatmapChart
      rows={rows}
      columns={columns}
      data={data}
      scale={scale}
      animate
      missingLabel="No report"
    >
      <Chart.HeatmapGrid
        caption="Support requests by day and hour"
        style={{ borderCollapse: "separate", borderSpacing: 3 }}
        cellProps={() => ({ style: { height: "2rem" } })}
        material={material}
      />
      <Chart.HeatmapLegend label="Requests per two-hour interval" />
      <Chart.HeatmapTooltip valueAnimation="shuffle" />
      <Chart.HeatmapDataTable
        caption="Support requests, exact values"
        style={{
          position: "absolute",
          width: 1,
          height: 1,
          padding: 0,
          overflow: "hidden",
          clipPath: "inset(50%)",
          whiteSpace: "nowrap",
        }}
      />
    </Chart.HeatmapChart>
  );
}

Keyboard and motion

Tab enters/leaves the grid; arrows move between cells. Home/End reach row ends; Ctrl+Home/End reach matrix corners. Escape dismisses inspection. See the data grid pattern.

Entrance fades cells diagonally, preserving geometry and colors. Interaction, input changes or resize finish it; reduced motion skips it.

API reference

Native HTML components with an independent Kind context; no Root or Recharts composition is needed.

HeatmapChart

Prop	Type	Default	Description
`rows` / `columns`	`readonly string[]`	Required	Unique, explicitly ordered domains. Records outside them throw.
`data`	`readonly HeatmapDatum[]`	Required	Records shaped as `{ row: string; column: string; value: number \| null }`. Nonfinite values throw.
`scale`	`HeatmapScale`	Required	Shared numeric encoding for grid, legend and tooltip content.
`duplicates`	`"error" \| "first" \| "last" \| "sum"`	`"error"`	Coordinate collision policy. Sum ignores null records; all-null coordinates stay missing. Nonfinite sums throw.
`formatValue`	`(value: number) => string`	`String` conversion	Formats cells, tooltip, legend and data table without changing the numeric scale.
`missingLabel`	`string`	`"Missing"`	Text used for absent or null observations.
`animate`	`boolean`	`false`	Diagonal cell entrance; respects reduced motion and interaction.

createHeatmapScale

Produces the HeatmapScale passed to HeatmapChart.

Prop	Type	Default	Description
`domain`	`readonly [number, number]`	Required	Finite ascending endpoints; their difference must also be finite. Equal endpoints use the palette midpoint.
`colors`	`readonly string[]`	Required	At least two opaque `#rrggbb` stops, evenly spaced in sRGB.

color(value) interpolates opaque hex colors and clamps to the explicit domain. Nonfinite values throw; data does not infer the scale or categorical palette.

HeatmapGrid

Captioned native table with row/column headers and roving grid focus. Empty domains show an empty state; wide matrices scroll horizontally.

Prop	Type	Default	Description
`caption`	`string`	Required	Visible table caption and accessible grid name.
`layout`	`{ cellSize?: number \| string; gap?: number \| string; rowLabels?: "visible" \| "hidden"; columnLabels?: "visible" \| "hidden" }`	Fluid cells; `gap: 3`; labels visible	Optional fixed cells, spacing and independent visual headers.
`material`	`"plain" \| "paper" \| "clay" \| "glow"`	`"plain"`	Static cell-edge finish; missing cells do not receive it.
`Cell`	`ComponentType<HeatmapCellContentProps>`	`HeatmapCellContent`	Custom cell content receives `cell`, `fill` and `formattedValue`. Keep content compatible with grid navigation.
`cellProps`	`(cell: HeatmapCell) => ComponentPropsWithRef<"td">`	—	Native styles, refs and handlers. The grid still owns cell semantics, focus and background color.
`rowLabel` / `columnLabel`	`(key: string) => ReactNode`	Domain key	Customize visible headers; coordinate identities and inspection labels remain domain keys.

cellSize must be positive; gap must be nonnegative, including zero. Numeric values must be finite. Native table style, custom Cell and cellProps keep their existing overrides. Hidden labels retain grid names, header IDs and keyboard navigation; HeatmapDataTable is independent.

Each HeatmapCell retains row/column identities, indices, value and every source record. See native table semantics.

HeatmapCellContent

Formats values and chooses black/white text from hex-fill luminance. Also usable inside a custom Cell.

Prop	Type	Default	Description
`cell`	`HeatmapCell`	Required	Normalized coordinate supplied to a custom cell component.
`fill`	`string`	Required	Opaque scale hex color or the missing-fill CSS variable.
`formattedValue`	`string`	Required	Display text; the default renderer does not format the number again.

HeatmapLegend

Prop	Type	Default	Description
`label`	`string`	Required	Fieldset legend describing the numeric encoding.

Shows scale endpoints, zero for signed domains and the missingLabel swatch. It is a numeric key, without series toggles.

HeatmapTooltip

In-flow inspection below the grid, linked to the active cell by aria-describedby. Focus, hover and touch inspect the same value.

Shuffle affects numeric digits only; assistive text exposes the final value immediately. Reduced motion uses plain text.

Prop	Type	Default	Description
`Content`	`ComponentType<HeatmapCellContentProps>`	Coordinate and value text	Custom content receives the active `cell`, `fill` and `formattedValue`; presentation stays consumer-owned.
`valueAnimation`	`"shuffle"`	Off	Optional digit motion for built-in numeric content. Missing cells remain text; custom `Content` receives no injected animation.

HeatmapDataTable

Static table using the shared model and formatter. The consumer chooses visible or visually hidden presentation; these examples preserve every observation.

Prop	Type	Default	Description
`caption`	`string`	Required	Native data table caption.

createHeatmapModel

Normalizes ordered domains into a two-dimensional cell array, filling missing coordinates with null and retaining source records. Accepts the chart’s rows, columns, data and duplicate policy; invalid input throws.

UsageCopy Anchor Link

Compact activity gridCopy Anchor Link

Signed comparisonsCopy Anchor Link

Cell materialsCopy Anchor Link

Keyboard and motionCopy Anchor Link

API referenceCopy Anchor Link

HeatmapChartCopy Anchor Link

createHeatmapScaleCopy Anchor Link

HeatmapGridCopy Anchor Link

HeatmapCellContentCopy Anchor Link

HeatmapLegendCopy Anchor Link

HeatmapTooltipCopy Anchor Link

HeatmapDataTableCopy Anchor Link

createHeatmapModelCopy Anchor Link

On this page

Usage

Compact activity grid

Signed comparisons

Cell materials

Keyboard and motion

API reference

HeatmapChart

createHeatmapScale

HeatmapGrid

HeatmapCellContent

HeatmapLegend

HeatmapTooltip

HeatmapDataTable

createHeatmapModel