@zhongyao/heatmap

A flexible and customizable React heatmap component for displaying year-based contribution calendars, similar to GitHub's contribution graph.

Features

• Flexible Year Display: Show any year's calendar in a heatmap format
• Customizable Week Start: Choose between Sunday or Monday as the first day of the week
• Fully Customizable Rendering: Override default rendering for day cells, month labels, and weekday labels
• Responsive Sizing: Configure cell size and gaps to fit your design
• TypeScript Support: Full TypeScript definitions included
• Lightweight: Built with React and dayjs

Installation

npm install @zhongyao/heatmap

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "^16.18.0",
  "dayjs": "^1.11.19"
}

Basic Usage

import { Heatmap } from "@zhongyao/heatmap";

function App() {
  return <Heatmap year={2025} weekStartDay="sunday" />;
}

Props

HeatmapProps

| Prop | Type | Default | Description | | -------------------- | ----------------------------------------------- | ----------- | -------------------------------------------- | | year | number | 2025 | The year to display | | weekStartDay | 'sunday' \| 'monday' | 'sunday' | First day of the week | | cellSize | number | 16 | Base size of cells and labels in pixels | | gap | number | 4 | Spacing between cells and labels in pixels | | containerGap | number | 18 | Gap between weekday labels and the main grid | | className | string | '' | Additional className for the wrapper | | renderDay | (props: DayCellProps) => React.ReactNode | undefined | Custom day cell renderer | | renderMonth | (props: MonthLabelProps) => React.ReactNode | undefined | Custom month label renderer | | renderWeekday | (props: WeekdayLabelProps) => React.ReactNode | undefined | Custom weekday label renderer | | weekDayLabelLayout | 'left' \| 'center' \| 'right' | 'left' | Alignment of weekday labels | | weekDayLabelStyle | CSSProperties | undefined | Custom styles for weekday labels |

Custom Rendering

Custom Day Cell

The renderDay prop allows you to customize how each day cell is rendered. You receive a DayCellProps object:

interface DayCellProps {
  date: Dayjs | null; // Date object (null for empty placeholders)
  dayOfYear: number | null; // Day of year (1-366, null for placeholders)
  colIndex: number; // 0-indexed column
  rowIndex: number; // 0-indexed row (0-6)
  isEmpty: boolean; // True for year start/end placeholders
}

Example:

<Heatmap
  year={2025}
  renderDay={({ date, isEmpty }) => {
    if (isEmpty) return <div style={{ width: 16, height: 16 }} />;

    // Custom logic based on your data
    const contribution = getContributionCount(date);
    const intensity = Math.min(contribution / 10, 1);

    return (
      <div
        style={{
          width: 16,
          height: 16,
          backgroundColor: `rgba(0, 255, 0, ${intensity})`,
          borderRadius: 2,
        }}
        title={`${date.format("YYYY-MM-DD")}: ${contribution} contributions`}
      />
    );
  }}
/>

Custom Month Label

The renderMonth prop customizes month labels:

interface MonthLabelProps {
  index: number; // 0-indexed month (0-11)
  label: string; // Default label (e.g., "Jan")
  startCol: number; // 1-indexed starting column
  span: number; // Number of columns this month spans
}

Example:

<Heatmap
  year={2025}
  renderMonth={({ label, span }) => (
    <div
      style={{
        gridColumn: `span ${span}`,
        height: 16,
        display: "flex",
        alignItems: "center",
        fontWeight: "bold",
        fontSize: 14,
      }}
    >
      {label}
    </div>
  )}
/>

Custom Weekday Label

The renderWeekday prop customizes weekday labels:

interface WeekdayLabelProps {
  index: number; // 0-indexed weekday (0-6)
  label: string; // Default label (e.g., "Mon")
  layout?: "left" | "center" | "right"; // Label alignment
  style?: CSSProperties; // Custom styles
}

Example:

<Heatmap
  year={2025}
  weekDayLabelLayout="center"
  renderWeekday={({ label }) => (
    <div
      style={{
        height: 16,
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        fontWeight: 600,
        color: "#374151",
      }}
    >
      {label.charAt(0)} {/* Show only first letter */}
    </div>
  )}
/>

Advanced Example

Here's a complete example with custom styling and data:

import { Heatmap, DayCellProps } from "@zhongyao/heatmap";
import { Dayjs } from "dayjs";

// Your contribution data
const contributions: Record<string, number> = {
  "2025-01-15": 5,
  "2025-01-16": 12,
  "2025-02-01": 8,
  // ... more data
};

function ContributionHeatmap() {
  const renderDay = ({ date, isEmpty }: DayCellProps) => {
    if (isEmpty) {
      return <div style={{ width: 12, height: 12 }} />;
    }

    const dateKey = date!.format("YYYY-MM-DD");
    const count = contributions[dateKey] || 0;

    // Calculate color intensity
    const getColor = (count: number) => {
      if (count === 0) return "#ebedf0";
      if (count < 5) return "#9be9a8";
      if (count < 10) return "#40c463";
      if (count < 15) return "#30a14e";
      return "#216e39";
    };

    return (
      <div
        style={{
          width: 12,
          height: 12,
          backgroundColor: getColor(count),
          borderRadius: 2,
          cursor: "pointer",
        }}
        title={`${dateKey}: ${count} contributions`}
      />
    );
  };

  return (
    <Heatmap
      year={2025}
      weekStartDay="monday"
      cellSize={12}
      gap={3}
      renderDay={renderDay}
      className="my-heatmap"
    />
  );
}

Styling

The component uses Tailwind CSS classes by default, but you can fully customize styling through:

1. Props: Use cellSize, gap, containerGap for spacing
2. Custom Renderers: Full control over rendering via renderDay, renderMonth, renderWeekday
3. CSS Classes: Add custom classes via the className prop

License

MIT

Contributing

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