What is Heatmap.js?

Heatmap (or density) map following my introductory post, I’d like to briefly mention heatmap.js, a JavaScript library that can be easily integrated and used on web pages or web applications, along with tools like Hotjar and other heatmap-based applications.

Heatmap.js

Heatmap.js is a lightweight and easy-to-use JavaScript library developed to visualize three-dimensional data and help understand user behavior by analyzing patterns. Of course, the library offers a flexible structure that can be used for various advanced features (such as maps, visualizations, or page/canvas elements). For example, FIFA.com uses this library to display the density of the ball’s position during soccer matches.

The initial development of the library was initiated by Patrick Wied, which is why the official homepage prominently features the heatmap.js path. On the other hand, the library’s development continues through GitHub.

Heatmap.js Installation and Usage

The library can be obtained either from the sources I mentioned above, or via the package managers npm and yarn.

yarn add heatmap.js
# or
npm install heatmap.js

However, during the demonstration process, I will link the library to the working file via a CDN. For this purpose, we can use services like unpkg or jsdelivr. In most cases, unpkg provides more up-to-date versions.

https://unpkg.com/heatmap.js@2.0.5/build/heatmap.js
https://cdn.jsdelivr.net/npm/heatmapjs@2.0.2/heatmap.js

As mentioned in the installation procedures, let’s take a look at how heatmap.js can be used. The first thing to know is that a global object has been defined for heatmap.js using “h337”. Through this object, heatmap examples can be created.

var heatmapContainer = document.querySelector('.heatmap');

var heatmapInstance = h337.create({
  container: heatmapContainer,
});

h337.create(configObject) returns the `heatmapInstance`. We can customize the heatmap using the `configObject`; properties such as backgroundColor, gradient, radius, opacity, etc.

var config = {
  container: document.getElementById('heatmapContainer'),
  radius: 10,
  maxOpacity: .5,
  minOpacity: 0,
  blur: .75
};
var heatmapInstance = h337.create(config);

For more detailed information, please refer to the relevant documentation¹.

Following the above definitions, the container (element, class, or id) must be specified, with the container parameter being mandatory (as part of the configObject). For example, let’s assume we have linked the .heatmap class to the body element. At this stage, we must decide how the heatmap will be created.

heatmapInstance.setData({
  max: 5,
  data: [{
    x: 120,
    y: 120,
    value: 20,
    radius: 250
  }, {
    x: 450,
    y: 100,
    value: 5
  }]
});

As shown above, within the data content of heatmapInstance.setData(), we can specify x and y positions, heat intensity, and the degree of this intensity. As a result, we obtain the following visualization.

We could also achieve the above operation using heatmapInstance.addData(). However, in that case, we would have to specify data points immediately.

var dataPoint = {
  x: 5,
  y: 5,
  value: 100
};
heatmapInstance.addData(dataPoint);

For multiple data points, the usage would be as follows.

var dataPoints = [dataPoint, dataPoint, dataPoint, dataPoint];
heatmapInstance.addData(dataPoints);

The most important difference between heatmapInstance.setData() and heatmapInstance.addData() is that setData() requires “min”, “max”, and “data” properties, and furthermore, it will remove all existing data points from the heatmap instance and restart the data store, then apply its own data set.

var data = {
  max: 100,
  min: 0,
  data: [
    dataPoint, dataPoint, dataPoint, dataPoint
  ]
};
heatmapInstance.setData(data);

The basic definitions above will be more than sufficient for our needs. However, for any additional information, you may refer to the heatmap.js documentation¹.

As I mentioned earlier, in the example, I implemented the config definition using the body class. Additionally, I requested that addData process the mouse position in real time. When you implement the example, you can view the relevant position data by opening your browser’s JavaScript console.

<body class="heatmap">
  <section class="section">
    <div class="container">
      <h1 class="title">
        Hello World
      </h1>
      <p class="subtitle">My first website with <strong>Bulma</strong>!</p>
    </div>
  </section>

  <script src="https://unpkg.com/heatmap.js@2.0.5/build/heatmap.js"></script>

  <script>
    window.onload = function () {
      var heatmapContainer = document.querySelector('.heatmap');

      var heatmapInstance = h337.create({
        container: heatmapContainer,
        radius: 50
      });

      heatmapContainer.onmousemove = heatmapContainer.ontouchmove = function (e) {
        e.preventDefault();
        var x = e.layerX;
        var y = e.layerY;
        if (e.touches) {
          x = e.touches[0].pageX;
          y = e.touches[0].pageY;
        }

        heatmapInstance.addData({
          x: x,
          y: y,
          value: 1
        });

        console.log('X:' + x + ',Y:' + y);
      };

    };
  </script>

The example above is certainly one of the most basic approaches. For more comprehensive examples, please check the examples page on the heatmapjs website. I believe the map and photo examples will provide particular value for e-commerce applications.

Footnotes

1. heatmap.js Documentation ↩ ↩²