Analytics office with heatmap displays on a wall screen and a red cat on a desk chair

Heat.js: Turn Your Date Data Into Beautiful Heatmaps, Charts, and More

The Orange Cat
The Orange Cat

If you have ever looked at a GitHub contribution graph and thought, "I want that for my own data," you are not alone. Those little colored squares are surprisingly effective at conveying patterns over time. Heat.js is a library built entirely around that idea, except it does not stop at calendar grids. It gives you six different visualization views, 31 ready-made themes, support for 60 languages, and the ability to export your data in nine formats. All without pulling in a single runtime dependency.

jheat.js is a TypeScript-first library that renders interactive heatmaps, line charts, bar charts, and statistical breakdowns from date-based data. It works with vanilla JavaScript, React, Angular, and Vue. Whether you are tracking user logins, deployment frequency, or how many cups of coffee your team consumes per day, Heat.js turns that data into something you can actually read at a glance.

Six Ways to See Your Data

Heat.js ships with six distinct visualization views, all powered by the same underlying dataset:

  • Map renders a GitHub-style calendar grid where each cell represents a day, colored by intensity.
  • Line draws trend lines across your data, added in the v5.0.0 release.
  • Chart provides a bar chart breakdown.
  • Days shows a day-level summary.
  • Months presents monthly aggregates as a bar graph, also new in v5.0.0.
  • Color Ranges displays statistical breakdowns organized by color intensity buckets.

Users can switch between views interactively, and each view supports tooltips with counts and percentage differences from the previous year. That year-over-year comparison is baked in, so trend spotting requires no extra work on your part.

Getting Started

Install from npm:

npm install jheat.js

Or with yarn:

yarn add jheat.js

You can also load it from a CDN if you prefer script tags over bundlers.

Wiring Up Your First Heatmap

The Declarative Approach

Heat.js uses a data-attribute binding pattern that keeps your markup clean. You attach configuration directly to a DOM element, and the library handles the rest:

const container = document.getElementById("activity-map");

const options = {
  views: {
    map: { showDayNames: true },
    chart: { enabled: true },
  },
  title: {
    text: "Deployment Frequency",
  },
  colorRanges: [
    { minimum: 0, cssClassName: "heat-js-color-0" },
    { minimum: 1, cssClassName: "heat-js-color-1" },
    { minimum: 5, cssClassName: "heat-js-color-2" },
    { minimum: 10, cssClassName: "heat-js-color-3" },
    { minimum: 20, cssClassName: "heat-js-color-4" },
  ],
};

The color ranges define how values map to visual intensity. Each range specifies a minimum threshold and a CSS class, giving you full control over the palette through your stylesheet.

Adding Data Points

Once the heatmap is rendered, you feed it data using the public API:

// Add a single date with a count
$heat.addDate("activity-map", new Date(2026, 2, 1), 7);
$heat.addDate("activity-map", new Date(2026, 2, 2), 3);
$heat.addDate("activity-map", new Date(2026, 2, 3), 15);

// Remove a date if needed
$heat.removeDate("activity-map", new Date(2026, 2, 1));

Each call specifies the element ID, a date, and a numeric value. The heatmap updates immediately, recoloring cells according to your defined ranges.

Picking a Theme

With 31 CSS themes available, you can match Heat.js to almost any design system. Themes come in both light and dark variants, so supporting dark mode means swapping a single CSS file rather than rebuilding your configuration. The library renders all UI elements with pure CSS, which means no inline SVG or canvas elements to wrestle with during styling.

Going Deeper

Data Import and Export

One of the more unusual features of Heat.js is its built-in import and export system. Most visualization libraries leave serialization to you. Heat.js handles it natively in nine export formats:

// Export formats: CSV, JSON, XML, TXT, HTML, Markdown, TSV, YAML, TOML
// Import formats: JSON, TXT, CSV, YAML, TOML, Markdown, TSV

The library includes export and import dialog UIs out of the box, so end users can download their data or load a previously saved dataset without you building any additional interface. This is particularly useful for dashboards where non-technical users need to grab a snapshot of the data.

Multi-Year Comparison

Heat.js supports year-over-year analysis with percentage change calculations built into the tooltip system. When a user hovers over a cell, they see not just the count for that day but also how it compares to the same day in the previous year. You can enable trend identification and separation for multi-dataset analysis, which is useful when you want to overlay different metrics on the same calendar.

const options = {
  views: {
    map: {
      showDayNames: true,
      showYearlyStatistics: true,
    },
    line: {
      enabled: true,
      showZooming: true,
    },
  },
  title: {
    text: "Commits per Day",
    showYearSelector: true,
  },
};

The showYearSelector option adds navigation controls so users can flip between years, while showYearlyStatistics displays aggregate numbers for each year. The line view supports zooming, which helps when you need to drill into a specific quarter or month.

Speaking 60 Languages

Internationalization is rarely a headline feature for chart libraries, but Heat.js ships with 60 built-in language translations. Day names, month names, tooltips, and UI labels all adapt based on the configured locale. If your application serves a global audience, this saves you from maintaining your own translation layer for the visualization component.

const options = {
  title: {
    text: "User Activity",
  },
};

// Heat.js will use the configured language for all UI text,
// including day names, month abbreviations, and tooltip labels

You can also provide custom text overrides for any string in the library, so mixing and matching is straightforward when the built-in translations do not quite match your product's terminology.

When Heat.js Fits

Heat.js occupies a specific niche: date-based activity visualization with multiple view types and zero external dependencies. If you need a GitHub-style contribution graph with the option to flip into line charts or bar charts without adding another library, it handles that well. The built-in theming, i18n, and data export features mean less integration work compared to assembling those capabilities from separate packages.

For spatial or geographic heatmaps, you will want a different tool entirely. For general-purpose charting with dozens of chart types, a larger library like ApexCharts covers more ground. But for the specific job of turning date-stamped counts into readable visual patterns, Heat.js delivers a focused, dependency-free solution that ships ready to use in any framework you are already working with.