Trend · Intermediate

Cohort chart

Retention by signup cohort: one row per cohort, one column per period since it started.

Open in playground
Use when
Following groups that started together, such as users by signup month, to see how many are still active 1, 2, 3 ... periods later
Avoid when
Comparing the exact shape of two cohorts' curves (use a line chart)

Try it

46

Cohort chart

Share of each monthly signup cohort still active, by months since signup
Cohort chartCohort chart. 8 cohorts × 8 periods. Average retention: 1 60%, 2 48%, 3 41%, 4 38%, 5 35%, 6 33%.100%60%48%41%38%35%33%31%100%57%45%40%36%34%33%31%100%58%47%40%37%36%33%100%60%47%40%39%36%100%60%47%43%39%100%60%50%43%100%63%50%100%63%100%
Cohort chart data
Average · 0100%, 12,217 of 12,217
Average · 160%, 6,279 of 10,407
Average · 248%, 4,150 of 8,674
Average · 341%, 2,928 of 7,084
Average · 438%, 2,055 of 5,437
Average · 535%, 1,393 of 3,935
Average · 633%, 866 of 2,625
Average · 731%, 384 of 1,240
2026-01 · 0100%, 1,240 of 1,240
2026-01 · 157%, 707 of 1,240
2026-01 · 245%, 558 of 1,240
2026-01 · 340%, 496 of 1,240
2026-01 · 436%, 446 of 1,240
2026-01 · 534%, 422 of 1,240
2026-01 · 633%, 409 of 1,240
2026-01 · 731%, 384 of 1,240
2026-02 · 0100%, 1,385 of 1,385
2026-02 · 158%, 803 of 1,385
2026-02 · 247%, 651 of 1,385
2026-02 · 340%, 554 of 1,385
2026-02 · 437%, 512 of 1,385
2026-02 · 536%, 499 of 1,385
2026-02 · 633%, 457 of 1,385
2026-03 · 0100%, 1,310 of 1,310
2026-03 · 160%, 786 of 1,310
2026-03 · 247%, 616 of 1,310
2026-03 · 340%, 524 of 1,310
2026-03 · 439%, 511 of 1,310
2026-03 · 536%, 472 of 1,310
2026-04 · 0100%, 1,502 of 1,502
2026-04 · 160%, 901 of 1,502
2026-04 · 247%, 706 of 1,502
2026-04 · 343%, 646 of 1,502
2026-04 · 439%, 586 of 1,502
2026-05 · 0100%, 1,647 of 1,647
2026-05 · 160%, 988 of 1,647
2026-05 · 250%, 824 of 1,647
2026-05 · 343%, 708 of 1,647
2026-06 · 0100%, 1,590 of 1,590
2026-06 · 163%, 1,002 of 1,590
2026-06 · 250%, 795 of 1,590
2026-07 · 0100%, 1,733 of 1,733
2026-07 · 163%, 1,092 of 1,733
2026-08 · 0100%, 1,810 of 1,810
A third are still active six months inIntermediate

Hover over the chart, or Tab in and use the arrow keys to move between items. The numbers are sample data.

Variants

Named looks for this chart. Each one is the example above with a few options or fields changed. The CLI (ztd-charts example cohort --variant <id>) and the MCP server know the same names.

People in cells

Share of each monthly signup cohort still active, by months since signup
Sample data

Without the average row

Share of each monthly signup cohort still active, by months since signup
Sample data

Without values

Share of each monthly signup cohort still active, by months since signup
Sample data

Code

CohortChart.tsx
import { ChartCard, CohortChart } from "ztd-charts";

const data = [
  {"cohort":"2026-01","month":0,"active":1240,"size":1240},
  {"cohort":"2026-01","month":1,"active":707,"size":1240},
  {"cohort":"2026-01","month":2,"active":558,"size":1240},
  {"cohort":"2026-01","month":3,"active":496,"size":1240},
  {"cohort":"2026-01","month":4,"active":446,"size":1240},
  {"cohort":"2026-01","month":5,"active":422,"size":1240},
  // … 30 more rows
];

export function Example() {
  return (
    <ChartCard number="46" title="Cohort chart" subtitle="Share of each monthly signup cohort still active, by months since signup" takeaway="A third are still active six months in" level="intermediate" replay>
      <CohortChart
        data={data}
        cohort="cohort"
        period="month"
        value="active"
        size="size"
      />
    </ChartCard>
  );
}

Props

<CohortChart> takes these props. Rows marked Common work the same on every chart.

33 props

Prop
dataRequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]
cohortRequiredCohort: a name or a start date. Cohorts go in date order when all read as dates, otherwise in order of first appearancestring | (d, i) => any
periodRequiredPeriods since the cohort started: 0, 1, 2 ... In number order when all are numbersstring | (d, i) => any
valueRequiredPeople still active, or the share still active (see options.valueType)string | (d, i) => number
sizeCohort size. The first value of each cohort countsstring | (d, i) => number
valueType"count" (people still active), "percent" (58) or "ratio" (0.58). "auto" reads counts when there is a size field, ratios when every value is at most 1, percents when every value is at most 100, otherwise counts with each cohort's first period as its size"auto" | "count" | "percent" | "ratio"Default "auto"
show"rate" writes the share in each cell, "count" the people still active (only when counts are known). Colors always follow the share"rate" | "count"Default "rate"
averageAverage row on top: the people still active over the cohort sizes, counting only the cohorts that reached each period (the plain mean of the shares without counts)booleanDefault true
colorStepsNumber of color steps. The legend shows each stepnumberDefault 5
showValuesValues in cells. "auto" shows them when they fitanyDefault "auto"
legendShow the color legendbooleanDefault true
legendLabelsNames at both ends of the legendstring[]
heightCommonHeight in px. Without it, each chart picks a default that fits its widthnumber
widthCommonFixed width in px. Without it, the chart fits its parentnumber
highlightCommonItem to highlight. An index, a name, an array, or "max" | "min" | "first" | "last" | "none"number | string | (number|string)[] | "max" …
formatCommonValue format. "number" | "integer" | "percent" (values are already percents: 42 → "42%") | "ratio" (0.42 → "42%") | "compact" | "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) | "decimal" or Intl.NumberFormat options"number" | "percent" | "compact" | …
unitCommonUnit appended to values. For example "%" or "ms"string
localeCommonLocale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider localestringDefault "en-US"
animateCommonEntry and update animationbooleanDefault true
durationCommonAnimation length (ms)number
easingCommonMotion curve"spring" | "easeOut" | "easeInOut" | "linear"Default "spring"
staggerCommonDelay between items as they enter (ms)number
reducedMotionCommon"auto" follows the OS setting. true always turns motion offanyDefault "auto"
animateOnViewCommonPlay when the chart scrolls into viewbooleanDefault true
showLabelsCommonLabels drawn on the chart (values and names)booleanDefault true
tooltipCommonShow tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left outtooltipDefault true
syncIdCommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick, skyline). <ChartGrid sync> sets one for every chart inside itstring
ariaLabelCommonName for screen readersstring
descriptionCommonDescription for screen readers. Built from the data when omittedstring
onHoverCommonRuns when hover or keyboard focus moves to another item(e: ChartEvent | null) => void
onClickCommonRuns on click, Enter or Space(e: ChartEvent) => void
replayKeyCommonReplays the entry animation when it changesstring | number
themeCommonChanges theme tokens for this chart onlyPartial<ChartTheme>