# Application Report: Cohort Retention Grid

A retention heatmap with weekly signup cohorts as rows, weeks since signup as columns, shaded cells, a shade legend, and a methodology note.

- Page: https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/cohort-retention-grid
- Collection: [Application](https://www.shadcn-ui-blocks.com/blocks/application-pro), Standard tier
- Group: [Reports](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports)
- Created: 2026-07-04
- Preview image: https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/cohort-retention-grid.png

## Install

```bash
npx shadcn@latest add @shadcn-ui-blocks/application-pro-reports-cohort-retention-grid
```

Needs an API key from a Pro or Team plan: add `@shadcn-ui-blocks` to the registries in components.json with the key as an `Authorization: Bearer` header. Setup: https://www.shadcn-ui-blocks.com/docs/shadcn-cli. The MCP server installs it without the setup: https://www.shadcn-ui-blocks.com/docs/mcp.

## Depends on

- npm packages: class-variance-authority, lucide-react, radix-ui
- shadcn/ui components: button
- Installs to: `@/components/blocks/application-pro/reports/cohort-retention-grid`

## About this block

Cohort Retention Grid lays out eight weekly signup
cohorts as rows, from Apr 20 at 412 users down to the
freshest Jun 8 cohort at 418, with weeks since signup as
columns from Week 0 through Week 7. Each cell is shaded by
the share of the cohort still active that week, so a
strong week reads dark and a thin one reads faint. Newer
cohorts trail off into a staircase of muted pending cells,
and two dropdown chips (Weekly cohorts, Active users) sit
above the grid.

Cohorts are one typed array and cellClass maps each value
to a foreground opacity band, so the heatmap needs no
chart library. A shade legend runs across the footer next
to the methodology note that a user counts as active with
one or more sessions in the week, which is the definition
every retention debate eventually turns on.

## When to use

Reach for this block on a retention or growth dashboard,
wired to your cohort query and active-user definition. The
two dropdown chips should switch the cohort grain and the
retention event without leaving the page.

A natural flow around it on an Application Pro page:

**Before**

- [App shell](https://www.shadcn-ui-blocks.com/blocks/application-pro/app-shells)
- [Report filters bar](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports)

**After**

- [Charts](https://www.shadcn-ui-blocks.com/blocks/application-pro/charts)
- [Data table](https://www.shadcn-ui-blocks.com/blocks/application-pro/data-tables)

## What you can display

One strong use is signup cohort retention. Other grids of
the same shape:

- **Feature retention.** Cohorts by first use of a
  feature, cells shaded by weekly return to that feature.
- **Revenue retention.** Dollar retention by billing
  cohort, cells shaded by share of starting MRR kept.
- **Channel cohorts.** Rows split by acquisition source so
  paid and organic curves sit side by side.

> Tip: the active definition in the footer note settles
> more arguments than any single cell, so keep it visible.

## More in Application Reports

- [Dashboard Grid Layout](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/dashboard-grid-layout)
- [Export Options Card](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/export-options-card)
- [Metric Detail Drilldown](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/metric-detail-drilldown)
- [Report Annotations Panel](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/report-annotations-panel)
- [Report Builder](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/report-builder)
- [Report Comparison View](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/report-comparison-view)
- [Report Filters Bar](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/report-filters-bar)
- [Report Run History](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/report-run-history)
- [Report Summary Header](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/report-summary-header)
- [Saved Reports List](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/saved-reports-list)
- [Scheduled Report Form](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/scheduled-report-form)
- [Scheduled Reports Table](https://www.shadcn-ui-blocks.com/blocks/application-pro/reports/scheduled-reports-table)
