# Heatmap (/docs/charts/components/heatmap)

Use a heatmap to show how one measure varies across two ordered sets, like days and hours, when the pattern matters more than each exact value.

<Example caption="Hover a cell, or focus the grid and press the arrow keys, to see its value.">
<Basic />

```tsx
"use client";

import { createHeatmapScale, HeatmapChart, type HeatmapDatum } from "@kind-ui/charts";

const rows = ["Mon", "Tue", "Wed", "Thu"];
const columns = ["08:00", "10:00", "12:00", "14:00", "16:00", "18:00"];
const data: 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 = createHeatmapScale({
  domain: [0, 60],
  colors: ["#eff6ff", "#93c5fd", "#2563eb", "#1e3a8a"],
});

export default function SupportHeatmap() {
  return (
    <HeatmapChart
      config={{}}
      rows={rows}
      columns={columns}
      data={data}
      scale={scale}
      missingLabel="No report"
      aria-label="Support requests by day and hour"
    >
      <HeatmapChart.Grid caption="Support requests by day and hour" />
      <HeatmapChart.Tooltip />
      <HeatmapChart.Legend label="Requests per two-hour interval" />
    </HeatmapChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/heatmap-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
HeatmapChart
├── HeatmapChart.Grid
├── HeatmapChart.Tooltip
├── HeatmapChart.Legend
├── HeatmapChart.DataTable
└── HeatmapChart.Content
```

`HeatmapChart` holds the rows, columns, data and color scale, and draws only the parts you add. The grid is an HTML table with a header for each row and column, so screen readers can read it like one. Heatmaps have no series, so pass `config={{}}`. `HeatmapChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Rows, Columns and Data [#rows-columns-and-data]

`rows` and `columns` set the order of the grid. `data` has one `{ row, column, value }` record per cell; a record whose row or column isn't listed throws. A missing record or a `null` value shows as a patterned cell labeled `missingLabel`, while `0` is a measured value. When two records share a cell, `duplicates` decides what happens: `error` (the default), `first`, `last` or `sum`.

`formatValue` formats the value in the cells, tooltip and legend, like ``(value) => `${value}%` ``, without changing the colors.

### Color Scale [#color-scale]

`createHeatmapScale` maps a numeric `domain` to two or more `#rrggbb` colors, spaced evenly. Values outside the domain take the nearest end color. For values above and below a target, center the domain on zero with a neutral middle color:

```tsx
const scale = createHeatmapScale({
  domain: [-20, 20],
  colors: ["#9a3412", "#fff7ed", "#1e40af"],
});
```

Keep the same scale when you compare two heatmaps, so the same color means the same value. `HeatmapChart.Legend` shows the scale's ends, zero for a domain that crosses it, and the missing-cell swatch.

### Compact Grids [#compact-grids]

Set `layout` on the grid for fixed square cells: `cellSize`, `gap`, and `rowLabels` or `columnLabels` set to `hidden`. Hidden labels stay readable by screen readers, and the tooltip still names each cell. Pass `Cell` to change what each cell shows, like nothing:

<Example caption="Square cells shrink with the page. Hover a cell to see its day and week.">
<Compact />

```tsx
"use client";

import { createHeatmapScale, HeatmapChart } from "@kind-ui/charts";

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 * 3 + c * 7) % 5 })),
);

const scale = createHeatmapScale({ domain: [0, 4], colors: ["#e8f3ec", "#2f7d4a"] });

export default function ActivityHeatmap() {
  return (
    <div style={{ containerType: "inline-size" }}>
      <HeatmapChart
        config={{}}
        rows={rows}
        columns={columns}
        data={data}
        scale={scale}
        aria-label="Contributions by day and week"
      >
        <HeatmapChart.Grid
          caption="Contributions by day and week"
          layout={{
            cellSize: "clamp(6px, calc((100cqw - 84px) / 26), 28px)",
            gap: 3,
            rowLabels: "hidden",
            columnLabels: "hidden",
          }}
          Cell={() => null}
        />
        <HeatmapChart.Tooltip />
      </HeatmapChart>
    </div>
  );
}
```
</Example>

Set `material="clay"` or `"glow"` on the grid for a finish on the cell edges; see [Materials](../guides/materials.mdx).

### Keyboard [#keyboard]

Focus the grid and press the arrow keys to move between cells, which shows the tooltip. Home and End go to the ends of a row, Ctrl+Home and Ctrl+End to the first and last cells, and Escape dismisses the tooltip. Pass `valueAnimation="shuffle"` to the tooltip to animate its digits.

### Motion [#motion]

Pass `animate` to fade the cells in diagonally when the chart mounts. Heatmaps don't animate by default. When the reader prefers reduced motion, cells appear without fading in. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart shows a placeholder grid, which holds still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default):

```tsx
<HeatmapChart loading={isPending} loadingLabel="Loading requests" {...props}>
```

## API Reference [#api-reference]

### HeatmapChart [#heatmapchart]

### HeatmapChartOptions

