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

Category: Chart & Graph , Javascript | July 9, 2024
Author:williamtroup
Views Total:11 views
Official Page:Go to website
Last Update:July 9, 2024
License:MIT

Preview:

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

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
  • 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,
  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.",
  triggerRefresh: true
},

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.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.

You Might Be Interested In:


Leave a Reply