Heatmap Table React component
A cohort retention table coloured like a heatmap: one row per signup month, one column per month after, cells shaded by how many users stayed, a percent / users switch, a weighted average row and a crosshair that compares any cell with the average.
About the Heatmap Table component
Heatmap Table turns a cohort retention table into something you can read at a glance: each signup month is a row, each month after signup is a column, and every cell is shaded by how many of those users were still active, so improving or slipping cohorts stand out immediately.
Switch between percentages and user counts, read the weighted average along the bottom, and hover, tap or arrow through any cell to see how it compares with the average for that month.
When to use it
Use it for product retention, subscription churn, repeat purchase rates, feature adoption over time and any 'what happened to the people who started in month X' question.
For a single retention curve, a line chart is clearer; the table shines when comparing many cohorts.
Installation
Add the Heatmap Table component to your project with the shadcn CLI. It lands in components/heatmap-table.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/heatmap-tableOr copy the source by hand and install its dependencies:
npm install clsx tailwind-mergeProps
<HeatmapTable /> accepts 7 props, all optional. It also accepts the usual <div> attributes, like className, style, id and aria-*, and passes them to its root element.
| Prop | Type | Default |
|---|---|---|
| theme | "dark" | "light" | "dark" |
| title | string | "Retention by signup cohort" |
| subtitle | string | "Share of each month's signups still active in later months" |
| cohorts | { label: string; size: number; retained: number[] }[] | DEFAULT_COHORTS |
| periodLabel Header prefix for the periods, e.g. "Month" → "Month 0", "Month 1"… | string | "Month" |
| mode Show percentages or user counts in the cells. | "percent" | "count" | "percent" |
| color Colour of the strongest cells. | string | — |
- theme"dark" | "light"Default: "dark"
- titlestringDefault: "Retention by signup cohort"
- subtitlestringDefault: "Share of each month's signups still active in later months"
- cohorts{ label: string; size: number; retained: number[] }[]Default: DEFAULT_COHORTS
- periodLabel
Header prefix for the periods, e.g. "Month" → "Month 0", "Month 1"…
stringDefault: "Month" - mode
Show percentages or user counts in the cells.
"percent" | "count"Default: "percent" - color
Colour of the strongest cells.
string
npm dependencies
Installed for you by the shadcn CLI.
Heatmap Table FAQ
- What data does it need?
- cohorts is { label, size, retained }[], where retained[k] is how many of that cohort were still active in period k (retained[0] is normally the full size). Newer cohorts have shorter arrays, which makes the triangle.
- How are the colours scaled?
- Cells blend from a base colour to color by retention divided by the highest retention after period 0, so the differences between later periods stay visible.
- Can I show weeks instead of months?
- Yes, set periodLabel="Week" and pass weekly cohorts; the headers become W0, W1 and so on.
- Is it accessible?
- It's a real <table> with row and column headers. The table is focusable, arrow keys move between cells, and the footer announces the selected cell politely.
