A lightweight, dependency-free Web Component that displays a GitHub contributions calendar (heatmap) for any user. Built with pure Vanilla JS, HTML5, and CSS3.
- No Dependencies: Pure Vanilla JS Web Component (
<github-calendar>). - Semantic HTML: Built with accessible and clean HTML5 elements.
- Mobile-First & Responsive: Includes smooth touch horizontal scrolling for perfect display on phones.
- Easy Customization: Uses CSS Custom Properties for painless color themes (Purple, Blue, Dark Mode, etc.).
- Vite Powered: Blazing fast modern ESM tooling.
npm install vanilla-js-github-calendarYou can use this library in several ways depending on your setup. In all cases, simply add the custom element with your username anywhere in your HTML:
<github-calendar username="moonhuntercode"></github-calendar>The fastest way to use the library in plain HTML without installing anything locally:
<head>
<!-- Include the external stylesheet -->
<link rel="stylesheet" href="https://unpkg.com/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.css">
</head>
<body>
<!-- Include the script directly from CDN -->
<script type="module" src="https://unpkg.com/vanilla-js-github-calendar"></script>
<github-calendar username="moonhuntercode"></github-calendar>
</body>If you are using a modern frontend framework or a bundler, you split the usage between your HTML and your JavaScript entry point.
1. In your JavaScript file (e.g., main.js):
// Import the component (automatically registers the <github-calendar> tag)
import 'vanilla-js-github-calendar';
// Import the CSS (if your bundler supports CSS imports)
import 'vanilla-js-github-calendar/styles.css';2. In your HTML file (e.g., index.html):
<body>
<!-- Link your JavaScript file -->
<script type="module" src="/main.js"></script>
<!-- Add the component anywhere -->
<github-calendar username="moonhuntercode"></github-calendar>
</body>If you installed the package via npm but want to use it in plain HTML without a bundler, you can use Import Maps to keep paths clean:
<head>
<!-- 1. Include the external stylesheet -->
<link rel="stylesheet" href="./node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.css">
<!-- 2. Define the import map -->
<script type="importmap">
{
"imports": {
"vanilla-js-github-calendar": "./node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.js"
}
}
</script>
</head>
<body>
<!-- 3. Import gracefully! -->
<script type="module">
import 'vanilla-js-github-calendar';
</script>
<!-- 4. Add the component -->
<github-calendar username="moonhuntercode"></github-calendar>
</body>If you prefer the classic method without import maps after running npm install:
<head>
<!-- 1. Include the external stylesheet -->
<link rel="stylesheet" href="node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.css">
</head>
<body>
<!-- 2. Include the script (ESM) -->
<script type="module" src="node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.js"></script>
<!-- 3. Add the custom element with your username -->
<github-calendar username="moonhuntercode"></github-calendar>
</body>We've designed this library to be incredibly beginner-friendly and robust. Please check out our dedicated guides:
- 📖 Usage & Theming Guide: Learn how to change colors, tooltips, and background themes effortlessly using pure CSS variables.
- 🎨 Advanced Customization Guide: Deep dive into how the component works internally, its semantic HTML structure, and how its Mobile-First responsive CSS works.
- 🏗️ Architecture & Developer Experience (DX): Learn about the Light DOM vs Shadow DOM, TypeScript typing, and Custom Events for error handling.
- 📏 Advanced Layout & Browser Compatibility: How to embed the calendar in Flex/Grid dashboards and the ES6+ browser support matrix.
We welcome contributions from the community! If you'd like to help make this project better, please check out our repository on GitHub:
🐙 moonhuntercode/vanilla-js-github-calendar
Please read our full Contributing Guide (CONTRIBUTING.md) for detailed instructions on how to set up the development environment, run the Vite server, and execute our Vitest test suite.