@rsalianto/git-heatmap-react

React component for displaying GitHub/GitLab contribution heatmaps.

Part of the @rsalianto/git-heatmap family — available for React, Vue, Angular, Vanilla JS, and Next.js.

Installation

npm install @rsalianto/git-heatmap-react

@rsalianto/git-heatmap-core is not required separately — buildHeatmapData, buildHeatmapDataForYear, and normalizeManual are re-exported directly from this package.

Usage

Fetch from an API endpoint

import { GitHeatmap } from "@rsalianto/git-heatmap-react";

export default function Page() {
  return <GitHeatmap apiUrl="/api/contributions" />;
}

The endpoint must return a HeatmapData JSON object.

Pass data directly

import { GitHeatmap, buildHeatmapData } from "@rsalianto/git-heatmap-react";

const data = buildHeatmapData([
  { date: "2025-06-01", count: 4 },
  { date: "2025-06-02", count: 0 },
]);

export default function Page() {
  return <GitHeatmap data={data} />;
}

Display a specific year

import { GitHeatmap, buildHeatmapDataForYear } from "@rsalianto/git-heatmap-react";

const data = buildHeatmapDataForYear(allEntries, 2024);

export default function Page() {
  return <GitHeatmap data={data} />;
}

Custom fetch function

<GitHeatmap fetchData={() => fetch("/api/contributions").then(r => r.json())} />

Pre-fetched data (Server Components / SSR)

import { fetchGitHubContributions } from "@rsalianto/git-heatmap-core/fetchers/github";
import { GitHeatmap } from "@rsalianto/git-heatmap-react";

export default async function Page() {
  const data = await fetchGitHubContributions({
    username: "your-username",
    token: process.env.GITHUB_TOKEN!,
  });
  return <GitHeatmap data={data} />;
}

Props

| Prop | Type | Default | Description | |---|---|---|---| | data | HeatmapData | — | Pre-fetched data — skips internal fetching | | apiUrl | string | — | Endpoint returning HeatmapData JSON | | fetchData | () => Promise<HeatmapData> | — | Custom async data resolver | | levels | LevelConfig[] | DEFAULT_LEVELS | Color thresholds (5 levels) | | cellSize | number | 10 | Cell width/height in px | | cellGap | number | 3 | Gap between cells in px | | cellRadius | number | 2 | Cell border radius in px | | showTotal | boolean | true | Show "N contributions in the last year" | | showLegend | boolean | true | Show Less / More legend | | showMonthLabels | boolean | true | Show month labels above the grid | | showDayLabels | boolean | true | Show Mon / Wed / Fri labels | | theme | Partial<HeatmapTheme> | — | Override CSS variable defaults via props | | onDayClick | (day: HeatmapDay) => void | — | Called when a cell is clicked | | label | string | "Contribution heatmap" | aria-label for the grid |

HeatmapData shape

This is the format your apiUrl endpoint must return:

{
  "totalContributions": 312,
  "source": "github",
  "weeks": [
    {
      "days": [
        { "date": "2025-01-05", "count": 0,  "level": 0 },
        { "date": "2025-01-06", "count": 3,  "level": 1 },
        { "date": "2025-01-07", "count": 8,  "level": 2 },
        { "date": "2025-01-08", "count": 14, "level": 3 },
        { "date": "2025-01-09", "count": 22, "level": 4 },
        { "date": "2025-01-10", "count": 1,  "level": 1 },
        { "date": "2025-01-11", "count": 0,  "level": 0 }
      ]
    }
  ]
}

Theming

Via theme prop

<GitHeatmap
  apiUrl="/api/contributions"
  theme={{
    colorL0: "#161b22",
    colorL1: "#0e4429",
    colorL2: "#006d32",
    colorL3: "#26a641",
    colorL4: "#39d353",
    textColor: "rgba(255,255,255,0.5)",
    tooltipBg: "#1c2128",
    tooltipBorderColor: "rgba(255,255,255,0.1)",
    tooltipTextColor: "rgba(255,255,255,0.8)",
    selectedBorderColor: "rgba(255,255,255,0.6)",
  }}
/>

Via CSS variables

All CSS variables can be set on the component or any ancestor:

/* Dark (default) */
.heatmap-wrapper {
  --ghm-color-l0: rgba(255,255,255,0.08);
  --ghm-color-l1: #1c3d06;
  --ghm-color-l2: #3a7510;
  --ghm-color-l3: #6ab81e;
  --ghm-color-l4: #aafd35;
  --ghm-text: rgba(255,255,255,0.5);
  --ghm-tooltip-bg: #1c2128;
  --ghm-tooltip-border: rgba(255,255,255,0.1);
  --ghm-tooltip-text: rgba(255,255,255,0.75);
  --ghm-font: inherit;
  --ghm-fs: 11px;
  --ghm-selected: rgba(255,255,255,0.7);
  --ghm-skeleton-opacity: 0.4;
}

/* Light theme */
.heatmap-wrapper {
  --ghm-color-l0: #ebedf0;
  --ghm-color-l1: #9be9a8;
  --ghm-color-l2: #40c463;
  --ghm-color-l3: #30a14e;
  --ghm-color-l4: #216e39;
  --ghm-text: rgba(0,0,0,0.5);
  --ghm-tooltip-bg: #fff;
  --ghm-tooltip-border: #d0d7de;
  --ghm-tooltip-text: #24292f;
  --ghm-selected: rgba(0,0,0,0.4);
}

useHeatmapData hook

Lower-level hook if you want to manage rendering yourself:

import { useHeatmapData } from "@rsalianto/git-heatmap-react";

const { data, status, error } = useHeatmapData({ apiUrl: "/api/contributions" });
// status: "idle" | "loading" | "success" | "error"

Related packages

• @rsalianto/git-heatmap-next — Next.js App Router route handlers
• @rsalianto/git-heatmap-core — Core utilities and fetchers