https://github.com/hunter-ji/calendar-heatmap
A lightweight JavaScript library for rendering calendar heatmaps.
https://github.com/hunter-ji/calendar-heatmap
calendar-heatmap heatmap javascript javascript-library javascript-plugin typescript
Last synced: 5 months ago
JSON representation
A lightweight JavaScript library for rendering calendar heatmaps.
- Host: GitHub
- URL: https://github.com/hunter-ji/calendar-heatmap
- Owner: hunter-ji
- License: mit
- Created: 2025-10-15T15:40:07.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-10-16T05:54:39.000Z (5 months ago)
- Last Synced: 2025-10-16T13:17:47.298Z (5 months ago)
- Topics: calendar-heatmap, heatmap, javascript, javascript-library, javascript-plugin, typescript
- Language: JavaScript
- Homepage:
- Size: 152 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Calendar Heatmap
English | [简体中文](./README.zh-CN.md)
Calendar Heatmap is a lightweight JavaScript library for rendering calendar heatmaps. It works in any modern browser, supports multiple time windows, and ships as a single dependency-free bundle.
## Features
- Render yearly, monthly, weekly, or rolling recent-day grids
- Configure square size, gaps, and color scales (arrays or custom functions)
- Localize weekday labels, tooltips, and legend captions via built-in language packs
- Trim large grids automatically to fit narrower containers
- Works with raw arrays of `{ date, value }` style data objects
## Installation
```bash
npm install calendar-heatmap
# or
yarn add calendar-heatmap
```
You can also load the bundled `index.js` directly via a `` tag.
## Quick Start
```html
<div id="heatmap"></div>
<script type="module">
import CalendarHeatmap from 'calendar-heatmap';
const data = [
{ date: '2025-01-01', value: 5 },
{ date: '2025-01-02', value: 3 },
{ date: '2025-01-04', value: 9 }
];
const heatmap = new CalendarHeatmap('#heatmap', data, {
view: 'year',
language: 'en',
legend: true
});
// Update later
heatmap.setOptions({ view: 'recent', recentDays: 30 });
```
## API
### Constructor
```ts
new CalendarHeatmap(container, data?, options?)
```
- `container`: CSS selector or DOM node to mount into
- `data`: array of `{ date | day | dateString, value | count }`
- `options`: see below
### Options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `view` | `'year' \| 'month' \| 'week' \| 'recent'` | `'year'` | Layout preset |
| `year` | `number` | current year | Target year for `year`/`month` views |
| `month` | `number` | current month | Zero-based month index |
| `weekStart` | `0 \| 1` | `0` | First weekday (`0` Sunday, `1` Monday) |
| `recentDays` | `number` | `7` | Number of trailing days for `recent` view |
| `startDate` | `Date \| string` | today | Anchor date for `week` view |
| `squareSize` | `number` | `14` | Pixel size of each day cell |
| `squareGap` | `number` | `2` | Gap between cells |
| `colorScale` | `string[] \| (value, max) => string | { color, level }` | GitHub green palette | Mapping from values to colors |
| `maxValue` | `number \| null` | max of data | Upper bound for scale calculations |
| `legend` | `boolean` | `false` | Render color legend |
| `tooltip` | `boolean` | `true` | Enable hover tooltip |
| `locale` | `string \| string[]` | browser default | ICU locale for date formatting |
| `language` | `string` | `'en'` | Language pack key (see below) |
### Methods
- `setOptions(options)` – merge new options and rerender
- `setData(data)` – replace data and rerender
- `replaceData(data)` – alias of `setData`
- `updateData(data)` – update existing entries (if implemented)
- `setValue(date, value)` – helper to change a single day
- `render()` – force rerender
- `destroy()` – remove DOM nodes and tooltips
### Language Packs
Calendar Heatmap ships with these language keys:
| Key | Locale | Description |
| --- | --- | --- |
| `en` | `en-US` | English |
| `zh-cn` | `zh-CN` | Simplified Chinese |
| `zh-tw` | `zh-TW` | Traditional Chinese |
| `ja` | `ja-JP` | Japanese |
| `fr` | `fr-FR` | French |
| `de` | `de-DE` | German |
| `ko` | `ko-KR` | Korean |
| `es` | `es-ES` | Spanish |
| `it` | `it-IT` | Italian |
Use aliases such as `zh`, `zh-Hans`, `en-GB`, etc. to select the closest match automatically. The active pack controls weekday labels, tooltip text, and legend captions.
Custom packs can be registered by mutating `CalendarHeatmap.languages`:
```js
CalendarHeatmap.languages['pt-br'] = {
locale: 'pt-BR',
legend: { less: 'Menos', more: 'Mais' },
weekdays: ['Dom', 'Seg', 'Ter', 'Qua', 'Qui', 'Sex', 'Sáb'],
tooltip: (value, dateLabel) => `${value} em ${dateLabel}`
};
```
## Development
- Clone the repo and install dependencies with `npm install`
- Run `npm run build` (if available) or open `tests/index.html` in a browser for manual testing
- Linting/tests are minimal; contributions welcome
## License
MIT License.