React Activity Heatmap

A simple and customizable leetcode-style activity heatmap component for React (Demo)

Installation

The package can be installed via npm:

npm install react-activity-heatmap --save

Or via yarn:

yarn add react-activity-heatmap

This package provides a simple and reusable React component to visualize activity data over time in a calendar-style heatmap. It allows you to display daily activity intensity using colored squares, similar to Leetcode’s contribution graph. You can easily customize the start and end dates, color scales, and activity data, making it suitable for dashboards, habit trackers, or any app that needs a compact overview of activity trends.

import React from "react";
import { ActivityHeatmapMonth } from "react-activity-heatmap";

const activities = [
  { date: new Date("2026-08-10"), count: 5, level: 2 },
  { date: new Date("2026-08-11"), count: 2, level: 1 },
  { date: new Date("2026-08-22"), count: 8, level: 3 },
  // add more activity objects here
];

export const ActivityHeatmap = () => {
  const months = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
  const year = new Date().getFullYear();

  return (
    <div style={{ display: "flex", gap: "0.5rem" }}>
      {months.map((m) => (
        <ActivityHeatmapMonth
          key={`${m}-${year}`}
          activities={activities}
          month={m}
          year={year}
          cellStyle={{ borderRadius: "0.2rem" }}
          monthNameStyle={{ fontWeight: "semibold" }}
          tooltipStyle={{ border: "1px solid #e0f2fe" }}
          customCellColors={{ level1: "#047857", level2: "#059669", level3: "#10b981", level4: "#34d399" }}
          monthNameFormat={"long"}
          onCellClick={(cell) => alert(`Clicked on cell with ${cell.count} activities.`)}
        />
      ))}
    </div>
  );
};

Props

Prop	Type	Required	Description
activities	HeatmapActivity[]	✅	Array of activity objects used to render the heatmap cells.
month	number	✅	Month to display (1–12).
year	number	✅	Year to display for the given month.
hideMonthName	boolean	❌	Hides the month name header when set to true.
hideTooltip	boolean	❌	Disables the tooltip entirely when set to true.
cellStyle	React.CSSProperties	❌	Inline styles applied to each heatmap cell.
monthNameStyle	React.CSSProperties	❌	Inline styles applied to the month name label.
tooltipStyle	React.CSSProperties	❌	Inline styles applied to the tooltip container.
customTooltipContent	(activity: HeatmapActivity) => React.ReactNode	❌	Custom renderer for tooltip content based on the activity data.
customCellColors	Partial<CellColors>	❌	Overrides default cell colors. Level 0 represents no activity; higher levels map to increasing activity intensity.
onCellClick	(activity: HeatmapActivity, event: React.MouseEvent<HTMLDivElement>) => void	❌	Callback fired when a heatmap cell is clicked.
monthNameFormat	"short" / "long" / ((date: Date) => string)	❌	Controls how the month name is formatted. Can be a preset or a custom formatter.
locale	string	❌	Locale used for month name formatting (for example: en-US, de-DE).
ariaLabel	string	❌	Accessible label for the heatmap container.
cellAriaLabel	(activity: HeatmapActivity) => string	❌	Generates an accessible label for individual heatmap cells.

Types

export type HeatmapActivity = {
  date: Date;
  count: number;
  level: number;
};

export type HeatmapCell = HeatmapActivity | "invisible";

export type CellColors = {
  level0: string;
  level1: string;
  level2: string;
  level3: string;
  level4: string;
};

Contributing

This package is open source, contributions are welcome. You can find the project at https://github.com/stefan5441/react-activity-heatmap.

Compatibility

This package supports the following React versions:

• React: >=16.8.0 <20.0.0
• React DOM: >=16.8.0 <20.0.0

Requires React 16.8 or later due to usage of hooks.

License

This project is licensed under the MIT License.