# Contribution graph

> A year of activity as a grid of days with tooltips and keyboard exploring.

Component · Pro · https://lodeui.com/components/contribution-graph

## When to use

- Activity over a year: commits, workouts, streaks, usage.

## When not to use

- Short ranges: use a bar chart.

## Installation

```bash
npx shadcn@latest add @lode/contribution-graph
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion

## Usage

```tsx title="example.tsx"
import { ContributionGraph } from "@/components/ui/contribution-graph";

<ContributionGraph data={days} unit="commits" />  // days: { date: "2026-03-04", count: 7 }[]
```

## API reference

### ContributionGraph

Weeks as columns and days as rows, shaded by count, with a live caption.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data | `{ date: string; count: number }[]` | – | One entry per day (YYYY-MM-DD), oldest first; missing days count as 0. |
| thresholds | `[number, number, number, number]` | `[1, 4, 8, 12]` | Counts where the shade steps up. |
| color | `string` | `"#22c55e"` | Base color; shades are mixed toward var(--muted). |
| unit | `string` | `"contributions"` | Word used in labels. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Enter the grid |
| ← / → | Previous or next week |
| ↑ / ↓ | Previous or next day |

## Accessibility

- A grid of cells, each labelled like "7 commits on Mar 4, 2026".
- The caption reads the focused or hovered day politely.
- Shades are backed by numbers, never color alone.

## Motion

- Cells pop in column by column; hovered cells grow; the caption swaps with a short slide.

## Responsive behavior

- Scrolls horizontally on narrow screens.

## Performance

- Weeks are computed once per data change; dates use UTC so time zones never shift days.

## Notes for AI

- Pass dates as YYYY-MM-DD strings.

## Related

- [Heatmap](https://lodeui.com/components/heatmap) — A color-scaled grid with row and column tracking, for cohorts and schedules.
- [Bar chart](https://lodeui.com/components/bar-chart) — Bars that grow in and morph between datasets, with a hover readout.
- [Sparkline](https://lodeui.com/components/sparkline) — A tiny trend line that draws itself in.