Heatmap Component

A flexible, customizable calendar heatmap component for React, inspired by GitHub's contribution graph.

Features

• 📅 Flexible Date Ranges - Display any date range with automatic week alignment
• 🎨 Customizable Colors - Define your own color scales and thresholds
• 🌓 Light/Dark Mode - Built-in theme support
• 📱 Responsive - Horizontal scrolling for large date ranges
• 🎯 Interactive - Click and hover handlers for cells
• 🔧 Highly Customizable - Override styles and classes for any element
• 📊 Smart Labels - Automatic month label positioning with overlap prevention
• 🌍 Week Start Options - Start weeks on any day (Sunday, Monday, etc.)
• 💡 TypeScript - Full TypeScript support with exported types

Installation

# If publishing as npm package
npm install @your-org/react-heatmap

# Or copy the component files to your project
cp -r components/common/Heatmap /your-project/components/

Basic Usage

import { Heatmap } from '@/components/common/Heatmap';

function MyComponent() {
  const data = [
    { date: '2024-01-01', count: 5 },
    { date: '2024-01-02', count: 12 },
    { date: '2024-01-03', count: 0 },
    // ... more data
  ];

  return (
    <Heatmap
      values={data}
      startDate="2024-01-01"
      endDate="2024-12-31"
    />
  );
}

Props API

Data Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | values | HeatmapValue[] | ✅ | - | Array of { date: string, count: number } objects | | startDate | string | ✅ | - | Start date in ISO format (YYYY-MM-DD) | | endDate | string | ✅ | - | End date in ISO format (YYYY-MM-DD) |

Display Options

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | showMonthLabels | boolean | ❌ | true | Show month labels | | showWeekdayLabels | boolean | ❌ | true | Show weekday labels | | monthPlacement | 'top' \| 'bottom' | ❌ | 'top' | Position of month labels | | weekStart | 0-6 | ❌ | 0 | Starting day of week (0=Sunday, 1=Monday, etc.) | | showLegend | boolean | ❌ | true | Show color legend | | emptyMessage | string | ❌ | 'No data available...' | Message shown when no data |

Sizing Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | cellSize | number | ❌ | 12 | Size of each cell in pixels | | cellGap | number | ❌ | 3 | Gap between cells in pixels | | cellRadius | number | ❌ | 2 | Border radius for cells in pixels |

Color Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | colorScale | ColorScale | ❌ | GitHub greens | Color thresholds object | | surface | 'light' \| 'dark' | ❌ | 'light' | Theme mode |

Styling Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | className | string | ❌ | - | Custom class for container | | classNames | HeatmapClassNames | ❌ | - | Override classes for elements | | style | CSSProperties | ❌ | - | Inline styles for container | | styles | HeatmapStyles | ❌ | - | Override styles for elements |

Interaction Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | tooltipFormatter | (value) => string | ❌ | Default formatter | Custom tooltip content | | onClick | (value, event) => void | ❌ | - | Cell click handler | | onMouseOver | (value, event) => void | ❌ | - | Cell hover handler | | onMouseLeave | (value, event) => void | ❌ | - | Cell leave handler |

Label Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | monthLabels | string[] | ❌ | ['Jan', 'Feb', ...] | Custom month labels | | weekdayLabels | string[] | ❌ | ['Sun', 'Mon', ...] | Custom weekday labels |

Advanced Examples

Custom Color Scale

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  colorScale={{
    0: '#f0f0f0',
    5: '#c6e48b',
    10: '#7bc96f',
    15: '#239a3b',
    20: '#196127',
  }}
/>

Week Starting on Monday

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  weekStart={1}
  weekdayLabels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
/>

Custom Tooltip

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  tooltipFormatter={(value) =>
    `${value.count} contributions on ${new Date(value.date).toLocaleDateString()}`
  }
/>

Dark Mode

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  surface="dark"
/>

Month Labels at Bottom

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  monthPlacement="bottom"
/>

Minimal Heatmap (No Labels or Legend)

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  showMonthLabels={false}
  showWeekdayLabels={false}
  showLegend={false}
/>

TypeScript Types

interface HeatmapValue {
  date: string;  // ISO format: YYYY-MM-DD
  count: number;
}

interface ColorScale {
  [threshold: number]: string;
}

type TooltipFormatter = (value: HeatmapValue) => string;
type CellClickHandler = (value: HeatmapValue, event: MouseEvent<HTMLDivElement>) => void;
type CellHoverHandler = (value: HeatmapValue | null, event: MouseEvent<HTMLDivElement>) => void;

Customization Guide

Override Individual Element Classes

The classNames prop allows you to override classes for specific elements:

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  classNames={{
    container: 'my-container',
    cell: 'my-cell',
    cellActive: 'my-active-cell',
    cellEmpty: 'my-empty-cell',
    tooltip: 'my-tooltip',
    legend: 'my-legend',
    monthLabel: 'my-month-label',
    weekdayLabel: 'my-weekday-label',
  }}
/>

Override Individual Element Styles

The styles prop allows you to override inline styles:

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  styles={{
    container: { backgroundColor: '#f5f5f5', padding: '20px' },
    cell: { borderRadius: '4px' },
    tooltip: { fontSize: '14px', padding: '8px 12px' },
    legend: { justifyContent: 'center' },
  }}
/>

Default Color Scale

The default color scale uses GitHub-style greens:

{
  0: '#ebedf0',   // Empty/no activity
  2: '#9be9a8',   // Low activity
  5: '#40c463',   // Medium activity
  10: '#30a14e',  // High activity
  20: '#216e39',  // Very high activity
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Performance Considerations

• The component efficiently handles large date ranges (multiple years)
• Uses useMemo for expensive calculations
• Horizontal scrolling for wide heatmaps
• Optimized re-renders with proper dependency arrays

Accessibility

• Semantic HTML structure
• Keyboard navigation support (when click handlers are provided)
• ARIA labels can be added via classNames and custom attributes
• High contrast mode compatible

License

MIT

Credits

Inspired by:

• GitHub's contribution graph
• react-calendar-heatmap
• @uiw/react-heat-map

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

v1.0.0

• Initial release
• Full TypeScript support
• Customizable color scales
• Light/Dark mode
• Interactive tooltips
• Click and hover handlers
• Smart month label positioning
• Week start customization

Click Handler

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  onClick={(value, event) => {
    console.log(`Clicked on ${value.date} with ${value.count} activities`);
  }}
/>

Custom Styling

<Heatmap
  values={data}
  startDate="2024-01-01"
  endDate="2024-12-31"
  className="my-custom-heatmap"
  classNames={{
    cell: 'custom-cell',
    tooltip: 'custom-tooltip',
  }}
  styles={{
    container: { padding: '24px' },
    cell: { borderRadius: '50%' },
  }}
/>