heatmap.js Documentation

What is it about the colors in the overview?

The colors in the overview is a prioritization of API functions:
red **hot docs** : most commonly used functions ;-)
green : used for customized implementations
blue : rarely used functionality
got it, thank you

h337

"h337" is the name of the global object registered by heatmap.js. You can use it to create heatmap instances

h337.create(configObject)

Returns a heatmapInstance.

Use h337.create to create heatmap instances. A Heatmap can be customized with the configObject.
The configObject parameter is required.

Possible configuration properties:
  • container (DOMNode) *required*
    A DOM node where the heatmap canvas should be appended (heatmap will adapt to the node's size)
  • backgroundColor (string) *optional*
    A background color string in form of hexcode, color name, or rgb(a)
  • gradient (object) *optional*
    An object that represents the gradient (syntax: number string [0,1] : color string), check out the example
  • radius (number) *optional*
    The radius each datapoint will have (if not specified on the datapoint itself)
  • opacity (number) [0,1] *optional* default = .6
    A global opacity for the whole heatmap. This overrides maxOpacity and minOpacity if set!
  • maxOpacity (number) [0,1] *optional*
    The maximal opacity the highest value in the heatmap will have. (will be overridden if opacity set)
  • minOpacity(number) [0,1] *optional*
    The minimum opacity the lowest value in the heatmap will have (will be overridden if opacity set)
  • onExtremaChange function callback
    Pass a callback to receive extrema change updates. Useful for DOM legends.
  • blur (number) [0,1] *optional* default = 0.85
    The blur factor that will be applied to all datapoints. The higher the blur factor is, the smoother the gradients will be
  • xField (string) *optional* default = "x"
    The property name of your x coordinate in a datapoint
  • yField (string) *optional* default = "y"
    The property name of your y coordinate in a datapoint
  • valueField (string) *optional* default = "value"
    The property name of your y coordinate in a datapoint

Example configurations

Simple configuration with standard gradient
// create configuration object
var config = {
  container: document.getElementById('heatmapContainer'),
  radius: 10,
  maxOpacity: .5,
  minOpacity: 0,
  blur: .75
};
// create heatmap with configuration
var heatmapInstance = h337.create(config);
Custom gradient configuration
// create configuration object
var config = {
  container: document.getElementById('heatmapContainer'),
  radius: 10,
  maxOpacity: .5,
  minOpacity: 0,
  blur: .75,
  gradient: {
    // enter n keys between 0 and 1 here
    // for gradient color customization
    '.5': 'blue',
    '.8': 'red',
    '.95': 'white'
  }
};
var heatmapInstance = h337.create(config);

heatmapInstance

Heatmap instances are returned by h337.create. A heatmap instance has its own internal datastore and renderer where you can manipulate data. As a result the heatmap gets updated (either partially or completely, depending on whether it's necessary).

heatmapInstance.addData(object|array)

Returns heatmapInstance

Use this functionality only for adding datapoints on the fly, not for data initialization! heatmapInstance.addData adds a single or multiple datapoints to the heatmaps' datastore.
// a single datapoint
var dataPoint = {
  x: 5, // x coordinate of the datapoint, a number
  y: 5, // y coordinate of the datapoint, a number
  value: 100 // the value at datapoint(x, y)
};
heatmapInstance.addData(dataPoint);

// multiple datapoints (for data initialization use setData!!)
var dataPoints = [dataPoint, dataPoint, dataPoint, dataPoint];
heatmapInstance.addData(dataPoints);

heatmapInstance.setData(object)

Returns heatmapInstance

Initializes a heatmap instance with a dataset. "min", "max", and "data" properties are required.
setData removes all previously existing points from the heatmap instance and re-initializes the datastore.
var data = {
  max: 100,
  min: 0,
  data: [
    dataPoint, dataPoint, dataPoint, dataPoint
  ]
};
heatmapInstance.setData(data);

heatmapInstance.setDataMax(number)

Returns heatmapInstance

Changes the upper bound of your dataset and triggers a complete rerendering.
heatmapInstance.setDataMax(200);
// setting the maximum value triggers a complete rerendering of the heatmap
heatmapInstance.setDataMax(100);

heatmapInstance.setDataMin(number)

Returns heatmapInstance

Changes the lower bound of your dataset and triggers a complete rerendering.
heatmapInstance.setDataMin(10);
// setting the minimum value triggers a complete rerendering of the heatmap
heatmapInstance.setDataMin(0);

heatmapInstance.configure(configObject)

Returns heatmapInstance

Reconfigures a heatmap instance after it has been initialized. Triggers a complete rerendering.
var nuConfig = {
  radius: 10,
  maxOpacity: .5,
  minOpacity: 0,
  blur: .75
};
heatmapInstance.configure(nuConfig);

heatmapInstance.getValueAt(object)

Returns value at datapoint position

Note: The returned value is an interpolated value based on the gradient blending if point is not in store
heatmapInstance.addData({ x: 10, y: 10, value: 100});
// get the value at x=10, y=10
heatmapInstance.getValueAt({ x: 10, y: 10 }); // returns 100

heatmapInstance.getData()

Returns a persistable and reimportable (with setData) JSON object

var currentData = heatmapInstance.getData();
// now let's create a new instance and set the data
var heatmap2 = h337.create(config);
heatmap2.setData(currentData); // now both heatmap instances have the same content

heatmapInstance.getDataURL()

Returns dataURL string

The returned value is the base64 encoded dataURL of the heatmap instance.
heatmapInstance.getDataURL(); // data:image/png;base64...
// ready for saving locally or on the server

heatmapInstance.repaint()

Returns heatmapInstance

Repaints the whole heatmap canvas