Gitmap

a react component for visualizing github contributions as a heatmap

@

Installation

npx shadcn@latest add https://gitmap.sachi.dev/r/gitmap.json

Usage

Import the component and provide the required props: contributions data, date range, and colors.

example.tsx
import { Gitmap } from "@/components/gitmap"


const contributions = [
  { date: "2024-01-01", count: 5, level: 2 },
  { date: "2024-01-02", count: 12, level: 4 },
]


const colors = {
  empty: "#161b22",
  level1: "#0e4429",
  level2: "#006d32",
  level3: "#26a641",
  level4: "#39d353",
}


export function MyGitmap() {
  return (
    <Gitmap
      contributions={contributions}
      from={new Date("2024-01-01")}
      to={new Date("2024-12-31")}
      colors={colors}
    />
  )
}

Theming with CSS Variables

For seamless light/dark mode support, define your gitmap colors as CSS custom properties.

globals.css
:root {
  --gitmap-empty: #ebedf0;
  --gitmap-level-1: #9be9a8;
  --gitmap-level-2: #40c463;
  --gitmap-level-3: #30a14e;
  --gitmap-level-4: #216e39;
}


.dark {
  --gitmap-empty: #161b22;
  --gitmap-level-1: #0e4429;
  --gitmap-level-2: #006d32;
  --gitmap-level-3: #26a641;
  --gitmap-level-4: #39d353;
}
gitmap.tsx
const colors = {
  empty: "var(--gitmap-empty)",
  level1: "var(--gitmap-level-1)",
  level2: "var(--gitmap-level-2)",
  level3: "var(--gitmap-level-3)",
  level4: "var(--gitmap-level-4)",
}


<Gitmap
  contributions={contributions}
  from={startDate}
  to={endDate}
  colors={colors}
/>

Static Themes

Alternatively, define static color themes as JavaScript objects:

themes.ts
const themes = {
  github: {
    empty: "#161b22",
    level1: "#0e4429",
    level2: "#006d32",
    level3: "#26a641",
    level4: "#39d353",
  },
  ocean: {
    empty: "#1a1b26",
    level1: "#1e3a5f",
    level2: "#2563eb",
    level3: "#3b82f6",
    level4: "#60a5fa",
  },
}

API Reference

Gitmap Props

PropTypeDefaultDescription
contributions*ContributionDay[]-Array of contribution data with date, count, and level
from*Date-Start date for the gitmap range
to*Date-End date for the gitmap range
colors*GitmapColors-Color configuration object for the gitmap levels
cellSizenumber10Size of each cell in pixels
cellGapnumber3Gap between cells in pixels
showMonthsbooleantrueShow month labels above the grid
showDaysbooleantrueShow day labels on the left side
showCountsbooleanfalseDisplay contribution count inside cells
classNamestring-Additional CSS classes for the container

ContributionDay

Each contribution day object should have the following shape:

PropTypeDefaultDescription
date*string-Date in YYYY-MM-DD format
count*number-Number of contributions on this day
level*0 | 1 | 2 | 3 | 4-Intensity level for coloring (0 = no contributions)

GitmapColors

Color configuration for the five intensity levels:

PropTypeDefaultDescription
empty*string-Color for days with no contributions
level1*string-Color for low activity
level2*string-Color for medium-low activity
level3*string-Color for medium-high activity
level4*string-Color for high activity

Customization

Customize the appearance with cell size, gap, and visibility options.

customization.tsx
<Gitmap
  contributions={contributions}
  from={startDate}
  to={endDate}
  colors={colors}
  cellSize={12}
  cellGap={4}
  showMonths={true}
  showDays={true}
  showCounts={true}
  className="my-custom-class"
/>