Calendar Heat Map
This jQuery plugin allows to conveniently display data like contributions on a day by day basis, indicating the count by colors.
Install
Using NPM
npm install jquery-calendar-heatmap
Using bower
bower install jquery-calendar-heatmap
Manual
- Download the latest release from here.
- Copy the
jquery.CalendarHeatmap.jsand thejquery.CalendarHeatmap.cssinto your project. Of cause you can use the minified versions, indicated by.min.jsand.min.cssas well.
Moment.js
Past releases required Moment.js to function. With the release of v1.3.0, Moment.js is no longer required as an dependency, as development has been stopped and it has been deprecated. Of cause it can still be used, or other packages for that matter, to format the labels as described below.
Usage
-
Include jQuery into the header of your html file:
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
-
Include the plugin after jQuery:
<script src="dist/jquery.CalendarHeatmap.min.js"></script>
-
When the DOM is ready call the plugin:
$("#element").CalendarHeatmap( data, options );
Dates (Data)
The provided date needs to be a valid date format that can be interpreted by Moment.js. The date needs to provide at least with year month and day, e.g. YYYY-MM-DD or as a unix timestamp e.g. 1578518342658.
// Provide dates as an array of objects.
// Provide the keys `count` and date. Make sure, each date provided is unique for that day.
var data = [{count: 2, date: "2017-09-23"}, ...]
// Provide dates as an array.
// The dates can have any format as long as year month and day are provided.
var data = [ "2017-09-23", ...]
// Provide dates as an object.
// The key is the date, the value is event count. Make sure the date has this format: `YYYY-MM-DD`
var data = { "2017-09-23": 2, ...}
Interactions (Functions)
After the plugin is initialized for the element, the following options are available to interact with the calendar heatmap.
Get Dates
The currently displayed data from the calendar heatmap can be received using the getDates argument. This is not the original data provided, but the data format internally used.
// Get current data from the calendar heatmap
$("#element").CalendarHeatmap( "getDates" );
Update Dates
The data displayed in the calendar heatmap can be updated/replaced using the updateDates argument and providing new data. In case data should be added to the existing, use the appendDates argument. The data provided can be in any format described above.
// Update/Replace the current data with a new data
$("#element").CalendarHeatmap( "updateDates", data );
Append Dates
Dates can be added to the currently displayed data in the calendar heatmap using the appendDates argument and providing the data to be added. The counts are added to existing dates. The data provided can be in any format described above.
// Append data to the current data
$("#element").CalendarHeatmap( "appendDates", data );
Get Options
The options object with the current settings can be received using the getOptions argument. It contains all options, not just the ones initially set.
// Get the calendar heatmap's current options
$("#element").CalendarHeatmap( "getOptions" );
Update Options
The options object with the current settings can be updated using the getOptions argument. Individual options can be provided, the full object as returned by getOptions is not required.
// Set the calendar heatmap's title option
$("#element").CalendarHeatmap( "updateOptions" {
title: "New Title"
} );
Options
The Calendar Heat Map can be modified using the following options:
// Default options for the heatmap
{
title: null,
months: 12,
weekStartDay: 1,
lastMonth: 1,
lastMonth: "current month",
lastYear: "current year",
labels: {
days: false,
months: true,
custom: {
weekDayLabels: null,
monthLabels: null
}
},
tiles: {
shape: "square"
}
legend: {
show: true,
align: "right",
minLabel: "Less",
maxLabel: "More",
divider: " to "
},
tooltips: {
show: false,
options: {}
}
}
title
You can add a title to the calendar heatmap. If no title is set, or set to null it will get ignored.
months
The number of months to display. If not set, the default number of months to be displayed is 12.
lastMonth
The last month shown in the calendar heatmap. Set the month by setting the value between 1 - 12. If not set, the default is the current month.
lastYear
The year of the last month shown. Use the four letter notation, e.g. 2017. If not set, the default is the current year.
weekStartDay
The first day of the week. Set the day by setting the value between 1 - 7, where 1 is Monday, 2 is Tuesday and so on. If not defined, Monday is the start day.
coloring
There is a set of different color gradients available. By default standard is selected.
Available Color Gradients
The following gradients are available based of Matplotlib for Python: blue, earth, electric, green, picknick, red, teal, standard, viridis. If you want to define your own color gradient, use custom and add the classes defining the colors to your css stylesheet as described below.
Custom Gradient
Just add the colors to be used for the 4 steps as in the example. In this case the name set for coloring would be the base class name custom.
.custom-1 {
background-color: #a6c96a !important;
}
.custom-2 {
background-color: #5cb85c !important;
}
.custom-3 {
background-color: #009e47 !important;
}
.custom-4 {
background-color: #00753a !important;
}
labels
The calendar heatmap has two sets of labels. One for week days and one for months. By default only the month labels are shown. The visibility can be set for either by setting them to true or false.
Custom format
Week day and month labels can be formatted using the Moment.js format (e.g. MM for the month number or MMMM for the full month name). Use an array, to provide custom labels. For months the array needs to contain 12 elements, e.g. ["janv", "févr", ..., "déc."] and for the week days 7 elements starting with Sunday, e.g. ["Dim", "Lun", ..., "Sam"].
labels: {
days: false,
months: true,
custom: {
weekDayLabels: null,
monthLabels: null
}
}
Supported Formats
| Input | Example | Description |
|---|---|---|
| YYYY | 2014 | 4 digit year |
| YY | 14 | 2 digit year |
| M MM | 1..12 | Month number |
| MMM MMMM | Jan..December | Month name |
| D DD | 1..31 | Day of month |
| Do | 1st..31st | Day of month with ordinal |
| DDD DDDD | 1..365 | Day of year |
| d | 0..6 | Day of the week numeric |
| dd | Su...Sa | Day name |
| ddd dddd | Mon...Sunday | Day name |
| ll | Mon...Sunday | Day name |
| ddd dddd | Mon...Sunday | Day name |
Function
In some cases, you might want to use libraries like Moment.js for naming your months and weekdays, even though Moment.js is no longer a required dependency for the plugin. In this case you can simply use a function to modify the label.
The example below is changing the weekday and month labels using Moment.js.
labels: {
months: true,
days: true,
custom: {
weekDayLabels: function( weekday ) {
return moment.weekdays( weekday );
},
monthLabels: function( year, month ) {
return moment.months( month ) + " '" + moment().year( year ).format("YY");
}
}
}
| Label | Function | Available Variables |
|---|---|---|
| Weekday | function ( weekday ) { ... } |
weekday , ranging from 0..6 (Sun..Sat) |
| Month | function ( year, month ) { ... } |
year and day , ranging from 1..12 |
tiles
By default, the shape of each day tile is square. Further the shapes rounded and circle are available.
tiles: {
shape: "square"
}
legend
The legend for the calendar heatmap is located below the heatmap and visible by default. The visibility can be set by setting show to true or false. Set the alignment using align. Options are right, center or left. Labels for min and max can be set using minLabel and maxLabel. Use null to hide the labels. Use the divider to change the word between the numbers in the legends tooltips. By default it is to (e.g. 1 to 10).
legend: {
show: true,
align: "right",
minLabel: "Less",
maxLabel: "More",
divider: " to "
}
tooltips
Tooltips require the Bootstrap library. Regardless of using the library, the tiles with representing data counts have a title element with count and date. This example is using Bootstrap 4.x, but the plugin will work with Bootstrap 3.x as well.
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css">
<!-- Latest compiled and minified JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/popper.min.js"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js"></script>
To enable the tooltips just set show to true. By default it is set to false. All settings for tooltips are available as documented and can be passed on using options.
tooltips: {
show: true,
options: {}
}
This plugin is based on the jQuery Boilerplate.
19 Oct 12, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
3 Sep 9, 2022
42 Dec 29, 2022
2 Feb 28, 2021
144 Jan 6, 2023
3 Sep 28, 2022
10.4k Jan 5, 2023
10 Aug 26, 2022
3 Mar 10, 2022
17 Dec 27, 2022
246 Dec 18, 2022
1 Aug 23, 2022
275 Jan 4, 2023
41 Jan 7, 2023
6 Nov 8, 2022
6 Sep 7, 2022