| Prop               | Type                                                                                                                                                                                                                            | Description                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `aria-label?`      | `string \| undefined`                                                                                                                                                                                                           | Defines a string value that labels the current element. The chart's accessible name. Pass this or `aria-labelledby`.                        |
| `aria-labelledby?` | `string \| undefined`                                                                                                                                                                                                           | Identifies the element (or elements) that labels the current element. The id of an element that names the chart. Pass this or `aria-label`. |
| `frameProps?`      | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined `` | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                                      |
| `rows`             | `readonly string[]`                                                                                                                                                                                                             | Row keys, top to bottom. A record whose row isn't listed throws.                                                                            |
| `columns`          | `readonly string[]`                                                                                                                                                                                                             | Column keys, left to right. A record whose column isn't listed throws.                                                                      |
| `data`             | `readonly HeatmapDatum[]`                                                                                                                                                                                                       | One `{ row, column, value }` record per cell. A missing record or a `null` value is a missing cell, not zero.                               |
| `duplicates?`      | `"error" \| "first" \| "last" \| "sum"`                                                                                                                                                                                         | What to do when two records share a cell: throw, keep the first or last, or add them up. Default: `"error"`                                 |
| `scale`            | `HeatmapScale`                                                                                                                                                                                                                  | Maps each value to a color for the cells and the legend. Make one with `createHeatmapScale`.                                                |
| `formatValue?`     | `((value: number) => string) \| undefined`                                                                                                                                                                                      | Formats values in the cells, tooltip and legend without changing the scale. Default: `String`                                               |
| `missingLabel?`    | `string \| undefined`                                                                                                                                                                                                           | What cells with no record or a `null` value show. Default: `"Missing"`                                                                      |
| `animate?`         | `boolean \| undefined`                                                                                                                                                                                                          | Fades the cells in diagonally on mount. Reduced motion skips it. Default: `false`                                                           |
| `loading?`         | `boolean \| undefined`                                                                                                                                                                                                          | Shows a placeholder grid and hides the legend and tooltip while the data is on its way.                                                     |
| `loadingLabel?`    | `string \| undefined`                                                                                                                                                                                                           | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                                                  |

### HeatmapChart.Grid [#heatmapchartgrid]

### HeatmapGridOptions

| Prop           | Type                                                                                                                                             | Description                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `caption`      | `string`                                                                                                                                         | Names the grid, and shows above it as the table caption.                                                                 |
| `layout?`      | `{ cellSize?: number \| string; gap?: number \| string; rowLabels?: "visible" \| "hidden"; columnLabels?: "visible" \| "hidden"; } \| undefined` | Fixed square cells, spacing, and whether row and column labels show. Hidden labels stay readable by screen readers.      |
| `material?`    | `"clay" \| "glow" \| "plain"`                                                                                                                    | A finish for the cell edges. The center of each cell keeps the exact scale color.                                        |
| `Cell?`        | `ComponentType<HeatmapCellContentProps> \| undefined`                                                                                            | Renders the inside of each cell. Receives the `cell`, its `fill` and its `formattedValue`. Default: `HeatmapCellContent` |
| `cellProps?`   | `((cell: HeatmapCell) => ComponentPropsWithRef<"td">) \| undefined`                                                                              | Props for each cell's `td`, like styles and handlers. The grid keeps its focus and keyboard handling.                    |
| `rowLabel?`    | `((row: string) => ReactNode) \| undefined`                                                                                                      | Renders a row header. Receives the row key, which stays the accessible name.                                             |
| `columnLabel?` | `((column: string) => ReactNode) \| undefined`                                                                                                   | Renders a column header. Receives the column key, which stays the accessible name.                                       |

### HeatmapChart.Tooltip [#heatmapcharttooltip]

### HeatmapTooltipOptions

| Prop              | Type                                                  | Description                                                                                        |
| ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `Content?`        | `ComponentType<HeatmapCellContentProps> \| undefined` | Renders the tooltip. Receives the active `cell`, its `fill` and its `formattedValue`.              |
| `valueAnimation?` | `"shuffle"`                                           | Set to `"shuffle"` to animate the digits of the built-in value. Custom `Content` is left as it is. |

### HeatmapChart.Legend [#heatmapchartlegend]

### HeatmapLegendOptions

| Prop    | Type     | Description                                                  |
| ------- | -------- | ------------------------------------------------------------ |
| `label` | `string` | Describes what the colors measure, like "Requests per hour". |

### createHeatmapScale [#createheatmapscale]

### CreateHeatmapScaleOptions

| Prop     | Type                        | Description                                                              |
| -------- | --------------------------- | ------------------------------------------------------------------------ |
| `domain` | `readonly [number, number]` | Finite ascending endpoints. A constant domain uses the palette midpoint. |
| `colors` | `readonly string[]`         | Evenly spaced opaque sRGB stops, each in #rrggbb format.                 |

<Caption>
`HeatmapChart.DataTable` takes a `caption` and shows the same records as a plain table. Each part also takes the props of its HTML element, like `className` and `style`.
</Caption>