Categories: CSSScriptWeb Design

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

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.

Table of Contents

Toggle

How

Sponsored

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.chart.showToolTips: true
views.chart.useGradients: 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.statistics.showToolTips: true
views.statistics.useGradients: false
views.map.showMinimalDayNames: false
views.map.showMonthsInReverseOrder: false
views.map.showDayDateNumbers: false
views.map.showToolTips: true
views.chart.showLineDateNumbers: 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
views.days.showToolTips: true
views.days.useGradients: false
views.days.useDifferentBackgroundOpacities: true
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
title.showSectionText: true
title.showToolTips: true
description.text: null
description.url: null
description.urlTarget: ‘_blank’
guide.enabled: true
guide.colorRangeTogglesEnabled: true
guide.showLessAndMoreLabels: true
guide.showNumbersInGuide: false
guide.showToolTips: true
tooltip.delay: 750
tooltip.dayText: “{d}{o} {mmmm} {yyyy}”
colorRanges: [ { minimum: 10, cssClassName: ‘day-color-1’ } ]).
year: the current year
exportType: “csv”, “xml”, “txt”, “html”, “md”, “tsv”, or “json”
useLocalStorageForData: false
allowFileImports: true
yearsToHide: []
holidays: []
dataFetchDelay: 60000
showOnlyDataForYearsAvailable: false
showHolidaysInDayToolTips: false
resizable: false
startMonth: 0 for Jan
onDayClick: function(date, count, isHoliday){}
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, count, year){}
onDataFetch: function(element){}
onClear: function(element){}
onUpdate: function(element){}
onOptionsUpdate: function(option){}
onWeekDayClick: function(weekday, dayCount, year){}
onDayDblClick( date, count, isHoliday )
onWeekDayDblClick( dayNumber, dayCount, year )
onStatisticDblClick( colorRange, count )

<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: "*",
  observationMode: true,
  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 "json", also accepts "json", "xml", "md", "tsv", 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";
                          
  --heat-js-text-bold-weight: 400;
  --heat-js-title-bold-weight: 900;
  --heat-js-sub-title-bold-weight: 700;
  --heat-js-text-bold-weight-active: 900;

  // Colors
  --heat-js-color-black: #3b3a3a;
  --heat-js-color-white: #adbac7;
  --heat-js-color-snow-white: #F5F5F5;
  --heat-js-color-gray: #AAAAAA;
  --heat-js-color-light-gray: #BBBBBB;

  // Containers
  --heat-js-container-background-color: #22272e;
  --heat-js-container-border-color: #454c56;

  // Dialog
  --heat-js-dialog-background-color: var(--heat-js-container-background-color);
  --heat-js-dialog-border-color: var(--heat-js-container-border-color);
  --heat-js-dialog-text-color: var(--heat-js-color-white);

  // Year
  --heat-js-years-background-color: #11161e;
  --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-years-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);

  // ToolTip
  --heat-js-tooltip-background-color: var(--heat-js-years-background-color);
  --heat-js-tooltip-border-color: var(--heat-js-container-border-color);
  --heat-js-tooltip-text-color: var(--heat-js-color-white);

  // Holidays
  --heat-js-holiday-background-color: rgba( 210, 43, 43, 0.75 );
  --heat-js-holiday-border-color: rgba( 210, 43, 43, 0.5 );
  --heat-js-holiday-text-color: var(--heat-js-color-black);

  // 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.2rem;
  --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);

  // Views - Colors
  --heat-js-view-days-background-color: var(--heat-js-day-color-4-background-color);
  --heat-js-view-days-border-color: var(--heat-js-day-color-4-border-color);
  --heat-js-view-days-text-color: var(--heat-js-day-color-4-text-color);

  // 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);

  // CheckBox
  --heat-js-checkbox-background-color-checked: rgba( 80, 200, 120, 1 );
  --heat-js-checkbox-background-color: var(--heat-js-color-black);
  --heat-js-checkbox-border-color-checked: --heat-js-checkbox-background-color-checked;
  --heat-js-checkbox-border-color: var(--heat-js-color-white);

  // Panels
  --heat-js-panel-background-color: var(--heat-js-day-background-color);
  --heat-js-panel-border-color: var(--heat-js-container-border-color);

  // Borders
  --heat-js-border-control-radius: 0.25rem;
  --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;
  --heat-js-spacing-day-font-size: 0.6rem;
  --heat-js-left-border: 8px;

  // Transitions
  --heat-js-transition: all .3s;
  --heat-js-animation-length: 0.5s;

  // Scroll Bars
  --heat-js-scroll-bar-size: 4px;
  --heat-js-scroll-bar-thumb-color: #3b434e;
  --heat-js-scroll-bar-border-radius: 0.5rem;

}

Changelog:

v4.5.2 (11/30/2025)

UI improvements and fixes
Add new options

v4.5.1 (11/29/2025)

Update and improvement

v4.5.0 (11/27/2025)

