Cohort retention
NewA retention card: weekly or monthly cohorts as a textured stream from oldest to newest, a tooltip with a leader to the band, week 1 by cohort and the best one flagged.
cohort-retention/cohort-retention.tsxRetention
Weekly cohorts
24%still active at week 8
- Week 1 average
- 67%
- Best cohort
- Sep 29
The live component, numbered part by part. Every measurement is read from it as it is drawn. Point at a row to outline its part, or at a part to find its row.
The choices it offers, each value drawn live and the default marked, with how to pick one.
When to use
- A product’s signups grouped by the week or month they joined, where the question is how many stay and whether newer cohorts stay better.
- A dashboard tile that has to carry one figure (the share still active at the oldest cohort’s age) with the shape behind it a hover away.
- Comparing cohorts at the same age: the week 1 bars line every cohort up at its first week, with the best one flagged.
- Up to a dozen cohorts. Each gets its own colour and texture, so bands stay apart in print, for colour-blind readers and when isolated.
When not to use
- A full retention table with every cohort at every age. Use a triangle heatmap; the stream shows people over time, not shares by age.
- More than a dozen cohorts. The bands get too thin to point at; switch to monthly, or show the latest dozen.
- Revenue retention, where expansion can push a cohort over 100%. The bands only shrink; use a line per cohort instead.
- A single number for a status bar. Show the headline as a stat with its change; the chart needs about 300 px to read.
- Live counts that change by the minute. The card reads a settled matrix, one value per cohort and period.
Reading the headline
- The figure is the share of the oldest cohort still active at its latest period:
24% still active at week 8. Cohorts that have reached the same period are averaged in by size. - The total under it is everyone active today, across every cohort.
- With a cohort hovered or held, both read that cohort alone, and the line says which:
of Sep 29 still active at week 4. - The period in progress reads
so farin the tooltip, and a cohort still in its week 1 has a dashed bar and no week 1 figure.
Weekly or monthly
Weekly cohorts show a change in onboarding within days, but each band is a week of signups and twelve weeks is about the most the stream holds. Monthly cohorts carry half a year in six bands. When both are passed, W / M reads the headline, the stream, the bars and the rows again from the other matrix, and lets go of any cohort held.
Each one drawn with the component itself, used well or badly.
The card writes most of its own words from the data: the cohorts’ dates, the shares and the counts. What you pass is the title and the metric.
- A title of a word or two, in sentence case:
Retention,Paid retention. The subtitle already says Weekly or Monthly cohorts, so leave the cadence out. - A metric of one word that fits
still … at week 8and after the total:active,paying,posting. - Shares are whole percentages and counts have thousands separators; don’t round the data for the card, it rounds when it writes.
- Cohorts are named by their start: Aug 25 for a week, Apr for a month.
You can add this component with the shadcn CLI or by hand:
Into components/cohort-retention of any React project, with no setup:
npx shadcn@latest add https://brunodelorence.com/r/cohort-retention.json- Copy the component files
Copy these files into one folder of your project, keeping their relative imports together, or download them as a ZIP:
- Import it
As shown under Usage, below.
Either way it needs React 19 and a bundler that supports CSS Modules, such as Next.js or Vite. It has a dark colour scheme: it follows your page’s color-scheme, light unless the page sets one, or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
Usage
import { CohortRetention, makeSeries } from './cohort-retention';const week = makeSeries({ period: 'week', first: '2026-08-25', count: 8, size: [1250, 1600], week1: 0.66, floor: 0.055, decay: 0.16, seed: 11,});export function RetentionTile() { return ( <CohortRetention data={{ week }} title="Retention" metric="active" onCohortPin={(start) => console.log('Cohort', start)} autoplay={false} /> );}Each state below is a live instance, locked so you can study it.
The pieces it is built from, each with its measurements read live.
Below are variations of this component, each live, with its code.
Monthly cohorts
The same product opened on M: six monthly cohorts from April, the headline at month 6, month 1 by cohort.
Poor retention
A product most people leave in week 1, on the ember palette: 6% still active at week 8, and the one cohort that did better flagged in lime.
Short history
Four weeks since launch: only weekly cohorts, so no switch, and the newest still in its first week.
Paying subscribers
Paid plans by the week they converted, with the metric set to paying: a high, slow curve and a smaller total.
A product’s signups grouped by the week (or month) they joined, read in one card. The headline is the share of the oldest cohort still active at its latest period, beside everyone active today. Below it, every cohort’s active users stack day by day, oldest at the bottom, each band a colour from violet to orange under a texture of its own: dots, fine dots, level lines or diagonals. Hover or walk the bands with the arrow keys to read a cohort’s period; hover a swatch in the legend to see one cohort alone, press it to hold it. Week 1 by cohort lines them up at their first week, the best in lime, the current one dashed while its week 1 runs. W / M reads it all again by the month. Light and dark.
- The data is a cohort matrix: each cohort’s start, its size and the share still active in each period since, the last one in progress. makeSeries grows a plausible one from a seed (a share left after period 1, an exponential fall to a floor, a lift per cohort and a little noise), so the card is the same on every load.
- readSeries turns it into a stack sampled day by day: a cohort ramps up through its signup period, then follows its shares through the middle of each period with a smoothstep, times a weekday rhythm and a seeded wobble that make the ragged top. Bands stack oldest at the bottom.
- The chart is SVG drawn in px at the box’s own width (a ResizeObserver), so the textures never stretch. Each band is filled with a pattern: a rect in the cohort’s colour under dots, fine dots, level lines or rotated stripes in a translucent dark, with a hairline top edge in the card’s colour. Colours run along eight stops, mixed for any other count.
- The pointer picks the band under it from the stack on that day, or the top band when just over it, and snaps to that cohort’s period. The ring sits mid-band at the period’s middle; the tooltip goes beside it on the side with more room, above when it fits, and a dotted leader runs from its nearest corner.
- The legend’s swatches and the week 1 bars both isolate a cohort: hovering fades the others hard and reads the headline and total for that cohort alone; pressing holds it (aria-pressed) until pressed again. A hovered band only fades the others a little.
- Week 1 bars scale between just under the lowest share and the highest, so the differences show; the best is lime on any palette and the cohort whose week 1 is still running is a dashed outline. The rows give the average and the best cohort.
- W / M is a radio group; switching reads the other matrix again and the stream redraws with a clip-path reveal. With one cadence in the data the switch is left out.
- While on screen and untouched, a demo pointer reads a cohort along its weeks and two others, switches to monthly and back, peeks at two swatches and holds one. Any real input hands it over; it comes back after 8 s of quiet.
| Prop | Type | Default | Description |
|---|---|---|---|
data | { week?: CohortSeries; month?: CohortSeries } | eight weekly and six monthly cohorts | The cohort matrices, each with its period, today’s date and its cohorts: start, size and the share retained per period, the last one in progress. With one of the two, the switch is left out. |
defaultPeriod | 'week' | 'month' | 'week' | The cadence it opens on. |
title | string | 'Retention' | The card’s title; the subtitle says the cadence. |
metric | string | 'active' | What staying means, in the headline and the total: “still paying at week 8”. |
palette | 'spectrum' | 'ember' | 'spectrum' | The bands’ colours, oldest to newest: violet to orange, or wine to amber. The best cohort is lime on both. |
onPeriodChange | (period: 'week' | 'month') => void | — | Called when W / M is switched. |
onCohortPin | (start: string | null) => void | — | Called with a cohort’s start date when it is held from the legend or the bars, and null when let go. |
defaultState | CohortRetentionState | — | Opens in a moment: a cadence, a cohort and period under the tooltip, a held or hovered cohort. It also keeps the demo off. |
autoplay | boolean | true | While on screen and untouched, a demo pointer shows the main interactions. Any real input stops it. |
colorScheme | 'light' | 'dark' | 'system' | — | Light or dark colours, or the reader’s; without it, the page’s color-scheme. |
className | string | — | Classes for the stage. |
Keyboard
- W / M is one tab stop; the arrow keys move the choice.
- The chart is one tab stop and, on focus, opens the oldest cohort at its latest period. Left and right walk periods, Home and End jump to the first and the latest, up and down move to the newer or older cohort, and Escape closes the tooltip, as does leaving the chart.
- Swatches and bars are buttons: Enter or Space holds a cohort and lets it go, and focus shows it alone as hover does.
Not by colour alone
Each band has a texture as well as a colour, the best cohort is named in its bar’s label and in the Best cohort row as well as drawn in lime, and a week 1 in progress is a dashed outline whose label says in progress (WCAG 1.4.1, Use of color).
Announcements
Switching cadence, holding or letting go of a cohort, and every reading made with the arrow keys are said in a polite live region, so they never interrupt (WCAG 4.1.3, Status messages). Pointer hovers are not announced.
Target size
The W and M segments are 34 × 28 px. The legend’s swatches are 14 × 24 px targets round an 11 × 8 drawing and sit edge to edge, narrower than the 24 px minimum; the week 1 bars hold and show the same cohorts as 34 px tall buttons, about 28 px wide with eight cohorts at the card’s full width, which meets WCAG 2.5.8 (Target size, minimum) by its equivalent-control exception. With more cohorts, or on a narrower card, the bars narrow too, and under 24 px the exception no longer holds.
Contrast and the demo
Every text colour reaches 4.5:1 on the panel and the card in both schemes, and the focus ring, the held segment’s edge and the dashed outline of a week 1 in progress reach 3:1 (WCAG 1.4.3 and 1.4.11). The demo pointer stops at the reader’s first input and doesn’t come back until the card remounts (WCAG 2.2.2); autoplay={false} turns it off, and under reduced motion it never plays.
In this build
- The chart is a focusable application with a roledescription of chart and a label that says what it draws: how many cohorts, from when to when, oldest at the bottom, and the total today. Focus opens a cohort’s period; the arrow keys walk periods (left, right, Home, End) and cohorts (up, down), Escape closes the tooltip, and each reading is said in a polite live region.
- W / M is a radiogroup of two radios moved with the arrow keys; a switch announces the new headline and total.
- The legend’s swatches and the week 1 bars are buttons with aria-pressed, named by their cohort and, for the bars, the week 1 share, “the best” or “week 1 in progress”. Focus works as hover: the cohort shows alone.
- The bands keep a texture each, so they stay apart without colour. The summary rows are a description list.
- Under reduced motion nothing fades, grows or reveals and the demo never plays. The demo pointer is decorative.
The complete source behind this demo. Open source under the MIT license, © 2026 Bruno Delorence: copy it, change it, ship it.
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useEffect, useEffectEvent, useId, useMemo, useRef, useState, type KeyboardEvent,} from 'react';import { StreamChart, spotPoint, type Spot } from './chart';import { BEST, DATA, count, percent, readSeries, type CohortData, type Palette, type Period,} from './data';// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useLayoutEffect, useRef, useState, type KeyboardEvent, type PointerEvent } from 'react';import { anchorDay, PERIOD_DAYS, type Reading, type Texture } from './data';import styles from './cohort-retention.module.css';/* * The stream of cohorts: one band per cohort stacked oldest at the bottom, each filled with its * colour under a texture of its own (an SVG pattern), drawn in px at the box's own width so the * textures never stretch. The pointer picks the band under it and snaps to that cohort's period; * the arrow keys walk the same points. The tooltip sits beside the point, a dotted leader back to * a ring on the band. *//** The chart's height in px; its width is the box's. */export const CHART_HEIGHT = 148;/** Headroom over the tallest day, so the ragged top never touches the total. */const HEADROOM = 1.18;export type Spot = { cohort: number; period: number };/** Where a cohort's period sits in the chart: its band's middle on the day it is read. *//* Cohort retention (cohort-retention.tsx): a card on a grey stage, near-black by night and white by day. A header with the chart's mark, the title and the W / M switch; an inset panel holds the headline, the stream of cohorts (chart.tsx), the legend, week 1 by cohort and two rows. Colours are the tokens below, light-dark(light, dark) where the two differ: the component takes the color-scheme it inherits from the page, or the one its colorScheme prop sets (data-color-scheme). The cohorts' own colours come from data.ts, the same on both. Text tokens reach 4.5:1 on the panel, and the focus ring, the held segment's edge and the dashed outline 3:1, in both schemes. */.root { --stage: #e9e9ec; --card: #ffffff; --card-edge: #e2e2e6; --panel: #f7f7f8; --panel-edge: #ebebee; --line: #e8e8eb; --ink: #18181b; --ink-2: #6e6e76; --ink-3: #717177; --seg: #ffffff; --seg-edge: #949498; --tip: #ffffff; --tip-edge: #e4e4e8;// Copyright (c) 2026 Bruno Delorence. MIT License./* * The cohorts the card opens with, and what it reads from them. * * A cohort is everyone who signed up in one week (or month): its size, and the share of it still * active in each period since, period 0 being the one it signed up in. The last share is the * period in progress. makeSeries grows a plausible matrix from a seed, so the card looks the same * on every load; readSeries turns one into what the card draws: a day-by-day stack of every * cohort's active users, the headline at the oldest cohort's age, week 1 by cohort, the best. */export type Period = 'week' | 'month';export type Cohort = { /** The first day of its period, YYYY-MM-DD. */ start: string; /** How many signed up. */ size: number; /** The share still active in each period since; [0] is 1, the last is in progress. */ retained: number[];};export type CohortSeries = { period: Period; now: string; cohorts: Cohort[] };// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it. The arrow and the * hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and never again once the reader has used it: `take()` hands it to them for * good, until the component remounts (WCAG 2.2.2). */export function useAutoplay<T extends HTMLElement>() { const ref = useRef<T>(null); const [visible, setVisible] = useState(false); const [reduced, setReduced] = useState(true); const [taken, setTaken] = useState(false); useEffect(() => { const element = ref.current; if (!element) return; let onScreen = false; const update = () => setVisible(onScreen && !document.hidden); const observer = new IntersectionObserver( ([entry]) => {