# Heatmap

Activity heatmap in weekly columns or as a calendar month, in four shades of one colour that fill in as a wave. Drag across it to read each day’s value, with a gentle tap per day.

> Composed · Pro · Data Display — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/heatmap
```

## Import

```tsx
import { formatHeatmapDate, Heatmap, HeatmapReadout } from "@/components/ui/heatmap/heatmap";
```

## Variants

- `contributions` — Commits: `npx @lumioui/cli add pro/heatmap-contributions`
- `focus` — Focus: `npx @lumioui/cli add pro/heatmap-focus`
- `training` — Training: `npx @lumioui/cli add pro/heatmap-training`

## Props

### Heatmap

| Prop | Type | Notes |
| --- | --- | --- |
| `data` | `HeatmapDatum[] | Record<string, number>` | Values per day — an array of `{ date, value }` or a `{ "2026-09-14": 3 }` map. |
| `layout?` | `"weeks" | "month"` | "weeks" — columns of weeks with month labels; "month" — one calendar month. Default "weeks". |
| `endDate?` | `string` | Last day shown in the weeks layout (`YYYY-MM-DD`). Default today. |
| `weeks?` | `number` | Week columns in the weeks layout. Default 26. |
| `month?` | `string` | Month for the month layout, `YYYY-MM`. Default the month of `endDate`. |
| `weekStartsOn?` | `0 | 1` | 0 = Sunday-first rows, 1 = Monday-first. Default 0. |
| `thresholds?` | `[number, number, number, number]` | Four ascending thresholds for levels 1–4. Default: any activity, then quarters of the max. |
| `color?` | `string` | Cell colour at full intensity. Default the primary/accent colour. |
| `gap?` | `number` | Gap between cells. Default 3 (weeks) / 6 (month). |
| `showMonthLabels?` | `boolean` | Month labels above the week columns. Default true. |
| `showDayLabels?` | `boolean` | Mon / Wed / Fri labels beside the rows. Default true. |
| `showLegend?` | `boolean` | "Less ▢▢▢▢▢ More" key under the grid. Default false. |
| `selected?` | `string | null` | Controlled selected day. `null` for none. |
| `defaultSelected?` | `string | null` | Uncontrolled initial selection. |
| `onSelectedChange?` | `(date: string | null, value: number) => void` | Fires when touch lands on a different day. |
| `accessibilityLabel?` | `string` | Screen-reader summary. Default "Activity heatmap". |
| `className?` | `string` | — |

### HeatmapReadout

| Prop | Type | Notes |
| --- | --- | --- |
| `swapKey` | `string | number | null | undefined` | Change this (e.g. the selected date) to swap the readout in place. |
| `className?` | `string` | — |

Source: https://lumioui.com/components/heatmap