Generate Customizable Heat Maps For Date-based Activities – Heat.js

Preview:

Description:

Heat.js is a lightweight JavaScript library that generates customizable heat maps to visualize date-based activity and trends.

It uses color shading in calendar blocks to indicate intensity – lighter colors for less activity, darker colors for more.

Inspired by GitHub’s contribution graph, Heat.js is great for showcasing user activity, website traffic, or any other time-based data.

How to use it:

1. Download the package and load the following JS/CSS files in the document.

<!-- Core -->
<link rel="stylesheet" href="/dist/heat.js.css" />
<script src="/dist/heat.js"></script>
<!-- Light Theme -->
<link rel="stylesheet" href="/dist/theme/heat.js.light.theme.css" />
<!-- Languages -->
<script src="/dist/translations/heat.translations.en.js"></script>
<script src="/dist/translations/heat.translations.es.js"></script>
<script src="/dist/translations/heat.translations.fr.js"></script>
...

2. Create a container to hold the heat map and pass the options via data-heat-js attribute. All possible options and callbacks:

• view: “map”, “statistics”, or “chart”
• views.map.showDayNames: true
• views.map.showMonthDayGaps: true
• views.map.showMonthNames: true
• views.map.monthsToShow: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]
• views.map.daysToShow: [ 1, 2, 3, 4, 5, 6, 7 ]
• views.map.showNoDataMessageWhenDataIsNotAvailable: false
• views.map.placeMonthNamesOnTheBottom: false
• views.map.showDaysInReverseOrder: false
• views.map.showDayNumbers: false
• views.map.keepScrollPositions: false
• views.chart.enabled: true
• views.chart.showMonthNames: true
• views.chart.monthsToShow: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]
• views.chart.daysToShow: [ 1, 2, 3, 4, 5, 6, 7 ]
• views.chart.showChartYLabels: true
• views.chart.showInReverseOrder: false
• views.chart.showLineNumbers: false
• views.chart.keepScrollPositions: false
• views.statistics.enabled: true
• views.statistics.monthsToShow: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ]
• views.statistics.showInReverseOrder: false
• views.statistics.daysToShow: [ 1, 2, 3, 4, 5, 6, 7 ]
• views.statistics.showChartYLabels: true
• views.statistics.showColorRangeLabels: true
• views.statistics.useColorRangeNamesForLabels: false
• views.statistics.showRangeNumbers: false
• views.statistics.keepScrollPositions: false
• views.map.showMinimalDayNames: false
• views.map.showMonthsInReverseOrder: false
• views.days.enabled: true
• views.days.showChartYLabels: true
• views.days.showDayNames: true
• views.days.showInReverseOrder: false
• views.days.showDayNumbers: false
• views.days.monthsToShow: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
• views.days.daysToShow: [1, 2, 3, 4, 5, 6, 7]
• views.days.keepScrollPositions: false
• title.text: “Heat.js”
• title.showText: true
• title.showYearSelector: true
• title.showRefreshButton: false
• title.showExportButton: false
• title.extraSelectionYears: 50
• title.showYearSelectionDropDown: true
• title.showImportButton: false
• title.showConfigurationButton: true
• title.showTitleDropDownButton: true
• title.showTitleDropDownHeaders: true
• title.showCurrentYearButton: true
• description.text: null
• description.url: null
• description.urlTarget: ‘_blank’
• guide.enabled: true
• guide.colorRangeTogglesEnabled: true
• guide.showLessAndMoreLabels: true
• guide.showNumbersInGuide: false
• tooltip.delay: 750
• tooltip.dayText: “{d}{o} {mmmm} {yyyy}”
• colorRanges: [ { minimum: 10, cssClassName: ‘day-color-1’ } ]).
• year: the current year
• exportType: “csv”, “xml”, “txt” or “json”
• useLocalStorageForData: false
• allowFileImports: true
• yearsToHide: []
• holidays: []
• dataFetchDelay: 60000
• showOnlyDataForYearsAvailable: false
• showHolidaysInDayToolTips: false
• onDayClick: function(date, count){}
• onBackYear: function(year){}
• onNextYear: function(year){}
• onSetYear: function(year){}
• onRefresh: function(element){}
• onBeforeRender: function(element){}
• onRenderComplete: function(element){}
• onDestroy: function(element){}
• onExport: function(element){}
• onTypeSwitch: function(type){}
• onDayToolTipRender: function(date, count){}
• onAdd: function(element){}
• onRemove: function(element){}
• onReset: function(element){}
• onTypeSwitch: function(type){}
• onViewSwitch: function(view){}
• onColorRangeTypeToggle: function(id, visible){}
• onImport: function(element){}
• onStatisticClick: function(colorRange){}
• onDataFetch: function(element){}
• onClear: function(element){}
• onUpdate: function(element){}
• onOptionsUpdate: function(option){}
• onWeekDayClick: function(weekday){}

