## Heatmap Grid (S—057)

A contribution-style calendar heatmap with a roving cursor and a readout that follows it.

- URL: https://sundaeui.dev/components/heatmap-grid
- Category: Cards & data visualization · Art direction: Understated
- Access: Sundae Pro (authenticated install)
- Stack: React 18+, TypeScript, plain CSS; dependencies: none
- Install: `npx shadcn@latest add https://sundaeui.dev/r/heatmap-grid.json`
- Tags: heatmap, chart, data, github, activity, calendar

Weeks run left to right, days top to bottom, five intensity levels. Cells pop in with a diagonal stagger.
Hover a cell or focus the grid and use arrow keys; the header reads out that day.

### Usage

```tsx
import { HeatmapGrid } from '@/components/sundae/heatmap-grid'

<HeatmapGrid weeks={weeks} describe={(w, d, v) => `${v} commits · week ${w + 1}`} />
```

### Props

- `weeks` (`number[][]`, required): Columns of seven values.
- `describe` (`(week, day, value) => string`, required): Text for a cell.
- `scale` (`string[]`, default `green scale`): Five colours, empty to hottest.
- `title` (`string`, default `'Activity'`): Heading.
- `fill` (`'dark' | 'light'`, default `'dark'`): Surface: dark or light.

### When to use

- Activity, streaks, bookings or usage over weeks.

### When not to use

- Exact comparisons between days: use bars.

### Accessibility

- A single focusable grid with arrow-key navigation, so it is one tab stop instead of a hundred.
- Every cell has an aria-label; the readout is a polite live region.
- Reduced motion removes the pop-in.

### Keyboard

- Arrow keys: Move between days
- Home / End: First / last week