Trend · Intermediate
Cohort chart
Retention by signup cohort: one row per cohort, one column per period since it started.
- 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
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
Without the average row
Share of each monthly signup cohort still active, by months since signup
Without values
Share of each monthly signup cohort still active, by months since signup
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> |
Also in Trend
- Line chartChange over time
- Area chartRunning totals and a changing mix (stacked, 100% stacked)
- StreamgraphMany series as flowing bands that show size and change
- SparklineA small trend line next to a table cell or KPI
- Calendar heatmapDaily amounts on a weekly grid
- Bump chartRank changes over time
- Candlestick chartOpen, high, low and close for each period in one candle
- SkylineStacked volume per period as blocks, with a smaller outcome in the same unit standing in front
- TimelineWhen things started and ended, and what overlapped: one bar per item on a time axis
- Horizon chartMany time series in thin rows, each value folded into a few colored bands