Added support for custom year-month ranges! So instead of defaulting to Jan-Dec, you can now use something like Apr-Mar. The UI will now show the years when this is used.
Added support to export all data to HTML (.html).
Added support to export all data to Markdown (.md).
Added support to export all data to Tab Separated Values (.tsv).
Added support to import data from a Tab Separated Values file (.tsv).
When the binding option “exportOnlyDataBeingViewed” is set to true, only data that is visible (months and days) will be exported.
BREAKING: The binding option “exportOnlyYearBeingViewed” has been renamed to “exportOnlyDataBeingViewed”.
Updated the binding option called “exportType” to have a new default value of “json”.
Added a new binding option called “startMonth”, which states the first month in the year that should be displayed (allows an Apr-Mar view, and defaults to 0, for Jan).
Added a new binding option called “views.map.showToolTips”, which states if the tooltips should be shown (defaults to true).
Added a new binding option called “views.chart.showToolTips”, which states if the tooltips should be shown (defaults to true).
Added a new binding option called “views.days.showToolTips”, which states if the tooltips should be shown (defaults to true).
Added a new binding option called “views.statistics.showToolTips”, which states if the tooltips should be shown (defaults to true).
Added a new binding option called “views.title.showToolTips”, which states if the tooltips should be shown (defaults to true).
Added a new binding option called “views.guide.showToolTips”, which states if the tooltips should be shown (defaults to true).
Added a new binding option called “views.chart.useGradients”, which states if the bar lines should use a gradient fill (defaults to false).
Added a new binding option called “views.days.useGradients”, which states if the bar lines should use a gradient fill (defaults to false).
Added a new binding option called “views.statistics.useGradients”, which states if the bar lines should use a gradient fill (defaults to false).
Added a new binding custom trigger called “events.onDayDblClick”, which triggers when a day is double-clicked.
Added a new binding custom trigger called “events.onWeekDayDblClick”, which triggers when a weekday is double-clicked.
Added a new binding custom trigger called “events.onStatisticDblClick”, which triggers when a statistic is double-clicked.
The title bar buttons now use a fixed height and width.
The title bar buttons now align all content so it’s always central.
When the counts/day dates are shown in the display, they are aligned vertically in the center.
The side Y labels shown in the “Chart”, “Day”, and “Color Range” views are now always visible, even on mobile devices.
Increased the right margin used for the bars in the “Chart” view by 0.5px.
Fixed bugs.

v4.4.0 (11/24/2025)

Added a new binding option called “resizable”, which states if horizontal resizing is enabled (defaults to false).
Added a new configuration option called “observationMode”, which states if looking for new DOM elements with the Heat.js binding should be done automatically (defaults to true).
Each day shown in the Map view now has a new attribute called “data-heat-js-map-date”, which stores the date for that map day.
Each bar shown in the Chart view now has a new attribute called “data-heat-js-chart-date”, which stores the date for that chart day.
Each bar shown in the Days view now has a new attribute called “data-heat-js-day-number”, which stores the day number.
Each bar shown in the Color Ranges view now has a new attribute called “data-heat-js-statistics-color-range-name”, which stores the name of the Color Range (if stated).
Added a new CSS variable “–heat-js-default-width”, which states what the default width should be.
The label links (in the footer) now use a bottom border for the underline effect when hovered (which allows a smooth transition).

v4.3.2 (11/16/2025)

Updated all the NPM packages to the latest versions.
Added a new “year” parameter for the event “onStatisticClick”, which is now passed after the “rangeCount” parameter.
Fixed the out-of-date BindingOptionsEvents for event triggers used when clicking in areas.
The left border on the main display is now only shown on larger screens (giving a little more room on smaller/mobile screens).
Added a new CSS variable called “–heat-js-scroll-bar-border-radius” (defaults to 0.5rem), which states the border radius the scrollbars should use.
The CSS variable “–heat-js-day-size” now defaults to 1.2rem instead of 1.1rem, making the day boxes slightly larger.
Added a new binding option called “views.map.showDayDateNumbers”, which states if the date day numbers should be shown (defaults to false).
Added a new binding option called “views.chart.showLineDateNumbers”, which states if the date day numbers should be shown (defaults to false).

v4.3.2 (11/16/2025)

Updated all the NPM packages to the latest versions.
SCSS/CSS improvements (less code).
The tooltips in the default dark view are now easier to see against the background.
Added a new option called “title.showSectionText” (defaults to true), which states if the current section being shown should be displayed in the title text.
Added some more spacing around the configuration dialog check boxes.
Increased the size of the scrollbar to make it a bit easier to click.
Added a new “isHoliday” parameter for the event “onDayClick”, which is now passed after the “count” parameter.
Fixed missing data from the other test events.
Updated the JS language usage in the documentation and testing HTML files.
Added a new “year” parameter for the event “onWeekDayClick”, which is now passed after the “dayCount” parameter.
Added a new “count” parameter for the event “onStatisticClick”, which is now passed after the “colorRange” parameter.

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)

Customizable Event Calendar With Month/Year Selection – Color Calendar

A flexible, customizable, themeable event calendar & month/year picker component written in vanilla JavaScript. How to use it: 1. Install & import the Color Calendar as an ES module. # NPM $ npm i color-calendar import Calendar from 'color-calendar'; import 'color-calendar/dist/css/theme-basic.css'; import 'color-calendar/dist/css/theme-glass.css'; 2. Or directly load the JavaScript and…

October 6, 2025

In "CSSScript"

Vanilla JavaScript Gallery Lightbox with Touch Support – Obsidium

Obsidium is an accessible, mobile-friendly JavaScript lightbox library that displays your images and rich text in a gallery popup with zoom/navigation controls, smooth transitions, and thumbnail previews. Features: Zero Dependencies: Runs as a standalone library with no external requirements. Touch Support: Handles swipe gestures for navigation and closing on mobile…

December 5, 2025

In "CSSScript"

Real-Time Table Search Library Under 1KB – Searchable

Searchable is an ultra-lightweight vanilla JavaScript library that adds real-time search functionality to HTML tables. You just include the script, add a class to your table, and it works. Features: Tiny footprint: 1.46KB minified (824 bytes gzipped) means no bundle bloat. Auto-initialization: Add class="searchable" and the search button appears automatically.…

November 14, 2025

In "CSSScript"

rssfeeds-admin