React Calendar Heatmap

@riishabh/react-calender-heatmap is a lightweight React component that renders a contribution-style calendar heatmap. It ships with sensible defaults, supports custom day states, and now works seamlessly in both React 18 and React 19 applications.

Highlights

• ✅ React 18 & 19 support with strict TypeScript typings
• 🧩 Plug-and-play component — no context or provider setup required
• 🎨 Customizable color palette for different attendance or productivity states
• 🧪 Storybook & Testing Library integration for rapid UI iteration

Installation

npm install @riishabh/react-calender-heatmap
# or
yarn add @riishabh/react-calender-heatmap
# or
pnpm add @riishabh/react-calender-heatmap

Peer dependencies

• react: ^18.2.0 || ^19.0.0
• react-dom: match your React version

Quick Start

import { TileChart } from '@riishabh/react-calender-heatmap';

const data = [
  { date: '2024-01-01', status: 'success' },
  { date: '2024-01-02', status: 'warning' },
  { date: '2024-01-03', status: 'holiday' },
];

export function AttendanceHeatmap() {
  return (
    <TileChart
      data={data}
      range={6}
      tileText="Day"
      onTileHover={(label, status) => {
        if (status) {
          console.log(`${label} → ${status}`);
        }
      }}
    />
  );
}

Importing the package automatically injects the default stylesheet, so the heatmap is ready to render without additional configuration.

Data shape

Each entry in the data array corresponds to a day.

type TileState =
  | 'success'
  | 'warning'
  | 'alert'
  | 'holiday'
  | 'weekend'
  | 'fullDayLeave'
  | 'halfDayLeave';

interface TileDataPoint {
  date: string;   // any ISO-8601 string parsable by new Date()
  status?: TileState;
}

Component props

Prop	Type	Default	Description
data	TileDataPoint[]	—	Source data for the heatmap. Dates should be parseable by the browser's Date constructor.
range	3 | 6 | 12	6	Number of months (backwards from the current month) to render.
onTileHover	(label: string, status?: TileState) => void	—	Callback fired after a tile has been hovered long enough for the tooltip to appear. Empty string clears.
tileText	string	—	Optional static string shown in the tooltip instead of the generated date string.

Visual states

Use one of the built-in status values to map data to colors. Override the classes below to match your design system.

Status	Class	Default styling (excerpt)
success	.bg-success	green background, subtle border
warning	.bg-warning	amber background
alert	.bg-alert	red background
holiday	.bg-holiday	blue background
weekend	.bg-weekend	lilac background
fullDayLeave	.bg-fullDayLeave	burnt orange background
halfDayLeave	.bg-halfDayLeave	magenta background
unset	.bg-default	neutral gray background

Customizing the palette

Create a global stylesheet (or use CSS modules) to override the classes:

:root {
  --heatmap-success: #00a86b;
}

.bg-success {
  background-color: var(--heatmap-success);
  border-color: rgba(0, 168, 107, 0.45);
}

Because the component injects its CSS at runtime, make sure your overrides load after the component (for example, in your app-level stylesheet).

Tooltip & interactions

Tile hover events emit a human-friendly label (e.g. 3rd Jan 24) and the resolved status. Use this to show additional UI (like side panels or analytics) or to hook into analytics events.

<TileChart
  data={data}
  onTileHover={(label, status) => track('heatmap-hover', { label, status })} 
/>

TypeScript support

All exports ship with .d.ts files generated from the source TypeScript. If you need to narrow the status union for your own domain, extend the provided TileChartProps:

import type { TileChartProps } from '@riishabh/react-calender-heatmap';

type CustomTileState = TileChartProps['data'][number]['status'] | 'remote';

Development & contributing

npm install        # install dependencies
npm run storybook  # launch interactive component docs at http://localhost:6006
npm run build      # create the production-ready bundles in /dist
npm test           # (optional) run Jest in watch mode

Feel free to open issues or pull requests on GitHub with feature ideas or fixes.

License

MIT © Rishabh Sharma