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-calendarSimply include the script and use the <github-calendar> HTML tag. No JavaScript configuration required!
<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.