<div data-heat-js="{ 'showDayNames': true, 'views': { 'map': { 'showDayNames': true } }, onDayClick': onDayClick }">
  ...
</div>

3. Add activities or trends to the heat map.

$heat.addDate(elementId, date, type, [triggerRefresh]):

4. Available configurations.

$heat.setConfiguration({
  safeMode: false,
  domElementTypes: "*",
  text: {
    stText: "st",
    ndText: "nd",
    rdText: "rd",
    thText: "th",
    backButtonText: "Back",
    nextButtonText: "Next",
    refreshButtonText: "Refresh",
    exportButtonText: "Export",
    lessText: "Less",
    moreText: "More",
    dateText: "Date",
    countText: "Count",
    monthNames: '[ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ],
    dayNames: '[ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ]'),
    dateText: 'Date',
    countText: 'Count',
    mapText: 'Map',
    chartText: 'Chart',
    noChartDataMessage: 'There is currently no data to view.',
    statisticsText: 'Statistics',
    noStatisticsDataMessage: 'There is currently no statistics to view.',
    unknownTrendText: 'Unknown',
    importButtonText: 'Import',
    noMapDataMessage: 'There is currently no data to view.',
    objectErrorText: 'Errors in object: {{error_1}}, {{error_2}}',
    attributeNotValidErrorText: 'The attribute '{{attribute_name}}' is not a valid object.',
    attributeNotSetErrorText: 'The attribute '{{attribute_name}}' has not been set correctly.',
    closeToolTipText: "Close",
    configurationToolTipText: "Configuration",
    configurationTitleText": "Configuration",
    visibleMonthsText": "Visible Months",
    visibleDaysText: "Visible Days",
    dataText: "Data",
    colorRangesText: "Color Ranges",
    yearText: "Year",
    daysText: "Days",
    noDaysDataMessage: "There are currently no days to view.",
    backButtonSymbolText: "←",
    nextButtonSymbolText: "→",
    refreshButtonSymbolText: "↻",
    exportButtonSymbolText: "↓",
    importButtonSymbolText: "↑",
    currentYearSymbolText: "⏎",
    currentYearText: "Current Year",
  }
})

5. More API methods.

// add dates
$heat.addDates(elementId, dates, [triggerRefresh])
// add a date
addDate(elementId, date, [triggerRefresh])
// remove
$heat.removeDate(elementId, date, type, [triggerRefresh]);
// reset
$heat.reset(elementId, [triggerRefresh]);
// refresh
$heat.refresh(elementId);
// refresh all instances
$heat.refreshAll();
// destroy
$heat.destroy(elementId);
// destroy all instances
$heat.destroyAll();
// set year
$heat.setYear(elementId, year)
// get year
$heat.getYear(elementId);
// set options
$heat.setConfiguration(newOptions);
// render a new heat map
$heat.render(element, options);
// render all heat maps
$heat.renderAll();
// set the year
$heat.setYear(elementId, year);
$heat.setYearToHighest(elementId);
$heat.setYearToLowest(elementId);
// import data from an array of file objects
$heat.import(elementID, files)
// export type: defaults to "csv", also accepts "json", "xml", and "txt"
$heat.export(elementID, exportType);
// return all the IDs of the elements
$heat.getIds();
// reset all
$heat.resetAll();
// move to the prev year
$heat.moveToPreviousYear(elementId);
// move to the next year
$heat.moveToNextYear(elementId);
// move to the current year
$heat.moveToCurrentYear(elementId);
// switch the view
$heat.switchView(elementId, viewName);
// switch the type
$heat.switchType(elementId, type)
// update options
$heat.updateOptions(elementId, newOptions)
// clear a date
$heat.clearDate(elementId, date, [triggerRefresh])
// update a date
$heat.updateDate(elementId, date, count, [triggerRefresh])

