Recipe

Cohort retention report explainer

A step-by-step recipe for building a weekly cohort retention dashboard that shows exactly how many users come back after day 0.

Ingredients

  • Events table with user_id and timestamp
  • Weekly cohort bucket (ISO week of first seen)
  • Retention window array: day 1, 3, 7, 14, 30
  • Chart library of choice (Recharts, Chart.js, or Vega-Lite)

Steps

  1. Assign cohort. For every user, find the earliest event timestamp and map it to an ISO week string (2026-W22).
  2. Build activity log. Join events back to the cohort table on user_id. Keep only rows where the event falls inside one of the retention windows.
  3. Pivot to matrix. Rows = cohort week, columns = retention day. Each cell is the count of users active in that window divided by the cohort size.
  4. Render heatmap. Use a diverging color scale anchored at the cohort average. Highlight cells above 40 % retention.
  5. Add sparklines. Append a small trend line per cohort so stakeholders can spot decay acceleration without reading raw numbers.

Output

A single-page dashboard with a cohort×window heatmap, a week-over-week delta column, and a summary KPI row showing the blended Day-7 retention across the last four cohorts.

Pro tip: Exclude the acquisition day (day 0) from the denominator adjustment so the report answers “of the people who showed up once, how many came back?” — not “how many logged in twice on day 0?”

← Back to docsMore recipes