# Heatmap grid (goodtabs UI)

A calendar-style intensity grid in foreground opacities, with a label on every cell.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/heatmap-grid.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/heatmap-grid`

## Usage

```tsx
import { HeatmapGrid } from "@/components/ui/heatmap-grid"

<HeatmapGrid title="Commits per day" unit="commits" start="2026-07-20" values={values} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| values | `number[]` |  | One number per day, oldest first, a whole number of weeks. |
| start | `string` |  | ISO date of the first value, which should be a Monday. |
| unit | `string` |  | What a value counts, used in each cell's label. |
| title | `string` |  | What the chart shows, used as the group label. |

## When to use

- Activity over weeks: commits, deploys, check-ins
- Profile and project pages that show a rhythm at a glance
- When the pattern of busy and quiet days matters more than exact counts

## When not to use

- Exact values or trends: use the area chart
- Fewer than four weeks of data, where a list says more
- Categories without an order, since intensity implies more and less

## Notes for agents

- Server component, no dependencies. Cells are square and fill the width, so height follows the number of weeks
- Each cell is role img with a label like Mon 3 Nov: 5 commits, and also a title for hover
- Five levels: zero is 6 percent foreground, then 20, 40, 65 and 90. There is no colour scale
- Pad values to full weeks and start on a Monday; the grid fills columns top to bottom, seven rows

## The maths

- Level is ceil(value / max × 4) for any value above zero, so the busiest day is always level 4 and a single event is never invisible.
- Opacities 6, 20, 40, 65 and 90 percent step roughly 20 to 25 points apart, so neighbouring levels stay distinguishable in both themes.
- The grid has weeks columns and 7 rows; cell i sits in week floor(i / 7) and row i mod 7, which is what grid-flow-col gives.

Docs: https://ui.goodtabs.co/components/heatmap-grid