@rsalianto/git-heatmap-vue

@rsalianto/git-heatmap-vue

Vue 3 component and composable 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-vue

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

---

Usage

Register globally (plugin)

// main.ts
import { createApp } from "vue";
import { GitHeatmapPlugin } from "@rsalianto/git-heatmap-vue";
import App from "./App.vue";

createApp(App).use(GitHeatmapPlugin).mount("#app");

<template>
  <GitHeatmap api-url="/api/contributions" @day-click="onDayClick" />
</template>

Import locally

<script setup lang="ts">
import { GitHeatmap } from "@rsalianto/git-heatmap-vue";

function onDayClick(day: { date: string; count: number }) {
  console.log(day);
}
</script>

<template>
  <GitHeatmap api-url="/api/contributions" @day-click="onDayClick" />
</template>

Pass data directly

<script setup lang="ts">
import { GitHeatmap, buildHeatmapData } from "@rsalianto/git-heatmap-vue";

const data = buildHeatmapData([
  { date: "2025-06-01", count: 4 },
  { date: "2025-06-15", count: 9 },
]);
</script>

<template>
  <GitHeatmap :data="data" />
</template>

Display a specific year

<script setup lang="ts">
import { GitHeatmap, buildHeatmapDataForYear } from "@rsalianto/git-heatmap-vue";

const data = buildHeatmapDataForYear(allEntries, 2024);
</script>

<template>
  <GitHeatmap :data="data" />
</template>

Server-side data (Nuxt)

// server/api/contributions.get.ts
import { fetchGitHubContributions } from "@rsalianto/git-heatmap-core/fetchers/github";

export default defineEventHandler(async () => {
  return fetchGitHubContributions({
    username: "your-username",
    token: process.env.GITHUB_TOKEN!,
  });
});

<script setup>
const { data } = await useFetch("/api/contributions");
</script>
<template>
  <GitHeatmap :data="data" />
</template>

---

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
label	string	"Contribution heatmap"	aria-label for the grid

Events

Event	Payload	Description
day-click	HeatmapDay	Emitted when a cell is clicked

---

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
  api-url="/api/contributions"
  :theme="{
    colorL0: '#161b22',
    colorL1: '#0e4429',
    colorL2: '#006d32',
    colorL3: '#26a641',
    colorL4: '#39d353',
    textColor: 'rgba(255,255,255,0.5)',
    tooltipBg: '#1c2128',
  }"
/>

Via CSS variables

/* 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 composable

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

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

---

Related packages

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