5. Override the default CSS variables to create your own styles.

:root {
  // Fonts
  --heat-js-default-font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", "Liberation Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  // Colors
  --heat-js-color-black: #3b3a3a;
  --heat-js-color-white: #adbac7;
  --heat-js-color-snow-white: #F5F5F5;
  --heat-js-color-gray: #AAAAAA;
  // Containers
  --heat-js-container-background-color: #22272e;
  --heat-js-container-border-color: #454c56;
  // ToolTip
  --heat-js-tooltip-background-color: var(--heat-js-container-background-color);
  --heat-js-tooltip-border-color: var(--heat-js-container-border-color);
  --heat-js-tooltip-text-color: var(--heat-js-color-white);
  // Year
  --heat-js-years-background-color: var(--heat-js-container-background-color);
  --heat-js-years-border-color: var(--heat-js-container-border-color);
  --heat-js-years-text-color: var(--heat-js-color-white);
  --heat-js-years-background-color-hover: var(--heat-js-button-background-color-hover);
  --heat-js-years-text-color-hover: var(--heat-js-color-snow-white);
  // Title
  --heat-js-title-opener-text-color-hover: var(--heat-js-color-gray);
  --heat-js-title-background-color: var(--heat-js-container-background-color);
  --heat-js-title-border-color: var(--heat-js-container-border-color);
  --heat-js-title-text-color: var(--heat-js-color-white);
  --heat-js-title-background-color-hover: var(--heat-js-button-background-color-hover);
  --heat-js-title-text-color-hover: var(--heat-js-color-snow-white);
  // Days
  --heat-js-day-background-color: #2d333b;
  --heat-js-day-border-color: var(--heat-js-container-border-color);
  --heat-js-day-background-color-hover: var(--heat-js-container-border-color);
  --heat-js-day-spacing: 6.3px;
  --heat-js-day-opacity-hover: 0.7;
  --heat-js-day-opacity-active: 0.5;
  --heat-js-day-size: 1.1rem;
  --heat-js-day-chart-width: 10px;
  // Days - Colors
  --heat-js-day-color-1-background-color: rgba( 80, 200, 120, 0.25 );
  --heat-js-day-color-1-border-color: rgba( 80, 200, 120, 0.15 );
  --heat-js-day-color-1-text-color: var(--heat-js-color-white);
  --heat-js-day-color-2-background-color: rgba( 80, 200, 120, 0.50 );
  --heat-js-day-color-2-border-color: rgba( 80, 200, 120, 0.25 );
  --heat-js-day-color-2-text-color: var(--heat-js-color-white);
  --heat-js-day-color-3-background-color: rgba( 80, 200, 120, 0.75 );
  --heat-js-day-color-3-border-color: rgba( 80, 200, 120, 0.50 );
  --heat-js-day-color-3-text-color: var(--heat-js-color-black);
  --heat-js-day-color-4-background-color: rgba( 80, 200, 120, 1 );
  --heat-js-day-color-4-border-color: rgba( 80, 200, 120, 0.75 );
  --heat-js-day-color-4-text-color: var(--heat-js-color-black);
  // Button
  --heat-js-button-background-color: var(--heat-js-day-background-color);
  --heat-js-button-border-color: var(--heat-js-container-border-color);
  --heat-js-button-text-color: var(--heat-js-color-white);
  --heat-js-button-background-color-hover: var(--heat-js-container-border-color);
  --heat-js-button-text-color-hover: var(--heat-js-color-snow-white);
  --heat-js-button-background-color-active: #616b79;
  --heat-js-button-text-color-active: var(--heat-js-color-snow-white);
  // Borders
  --heat-js-border-radius: 0.5rem;
  --heat-js-border-radius-day: 0.35rem;
  --heat-js-border-size: 0.5px;
  --heat-js-border-size-day: 1px;
  // Sizes
  --heat-js-spacing: 10px;
  --heat-js-spacing-font-size: 0.85rem;
  // Fonts
  --heat-js-text-bold-weight: 400;
  --heat-js-title-bold-weight: 900;
  --heat-js-text-bold-weight-active: 900;
  // Transitions
  --heat-js-transition: all .3s;
  --heat-js-animation-length: 0.5s;
}

