# GitHub Activity

> A React GitHub contribution graph: a yearly heatmap with a panel of your top repositories.

- Type: React chart component (Charts & Stats)
- Access: Free (the source is open to everyone)
- Version: 1.0.1
- Install: `npx wingo-ui@latest add github-activity`
- Docs: https://wingo-ui.com/components/github-activity

## Interaction

The grid sweeps in column by column, then the month labels blur into focus. Hover any cell, or press one on a touchscreen, for its count and date. Click the chevron to expand the top repositories over the grid, their avatars flying out of the stack into rows, and again to fold them back. The grid shows as many recent weeks as fit its width, so it never scrolls sideways on a phone.

## Installation

```bash
npx wingo-ui@latest add github-activity
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/github-activity.json`

Files:

- `components/ui/github-activity.tsx`

npm dependencies: `npm i motion`

Wingo UI dependencies (installed automatically):

- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import GitHubActivity from "@/components/ui/github-activity"

export function Demo() {
  return <GitHubActivity username="octocat" />
}

// or pass everything yourself:
// <GitHubActivity
//   contributions={contributions}
//   repos={[{ name: "Zero mail", count: 412, logo: <ZeroIcon /> }]}
//   accent={["#0e4429", "#006d32", "#26a641", "#39d353"]}
// />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `username?` | `string` | `""` | A GitHub username to load the last year of contributions and the most-pushed repositories for, from public APIs. Ignored for whichever of contributions or repos you pass yourself. An unknown or invalid name shows a not found heading and calls onError. |
| `contributions?` | `Contribution[]` | `"[]"` | Your own contribution data, one { date, count, level } per day in date order, starting on a Sunday. Level 0 to 4 picks the shade. |
| `repos?` | `RepoContribution[]` | `"[]"` | The repositories listed in the footer, highest first: { name, count, logo?, href? }. The first avatarCount (3) stack as avatars; a missing logo shows the initial. |
| `year?` | `number` | `0` | Overrides the year in the heading. 0 uses the year of the latest contribution (2025 in this sample). |
| `accent?` | `string \| string[]` | `"#39d353"` | The color of the contribution squares. One color is faded per level; an array of four shades (or five, with the empty color first) sets each level exactly. |
| `cellSize?` | `number` | `11` | Size of each day square in pixels. The gap scales with it. |
| `cellRadius?` | `number` | `3` | Corner radius of each day square in pixels. |
| `background?` | `string` | `""` | Any CSS color for the card. Empty is white in light mode and black in dark mode. The heading and the panel keep the theme colors, so pick a background that suits the theme. |
| `radius?` | `number` | `28` | Corner radius of the card in pixels; the repository panel inside follows it minus 10px. |
| `chevronColor?` | `string` | `""` | Any CSS color for the round chevron that opens the panel. Empty uses #C4C9CC light, #3E4346 dark. It keeps a 44px hit area on touch screens. |
| `avatarCount?` | `number` | `3` | How many repository avatars stack in the closed footer (and, with username, how many repositories are fetched). |
| `months?` | `number` | `12` | How many months of history to show, at most. The grid also drops older weeks that do not fit its width. |
| `showMonths?` | `boolean` | `false` | Adds a row of month names above the grid. |
| `label?` | `string` | `"Top contributions in:"` | Text shown in the footer next to the avatars. |
| `locale?` | `string` | `""` | Intl locale for the month names, the tooltip date and the heading count. Falls back to UIProvider's locale, then en-US. |
| `headingLabel?` | `string` | `"{count} contributions"` | Heading template; {count} fills in the total. |
| `yearLabel?` | `string` | `"in {year}"` | Appended to the heading when there is a year; {year} fills in. |
| `notFoundLabel?` | `string` | `"No public activity found for {login}"` | Heading when username has no public calendar; {login} fills in. |
| `dayLabel?` | `string` | `"{count} contributions on {date}"` | Tooltip template for a day; {count} and {date} fill in. |
| `dayLabelOne?` | `string` | `"{count} contribution on {date}"` | Tooltip template for a day with exactly one contribution. |
| `showReposLabel?` | `string` | `"Show top repositories"` | Accessible name of the chevron while the panel is closed. |
| `hideReposLabel?` | `string` | `"Hide top repositories"` | Accessible name of the chevron while the panel is open. |
| `defaultOpen?` | `boolean` | `false` | Starts with the repository panel open. Ignored when open is set. |
| `open?` | `boolean` |  | Panel state for controlled usage. When set, the component stops managing its own state. |
| `onOpenChange?` | `(open: boolean) => void` |  | Called with the next state when the chevron is clicked. |
| `onError?` | `(username: string) => void` |  | Called when username is not a valid GitHub login or its calendar cannot be loaded, for example to fall back to data you pass yourself. |
| `className?` | `string` |  | Extra classes for the card that wraps the grid. Its width fits the visible weeks (at least 320px) and is capped at the parent width; pass max-w-* to show fewer weeks. |

## Parts

### Contribution (type)

One day of contributions: { date: "YYYY-MM-DD", count, level: 0 | 1 | 2 | 3 | 4 }. Pass them oldest first, starting on a Sunday.

### RepoContribution (type)

One repository in the footer: { name, count, logo?, href? }.

### ContributionLevel (type)

The five intensity steps of a day, 0 (none) to 4 (most).

## Examples

- **Your own color scale**: An array of four shades sets each level exactly; showMonths adds the month row.
- **Last six months, round cells**: months 6 with larger cells and a radius of half the cell, in orange.
- **Repositories open**: defaultOpen starts with the top repositories expanded over the grid; the chevron folds them back.

## See also

- [Heatmap calendar](https://wingo-ui.com/components/heatmap-calendar) ([Markdown](https://wingo-ui.com/components/heatmap-calendar.md))
- [Sparkline](https://wingo-ui.com/components/sparkline) ([Markdown](https://wingo-ui.com/components/sparkline.md))
- [Stat Card](https://wingo-ui.com/components/stat-card) ([Markdown](https://wingo-ui.com/components/stat-card.md))
- [Bar chart](https://wingo-ui.com/components/bar-chart) ([Markdown](https://wingo-ui.com/components/bar-chart.md))
- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))

---

Canonical: https://wingo-ui.com/components/github-activity
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt