Gitmap

A React component for visualizing GitHub contributions as a heatmap.

Features

• GitHub-style contribution heatmap visualization
• Customizable color themes
• Configurable date ranges
• Optional month and day labels
• Show contribution counts on cells
• Tooltip with contribution details on hover

Installation

npx shadcn@latest add https://gitmap.rudro.dev/r/gitmap.json
# or
bunx --bun shadcn@latest add https://gitmap.rudro.dev/r/gitmap.json
# or
pnpm dlx shadcn@latest add https://gitmap.rudro.dev/r/gitmap.json
# or
yarn shadcn@latest add https://gitmap.rudro.dev/r/gitmap.json

Getting Started

Run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

.env.local

NEXT_PUBLIC_APP_URL=http://localhost:3000

Open http://localhost:3000 to see the demo.

Usage

import { Gitmap } from "@/components/gitmap"

<Gitmap
  contributions={contributions}
  from={new Date("2024-01-01")}
  to={new Date("2024-12-31")}
  colors={{
    empty: "#ebedf0",
    level1: "#9be9a8",
    level2: "#40c463",
    level3: "#30a14e",
    level4: "#216e39",
  }}
  showMonths={true}
  showDays={true}
  showCounts={false}
/>

Props

Prop	Type	Default	Description
contributions	ContributionDay[]	required	Array of contribution data
from	Date	required	Start date of the range
to	Date	required	End date of the range
colors	GitmapColors	required	Color theme for the heatmap
cellSize	number	10	Size of each cell in pixels
cellGap	number	3	Gap between cells in pixels
showMonths	boolean	true	Show month labels
showDays	boolean	true	Show day labels (Mon, Wed, Fri)
showCounts	boolean	false	Show contribution count inside cells
className	string	-	Additional CSS classes

Types

interface ContributionDay {
  date: string      // Format: "yyyy-MM-dd"
  count: number     // Number of contributions
  level: 0 | 1 | 2 | 3 | 4  // Intensity level
}

interface GitmapColors {
  empty: string   // Color for 0 contributions
  level1: string  // Color for level 1
  level2: string  // Color for level 2
  level3: string  // Color for level 3
  level4: string  // Color for level 4
}

License

MIT License - see LICENSE for details.