# Heatmap

> A color-scaled grid with row and column tracking, for cohorts and schedules.

Component · Pro · https://lodeui.com/components/heatmap

## When to use

- Cohort retention, activity by hour and day, any grid of magnitudes.

## When not to use

- A single row: use a bar chart.

## Installation

```bash
npx shadcn@latest add @lode/heatmap
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion

## Usage

```tsx title="example.tsx"
import { Heatmap } from "@/components/ui/heatmap";

export function Retention({ rows }: { rows: { label: string; values: (number | null)[] }[] }) {
  return <Heatmap rows={rows} columns={["M0", "M1", "M2"]} max={100} />;
}
```

## API reference

### Heatmap

A table of color-scaled cells.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| rows | `{ label; values: (number\|null)[]; meta? }[]` | – | null leaves a cell empty. |
| columns | `string[]` | – | Column headers. |
| max / format / color | `number / (n) => string / string` | – | Scale top, cell text and color. |
| metaLabel | `string` | – | Header for the meta column, e.g. cohort size. |

## Accessibility

- A real <table>; each cell's value is printed, so color isn't the only signal.

## Motion

- Cells pop in along the diagonal; hover highlights the row and column.

## Responsive behavior

- Scrolls horizontally inside its container on narrow screens.

## Performance

- One cell per value; fine up to a few hundred cells.

## Notes for AI

- Use null, not 0, for periods that haven't happened yet.

## Related

- [Bar chart](https://lodeui.com/components/bar-chart) — Bars that grow in and morph between datasets, with a hover readout.
- [Stacked area chart](https://lodeui.com/components/stacked-area-chart) — Stacked series above and below zero, morphing as the range changes.