rlugojr / calendar-heatmap

A d3 heatmap for representing time series data similar to github's contribution chart

D3 Calendar Heatmap

A d3.js heatmap representing time series data. Inspired by Github's contribution chart

TODO

• Enable/disable tooltip
• Editing of tooltip text
• Editing of the cell gradient colours
• Add optional callback for click events on the day cells
• Add project to bower
• Remove example and vendor folders to separate gh-pages branch [in progress]

Configuration

Property	Usage	Default	Required
data	Chart data	none	yes
selector	DOM selector to attach the chart to	body	no
max	Maximum count	max found in data	no
startDate	Date to start heatmap at	1 year ago	no
colorRange	Minimum and maximum chart gradient colors	['#D8E6E7', '#218380']	no
tooltipEnabled	Option to render a tooltip	true	no
tooltipUnit	Unit to render on the tooltip, can be object for pluralization control	'contributions'	no
legendEnabled	Option to render a legend	true	no
onClick	callback function on day click events (see example below)	null	no
locale	Object to translate every word used, except for tooltipUnit	see below	no

locale default object

{
    months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    days: ['S', 'M', 'T', 'W', 'T', 'F', 'S'],
    No: 'No',
    on: 'on',
    Less: 'Less',
    More: 'More'
}

Dependencies

• d3.js
• moment.js

Usage

1: Add d3.js and moment.js

2: Include calendar-heatmap.js and calendar-heatmap.css <link rel="stylesheet" type="text/css" href="path/tocalendar-heatmap.css"> <script src="path/to/calendar-heatmap.js"></script>

3: Format the data so each array item has a date and count property. As long as new Date() can parse the date string it's ok. Note - there all data should be rolled up into daily bucket granularity.

4: Configure the chart and render it

// chart data example
var chartData = [{
  date: valid Javascript date object,
  count: Number
}];
var chart1 = calendarHeatmap()
              .data(chartData)
              .selector('#chart-one')
              .colorRange(['#D8E6E7', '#218380'])
              .tooltipEnabled(true)
              .onClick(function (data) {
                console.log('onClick callback. Data:', data);
              });
chart1();  // render the chart

control unit pluralization

var chart1 = calendarHeatmap()
              .data(chartData)
              .tooltipUnit(
                [
                  {min: 0, unit: 'contribution'},
                  {min: 1, max: 1, unit: 'contribution'},
                  {min: 2, max: 'Infinity', unit: 'contributions'}
                ]
              );
chart1();  // render the chart

Pull Requests and issues

...are very welcome!