Changelog:

v4.3.1 (03/18/2025)

• Added a new border to the left side of the main UI to make the control stand out a bit more.
• The drop-down menus in the default dark view are now easier to see against the background.
• The day names in the “Map” view remain visible on smaller screens.

v4.3.0 (03/07/2025)

• Updated all the NPM packages to the latest versions.
• Updated SASS usages of import to use (with minor accessor updates).
• Scroll bars are now only shown when required for the views, and are styled using the default theme colors.
• Fixed an issue that caused scroll bars to appear when not required.

v4.2.2 (10/14/2024)

• UI improvements and fixes

v4.2.1 (09/02/2024)

• UI improvements and fixes

v4.2.0 (08/20/2024)

• UI improvements and fixes
• Added new options

v4.1.1 (07/25/2024)

• UI improvements and fixes

v4.1.0 (07/18/2024)

• Code improvement
• Add more options

v4.0.5 (07/16/2024)

• Improvement

v4.0.4 (07/09/2024)

• Added a “build-all” script option so that everything (including minimized versions) can be built with one command.
• Minor CSS layout improvements.
• Removed deprecated “cancelBubble” usages and replaced them with “stopPropagation()”.
• Rewritten “getStyleValueByName()” to use the modern implementation to get a style.
• Fixed a type mismatch between the PublicApi structure and the implementation.
• Improved more type implementations.
• Internal storage date methods are now exported via the “DateTime.ts” module.
• The “import” public API function will now show the select files dialog if no files are passed.

v4.0.3 (07/06/2024)

• Improvements

v4.0.2 (07/06/2024)

• Bugfixes

v4.0.1 (07/04/2024)

• Bugfixes

v4.0.0 (07/04/2024)

• Rewritten in TypeScript

v3.2.0 (06/17/2024)

• Added new options and methods.
• Added export support

v3.1.2 (05/31/2024)

• All text translations now allow empty text to be passed (which will prevent them from defaulting to the English version).

v3.1.1 (05/07/2024)

• Added more options.
• Fixed bugs.

v3.1.0 (04/02/2024)

• Added more options.

v3.0.0 (03/29/2024)

• Added more options.
• CSS renames to ensure they do not collide with other libraries, along with internal refactoring.
• Added a new configuration icon to the main display, which will allow the Days/Months to be toggled easily per view!
• Added a brand new view called “Days”, which will allow you to see the counts for the days of the week for the entire year.
• Redesigned the title drop-down menu.
• Fixed bugs.

v2.8.0 (03/18/2024)

• Added more options.
• Added support for import from CSV

v2.7.2 (03/18/2024)

• The “unload” window event has been replaced with “pagehide”
• Added more options

v2.7.1 (03/07/2024)

• Minor improvements

v2.7.0 (03/06/2024)

• New options
• Code improvements.
• Bugfixes.

v2.6.0 (02/26/2024)

• Added new options, callbacks and methods.
• Code improvements.
• Bugfixes.

v2.5.0 (02/21/2024)

