RetentionCurve
RetentionCurve draws cohort retention as a step line locked to 0–100%, marking the period where the curve plateaus.
- encodes
- step-line position on a locked [0,1] scale
- precision
- high — the full range is the honest frame for a share
- nodes
- ≤ 6
A cohort has run twelve weeks and the curve looks like it is flattening. RetentionCurve draws it as a step line
(cohort periods are discrete) on a scale locked to 0–100%: the full range is the frame a share is read against, and
a truncated floor would exaggerate or hide the drop. When the curve flattens, a dotted plateau marker appears. A
compare series rides behind as a subordinate dashed ghost.
Install
import { RetentionCurve } from "@microcharts/react/retention-curve";// cohort — real values under “Sample data” below<RetentionCurve data={cohort} unit="week" title="W12 cohort" />Sample data
// a weekly cohort that decays then plateaus around 38%const cohort = [1, 0.72, 0.55, 0.47, 0.42, 0.4, 0.39, 0.385, 0.382, 0.38, 0.379, 0.378];Try it
When to use it
Use it for a cohort retention curve in a KPI card, your decay against an industry benchmark, and spotting whether retention plateaus or keeps leaking. For a continuous signal use Sparkline; for one-number retention use Progress or Delta.
Sizing
Variants
The compare series stays a dashed ghost behind your curve rather than a second competing line. curve="smooth"
interpolates between periods, which implies values that were never measured; the step default doesn't. The plateau
marker appears only when the mean period-over-period change across the tail falls below half a point, never as
decoration.
Edge cases
A single period is too short for plateau detection (the window needs at least four finite points) and renders as a
single step with no visible line. data accepts either a 0–1 fraction or a 0–100 percent series, whichever the max
value implies, so a raw percent export renders identically to its fraction form without a manual divide. With a
locale, the percent label and every announced number follow that locale's own formatting.
Four homes
Accessibility
The accessible name states the final retention and, when one is detected, the plateau: "38% retained after 10 weeks; curve plateaus from week 6." The interactive entry steps the periods and announces each period's retention alongside the benchmark's.
The interactive entry follows the shared interaction contract:
arrow keys rove between units on both axes, Home and End jump to the ends, and a click, tap, Enter or
Space selects a unit — pinning its readout so it survives blur, until you select it again or press Escape.
On touch, a tap pins and a drag scrubs.
Props
| Prop | Type | Notes |
|---|---|---|
| data* | number[] | Fraction retained per period (0–1 or 0–100); period 0 is typically 1.0. |
| compare | number[] | Peer/industry curve, drawn as a subordinate dashed ghost. The catalog word for a second series to read the first against (DualSparkline, StarSpoke). |
| benchmark | number[] | Deprecated alias for `compare`, still accepted and still winning when both are passed. |
| plateau | boolean | Detect + mark a plateau (default true). |
| curve | "step" | "smooth" | Step (default — cohorts are discrete) or smooth (editorial). |
| unit | string | Period noun for the summary (default 'period'). |
| label | "last" | "none" | Final retention in a right gutter. |
| animate | boolean | interactiveOpt-in entrance motion when the chart mounts client-side — add import "@microcharts/react/motion" once. Inert on the server, on hydrated server HTML, and under prefers-reduced-motion. |
Plus the shared grammar — data, domain, color, title, summary, format — and the layout props (width, height, className, style) that every chart accepts. Interactive entries also share animate and live, and — wherever a chart has more than one navigable unit — onActive, onSelect, selectedIndex and defaultSelectedIndex; and — wherever the chart shows a hover value — readout. See the shared grammar.