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-calendarusername="moonhuntercode"></github-calendar>The fastest way to use the library in plain HTML without installing anything locally:
<head><!-- Include the external stylesheet --><linkrel="stylesheet" href="https://unpkg.com/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.css"></head><body><!-- Include the script directly from CDN --><scripttype="module" src="https://unpkg.com/vanilla-js-github-calendar"></script><github-calendarusername="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 --><scripttype="module" src="/main.js"></script><!-- Add the component anywhere --><github-calendarusername="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 --><linkrel="stylesheet" href="./node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.css"><!-- 2. Define the import map --><scripttype="importmap">{"imports": {"vanilla-js-github-calendar": "./node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.js"}}</script></head><body><!-- 3. Import gracefully! --><scripttype="module">import'vanilla-js-github-calendar';</script><!-- 4. Add the component --><github-calendarusername="moonhuntercode"></github-calendar></body>If you prefer the classic method without import maps after running npm install:
<head><!-- 1. Include the external stylesheet --><linkrel="stylesheet" href="node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.css"></head><body><!-- 2. Include the script (ESM) --><scripttype="module" src="node_modules/vanilla-js-github-calendar/dist/vanilla-js-github-calendar.js"></script><!-- 3. Add the custom element with your username --><github-calendarusername="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.