Skip to content

README.md

Latest commit

 

History

History
135 lines (102 loc) · 5.38 KB

README.md

File metadata and controls

135 lines (102 loc) · 5.38 KB
Raw

📅 Vanilla JS GitHub Calendar

NPM Version Live Demo License: MIT

A lightweight, dependency-free Web Component that displays a GitHub contributions calendar (heatmap) for any user. Built with pure Vanilla JS, HTML5, and CSS3.

🚀 View the Live Demo!

Screenshot

Features

  • 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.

Quick Start

1. Installation

npm install vanilla-js-github-calendar

2. Usage

You 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>

Option A: Using a CDN (Easiest, no build tools required)

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>

Option B: Modern Bundlers (Vite, Webpack, React, Vue, etc.)

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>

Option C: Local Files via Import Maps (Vanilla HTML)

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>

Option D: Classic Local Files (Direct Script Tag)

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>

Documentation & Guides

We've designed this library to be incredibly beginner-friendly and robust. Please check out our dedicated guides:

🤝 Contributing

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.