• Added new options, callbacks and methods.
• Added more translations.
• Updated UI

v2.4.0 (02/19/2024)

• Added holiday support
• Added data pulling support
• Added new options and callbacks
• Improved code

v2.3.0 (02/18/2024)

• Added “Import” button
• Added new options
• Bugfixes

v2.2.0 (02/17/2024)

• Export to TXT support
• Added new options
• Changed UI
• Fixed bugs

v2.1.1 (02/15/2024)

• Bugfixes

v2.1.0 (02/13/2024)

• Added file-dropping support to all views, which allows exported JSON data to be re-imported to the currently selected trend type.
• Updated options
• Added new options

v2.0.0 (02/11/2024)

• Added more options
• Added more translations
• Added more themes
• Fixed bugs
• Updated CSS

1.9.2 (02/06/2024)

• Added more options

1.9.0 (02/05/2024)

• Export to XML support
• Add more API
• Code improvement
• Bugfix

1.8.3 (02/04/2024)

• Minor color and layout adjustments

1.8.2 (02/03/2024)

• Added 13 languages

1.8.1 (02/02/2024)

• 15 new languages and fixes

1.8.0 (02/02/2024)

• Added a new “Statistics” view, which shows the total count per map range type (in a bar chart)
• Added label support for the bottom right
• Added more options and API methods

1.7.1 (02/01/2024)

• Bugfixes

1.7.0 (02/01/2024)

• Added export to JSON support
• Added more options and API methods.
• Added more themes
• Updated CSS

1.6.4 (01/30/2024)

• Bugfix

1.6.3 (01/30/2024)

• Update

1.6.2 (01/29/2024)

• Added hover effect for the guide day toggles that are turned off.

1.6.1 (01/29/2024)

• Bugfixes

1.6.0 (01/29/2024)

• Added more options and API methods.
• Added custom tooltip support!

1.5.1 (01/27/2024)

• Added more options
• Bugfixed

1.5.0 (01/25/2024)

• Added more options
• Updated CSS
• Optimized code

1.4.0 (01/23/2024)

• Added more options
• Added more API methods
• Updated CSS

1.3.0 (01/23/2024)

• Added more options
• Added more methods

1.2.1 (01/22/2024)

• Fixed a minor fault that caused the month names to be centred.
• Fixed the day name labels shown on the right, so are now the same height/margin as the days, allowing them to align correctly.
• Added new “:root” variable “–heat-js-border-size-day”, which states the size to use the days/day name heights.
• Fixed the day name labels not being aligned to the middle vertically.
• Increased the default size of the days from 0.85rem to 1.1rem.
• The day names are now hidden in mobile view.
• The type/guide toggles are now stacked in mobile view and centred (make them much easier to access and see).
• The export/refresh buttons are now hidden in mobile view.
• Added new “:root” variable “–heat-js-button-text-color”, which will allow you to override the button text colors.
• The light mode theme buttons now use a darker background color (so they stand out).
• Added the button margin back in for the test files.

1.2.0 (01/19/2024)

• Added new options
• Updated CSS
• Added new themes

1.1.0 (01/19/2024)

• Added more languages

1.0.0 (01/18/2024)

• Added new options and callbacks
• Bugfixes

0.9.0 (01/17/2024)

• Added new options and callbacks
• Added new CSS variables

0.8.0 (01/17/2024)

• Added new options and callbacks
• The heat map layout is now fully responsive with mobile and tablet views.
• When exporting the map details, the type selected is now included in the filename (if types are available).

0.7.0 (01/15/2024)

• All “:root” variables now start with “–heat-js-“, which will prevent collisions with other libraries.

0.6.0 (01/14/2024)

• Added Trend types support
• The “More” and “Less” labels can now be clicked
• Renamed the “year” CSS class to “title-bar”
• Bugfix

0.5.0 (01/11/2024)

• The heat map can now export all data to a CSV file
• Added new options and methods.

0.4.0 (01/11/2024)

• Added new options and methods.