cal-heatmap

Cal-Heatmap is a javascript charting library to create a time-series calendar heatmap

2,686

290

2,686

View on GitHub View on NPM

Top Related Projects

react-calendar-heatmap

1,213

An svg calendar heatmap inspired by github's contribution graph

github-calendar

1,220

:bar_chart: Embed your GitHub calendar everywhere.

Quick Overview

Cal-HeatMap is a JavaScript library for creating calendar heatmaps. It allows developers to visualize time series data in a GitHub-like calendar view, with customizable colors, domains, and subdomains. The library is lightweight and easy to integrate into web applications.

Pros

Highly customizable with numerous options for appearance and behavior
Supports various data sources, including JSON and CSV
Responsive design that adapts to different screen sizes
Offers plugins for additional functionality like tooltips and legends

Cons

Limited built-in interactivity options
Documentation could be more comprehensive for advanced use cases
Requires additional libraries for some features (e.g., d3.js)
May have a learning curve for developers new to data visualization

Code Examples

Creating a basic calendar heatmap:

const cal = new CalHeatmap();
cal.paint({
  data: {
    source: './data.json',
    type: 'json'
  },
  domain: {
    type: 'month'
  },
  subDomain: {
    type: 'day'
  }
});

Customizing colors and range:

cal.paint({
  range: 3,
  domain: {
    type: 'month'
  },
  subDomain: {
    type: 'day',
    color: {
      range: ['#FFEBE6', '#FF7F50', '#FF4500'],
      scale: 'linear'
    }
  }
});

Adding a tooltip plugin:

import Tooltip from '@cal-heatmap/tooltip';

cal.paint({
  // ... other options
  plugins: [
    new Tooltip({
      text: function(date, value, dayjsDate) {
        return `${dayjsDate.format('LL')}: ${value} events`;
      }
    })
  ]
});

Getting Started

Install Cal-HeatMap using npm:
```
npm install cal-heatmap
```

Import and initialize in your JavaScript file:

import CalHeatmap from 'cal-heatmap';
import 'cal-heatmap/cal-heatmap.css';

const cal = new CalHeatmap();
cal.paint({
  itemSelector: '#cal-heatmap',
  data: {
    source: './data.json',
    type: 'json'
  },
  domain: { type: 'month' },
  subDomain: { type: 'day' }
});

Add a container element in your HTML:
```
<div id="cal-heatmap"></div>
```

Competitor Comparisons

react-calendar-heatmap

1,213

An svg calendar heatmap inspired by github's contribution graph

Pros of react-calendar-heatmap

Built specifically for React, offering seamless integration with React applications
Provides more customization options out of the box, including tooltips and click handlers
Simpler API and easier to get started with for React developers

Cons of react-calendar-heatmap

Limited to React ecosystem, not suitable for non-React projects
Less feature-rich compared to cal-heatmap, which offers more advanced options and plugins
Smaller community and fewer updates, potentially leading to compatibility issues with newer React versions

Code Comparison

react-calendar-heatmap:

<CalendarHeatmap
  startDate={new Date('2016-01-01')}
  endDate={new Date('2016-04-01')}
  values={[
    { date: '2016-01-01', count: 1 },
    { date: '2016-01-22', count: 2 },
    { date: '2016-01-30', count: 3 },
  ]}
/>

cal-heatmap:

const cal = new CalHeatmap();
cal.paint({
  data: {
    source: './datas-years.csv',
    type: 'csv',
    x: 'timestamp',
    y: 'value',
  },
  date: { start: new Date('2000-01-01') },
  range: 12,
});

The code snippets demonstrate the different approaches: react-calendar-heatmap uses a declarative React component, while cal-heatmap employs a more imperative style with configuration options.

github-calendar

1,220

:bar_chart: Embed your GitHub calendar everywhere.

Pros of github-calendar

Specifically designed for GitHub contribution graphs
Simpler implementation for GitHub-style calendars
Includes built-in GitHub API integration

Cons of github-calendar

Less flexible for non-GitHub data visualization
Fewer customization options for appearance and behavior
Limited to yearly view, unlike cal-heatmap's various time ranges

Code Comparison

github-calendar:

GitHubCalendar(".calendar", "your-username", { responsive: true });

cal-heatmap:

const cal = new CalHeatmap();
cal.paint({
  data: { source: 'your-data-source' },
  range: 12,
  domain: { type: 'month' },
  subDomain: { type: 'day' }
});

github-calendar is more straightforward for GitHub-specific use cases, requiring minimal setup. cal-heatmap offers greater flexibility but needs more configuration for similar results.

github-calendar is ideal for quickly implementing GitHub-style contribution graphs, while cal-heatmap is better suited for diverse data visualization needs and customizable heatmap calendars across various time ranges and domains.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Cal-HeatMap

Cal-Heatmap is a javascript charting library to create a time-series calendar heatmap

This library will help you to chart a calendar heatmap, like the Github contribution calendar appearing on each github user's page, but with more features like: