Skip to main content

Migrating from 3.x

The current v4 release is rewritten from the ground up, and have a lot of major breaking changes.

The last 3.x release was from October 2016, and was built on top of a vanilla JS codebase from 2012.

After 7 years, the javascript scene has seen some changes, such as the maturity of ECMAScript, babel, and other various bundler tools, as well as newer versions of the underlying d3.js libraries used by Cal-Heatmap.

Aside from some bugfixes and new features, the v4 branch has been rewritten from the ground up as ES modules, and transpiled to support older browsers. This direction allows an easier code maintainability and readability than the previous single file 3k lines codebase.

Most of the breaking changes come from the settings renaming, and methods removal.

Major changes

  • All functions using callbacks have been migrated to use a Promise instead
  • Code base rewritten in Typescript, and ESnext (babel transpiled for older browser support)
  • New plugin system to extend/modify calendar capabilities
  • New Template system to use user-created calendar layout
  • All dates handling delegated to dayjs
  • Bundles for ESM, UMD
  • Support for D3.js v6 and v7

Default settings update

  • animationDuration has been decreased from 500ms to 200ms.

New settings


Control the sort order of the domains


Set a custom date locale. Default to en


Instruct the calendar how to extract the date from your dataset


Instruct the calendar how to extract the value from your dataset


Instruct the calendar how to aggregate values from same time range


Dynamically color the subDomain's label


New option, grouping previous functions from legend and legendColors, to control how to colorize your dataset

Renamed/moved settings


Renamed to label.textAlign.


Moved inside the domain namespace.


date is now a namespace, grouping all date related options. Old date option has been moved to date.start


Moved to date.min


Moved to date.max


Moved to date.highlight


data is now a namespace, grouping all data related options. Old data option has been moved to data.source


Moved to data.type


domain is now a namespace, grouping all domain related options. Old doamin option has been moved to subDomain.type


Moved to domain.gutter


Moved to domain.padding


Moved to domain.dynamicDimension


Moved to domain.label


subDomain is now a namespace, grouping all subDomain related options. Old subDomain option has been moved to subDomain.type


Moved to subDomain.width and subDomain.height


Moved to subDomain.radius


Moved to subDomain.gutter


Moved to subDomain.label

Removed settings


Use a custom date.locale, or a custom Template.

legend, displayLegend, legendCellSize, legendCellPadding, legendCellMargin, legendVerticalPosition, legendHorizontalPosition, legendOrientation, legendTitleFormat

Removed, migrated to Legend plugin


Moved to a new option inside scale.

subDomainDateFormat, subDomainTitleFormat, itemName

Removed, use Tooltip text


Removed, migrated to Tooltip plugin.


CalHeatmap is not expecting a strict opinionated data structure anymore, and accept an array of object, just like d3.js. See data.x, data.y and data.groupY

colLimit, rowLimit

To customize the layout of the subDomains, a new Template system has been introduced

nextSelector, previousSelector

The same objective can be achieved by adding an onClick() event on your desired DOM Element, and call next() or previous() on the calendar instance.


Data are treated as they are, you can preprocess/transform them using data.y and data,.groupY options.


Obsolete, was only used internally to namespace the nextSelector and previousSelector onclick events.

New methods

  • on(eventName, callback) has been added, to replace all old callback functions.

See Events for the complete list of events

afterLoad and onComplete removed

These events are now obsolete, as all methods now return a promise.

Renamed methods

  • init(options) renamed to paint(options). This method can now be called multiple times with new options, and will update the calendar dynamically, instead of redrawing it from scratch.
  • update(data, afterLoad, updateMode) renamed to fill(data), to reflect that it's for updating data only, and not the options. It now accepts only data as its only argument, all other arguments can be set via paint()
  • destroy(callback) do not take a callback argument anymore, and returns a Promise.

Removed methods


The same objective can be achieved by calling jumpTo() with your initial start date on the calendar instance.

showLegend(), removeLegend(), setLegend()

The same objective can be achieved by calling paint({}, [[Legend, LEGEND_OPTIONS]]) on the calendar instance.


The same objective can be achieved by calling paint({ date: { highlight: [YOUR_DATES] } }) on the calendar instance.


Delegated to a plugin

Over changes

  • All the CSS classes used for data coloring have been removed. The scale option allow a more precise color customization.
  • All the x_ subDomains variants aside from x_day have been removed. You can re-created them with a custom template.
  • The mouse cursor do not change to pointer when hovering on a subDomain cell automatically when there is an onClick event registered, since there is no reliable way to detect if an onClick listener is registered anymore.
  • Test suite migrated to Jest, and start testing on browserstack against a matrix of browsers.