JavaScript Library for Creating an Interactive Timeline Heatmap

This JavaScript library is for creating an interactive timeline heatmap. Each colored “block” in the timeline represents a time point (e.g. one day). The blocks have differenct labels, colors, and heights (optional), which can encode three different dimensions. It is also possible to store custom dimensions in the DOM elements’ data attribute. One example that uses this chart is Smell PGH. In the example, each block means one day, and the color of the blocks represent the concentration of smell reports in that day.


First, include the following libraries on html file:

<link href="TimelineHeatmap.css" media="screen" rel="stylesheet" type="text/css"/>
<script src="jquery.min.js" type="text/javascript"></script>
<script src="TimelineHeatmap.js" type="text/javascript"></script>


Create a html container for Heatmap

<div id="chart-container"></div>


Generate a basic heat map in a container you specify.

var container_id = "chart-container";
var settings = {
  data: [["Mar 01", 1, 3, "03/01/2018"], ["Mar 02", 2, 15, "03/02/2018"]],
  columnNames: ["label", "color", "height", "custom_field"],
  dataIndexForLabels: 0,
  dataIndexForColors: 1,
  dataIndexForHeights: 2
fbchart = new edaplotjs.TimelineHeatmap(container_id, settings);

More configuration options to customize the heat map.

myHeatmap = new edaplotjs.TimelineHeatmap('chart-container', {
  data: myData,
  columnNames: ["label", "color", "height", "custom_field"],
  // The column index in the data matrix for showing labels under each block
  dataIndexForLabels: 0,
  // The column index in the data matrix for coding the color of each block
  dataIndexForColors: 1,
  // The column index in the data matrix for coding the height of each block
  dataIndexForHeights: 2,
  // Enable rendering each block by color quatiles
  // Default: false
  useColorQuantiles: true,
  // The bin and range of the color
  colorBin: [],
  colorRange: [],
  // The bin and range of the height
  heightBin: [],
  heightRange: [],
  // Prevent adding events to blocks with color value zero
  noEventWhenColorValueZero: true,
  // Add an arrow on the left of the timeline for appending new data. 
  // If this setting is a function, when the arrow is clicked, the function will be triggered.
  addLeftArrow: true,
  // The text on the bottom of the arrow
  leftArrowLabel: 'More'

Callback functions.

myHeatmap = new edaplotjs.TimelineHeatmap('chart-container', {
  click: function ($e, obj) {
    console.log("click", $, obj);
  select: function ($e, obj) {
    console.log("select", $, obj);
  create: function (obj) {
    console.log("create", obj);

API methods

// clear block selection
// select a specified block
// Select the last block
// Select the first block
// Prepend blocks to the left of the timeline.
var data = [["Mar 03", 9, 2, "03/03/2018"], ["Mar 04", 14, 2, "03/04/2018"]];
// Up<a href="">date</a> blocks
var data = [["Mar 03", 9, 2, "03/03/2018"], ["Mar 04", 14, 2, "03/04/2018"]];
// Get the data of the current selected block.
// Get the jQuery DOM element of the current selected block.
// Get the current number of blocks.
// Use index to get the data for the corresponding block.
// Get the data for the first block
// Get the data for the last block
// Hide the left arrow
// Show the left arrow
// Set the opacity of the left arrow
// Disable the left arrow
// Enable the left arrow

See live demo and download source code.


This awesome plugin is developed by yenchiah. Visit their official github repository for more information and follow for future updates.