Cohort Retention Heatmap React component
A single-hue cohort retention matrix with percentage and user views, weighted retention, hover details and unobserved periods kept apart from zero.
About the Cohort Retention Heatmap component
Cohort Retention Heatmap shows whether newer customers stay longer than older ones. Each row is a signup cohort and each column is time since signup, and the cells deepen in a single hue as retention rises.
A switch moves between percentages and user counts, and the headline gives weighted retention for the first period. Periods that have not happened yet show a dash, so they can never be mistaken for zero.
When to use it
Use it for subscription, product and growth dashboards, where you need to compare signup groups over the same time since joining.
For a single retention curve over time, a line chart is simpler to read.
Installation
Add the Cohort Retention Heatmap component to your project with the shadcn CLI. It lands in components/cohort-retention-heatmap.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/cohort-retention-heatmapOr copy the source by hand and install its dependencies:
npm install motionProps
<CohortRetentionHeatmap /> accepts 7 props, all optional. It also accepts the usual <section> attributes, like className, style, id and aria-*, and passes them to its root element.
| Prop | Type | Default |
|---|---|---|
| title | string | "Retention by cohort" |
| subtitle | string | "Retention gets stronger with every new cohort." |
| theme | "dark" | "light" | "dark" |
| cohorts | { label: string; size: number; retained: (number | null)[] }[] | COHORTS |
| periodLabel | string | "Month" |
| color The single hue the cells build up in. | string | "#5E6AD2" |
| defaultMode | "percentage" | "users" | "percentage" |
- titlestringDefault: "Retention by cohort"
- subtitlestringDefault: "Retention gets stronger with every new cohort."
- theme"dark" | "light"Default: "dark"
- cohorts{ label: string; size: number; retained: (number | null)[] }[]Default: COHORTS
- periodLabelstringDefault: "Month"
- color
The single hue the cells build up in.
stringDefault: "#5E6AD2" - defaultMode"percentage" | "users"Default: "percentage"
npm dependencies
Installed for you by the shadcn CLI.
Cohort Retention Heatmap FAQ
- What does null mean in retained?
- That period has not been observed yet. The cell is disabled and shows a dash, which keeps it separate from a real zero.
- How is the headline worked out?
- It adds up period 1 users across every cohort that has reached it and divides by those cohorts' sizes, so bigger cohorts count for more.
- Can I change the colour?
- Yes, with the color prop. The whole scale builds from that one hue.
- How does it fit on a phone?
- The table keeps its width and scrolls sideways inside the card.
