React Github Heatmap

Table of Contents

• Features
• Installation
• Getting Started
• Customizing Colors
• API

Features

• ✅ Fully customizable colors
• ✅ Fast and lightweight for smooth performance
• ✅ Interactive & responsive for modern UI needs
• ✅ Easy integration with React projects

Installation

With pnpm

pnpm add @ahmaddzidnii/react-github-heatmap

With NPM

npm install @ahmaddzidnii/react-github-heatmap

With Yarn

yarn add @ahmaddzidnii/react-github-heatmap

Getting Started

First, to perform testing, we create helper functions generateDataByDateRange() and get52WeeksDateRange to generate the data in ./helpers.ts.

export const generateDataByDateRange = (startDate: string, endDate: string) => {
  const start = new Date(startDate);
  const end = new Date(endDate);
  const generatedData = [];

  for (let d = new Date(start); d <= end; d.setDate(d.getDate() + 1)) {
    const year = d.getFullYear();
    const month = String(d.getMonth() + 1).padStart(2, "0");
    const day = String(d.getDate()).padStart(2, "0");

    generatedData.push({
      date: `${year}-${month}-${day}`,
      contributions: Math.floor(Math.random() * 51), // Random number between 0-100
    });
  }

  return generatedData;
};

export const get52WeeksDateRange = ({ endDate }: { endDate: Date }) => {
  // Go back approximately one year (52 weeks)
  let startDate = new Date(endDate);
  startDate.setDate(endDate.getDate() - 52 * 7);

  // Adjust to the nearest Sunday if not already a Sunday
  while (startDate.getDay() !== 0) {
    startDate.setDate(startDate.getDate() - 1);
  }

  const strStartDate = `${startDate.getFullYear()}-${String(startDate.getMonth() + 1).padStart(
    2,
    "0"
  )}-${String(startDate.getDate()).padStart(2, "0")}`;
  const strEndDate = `${endDate.getFullYear()}-${String(endDate.getMonth() + 1).padStart(
    2,
    "0"
  )}-${String(endDate.getDate()).padStart(2, "0")}`;

  return { startDate: strStartDate, endDate: strEndDate };
};

Next, create your React component, for example in App.tsx

import { ReactGithubHeatmap } from "@ahmaddzidnii/react-github-heatmap";
import { get52WeeksDateRange, generateDataByDateRange } from "./helpers";

const App = () => {
  const { endDate, startDate } = get52WeeksDateRange({
    endDate: new Date(),
  });
  const data = generateDataByDateRange(startDate, endDate);
  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        height: "100vh",
      }}
    >
      <ReactGithubHeatmap
        data={data}
        tooltipContent={(t) => {
          if (!t.contributions) {
            return `No contributions on ${t.date}`;
          }

          return `${t.contributions} contributions on ${t.date}`;
        }}
        tooltipOptions={{
          place: "top",
        }}
      />
    </div>
  );
};

Customizing Colors

You can customize the colors of the heatmap by adding your own CSS classes. For example, you can define a custom class in your CSS file and apply it to the heatmap.

Example

1. Create a CSS file (e.g., styles.css) and define your custom styles:

[data-level="0"] {
  background-color: #ebedf0 !important;
}

[data-level="1"] {
  background-color: #9be9a8 !important;
}

[data-level="2"] {
  background-color: #40c463 !important;
}

[data-level="3"] {
  background-color: #30a14e !important;
}

[data-level="4"] {
  background-color: #216e39 !important;
}

2. Import the CSS file into your React component:

import "./styles.css";
import { ReactGithubHeatmap } from "@ahmaddzidnii/react-github-heatmap";
import { get52WeeksDateRange, generateDataByDateRange } from "./helpers";

const App = () => {
  const { endDate, startDate } = get52WeeksDateRange({
    endDate: new Date(),
  });
  const data = generateDataByDateRange(startDate, endDate);

  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        height: "100vh",
      }}
    >
      <ReactGithubHeatmap
        data={data}
        tooltipContent={(t) => {
          if (!t.contributions) {
            return `No contributions on ${t.date}`;
          }

          return `${t.contributions} contributions on ${t.date}`;
        }}
        tooltipOptions={{
          place: "top",
        }}
      />
    </div>
  );
};

3. Run your application, and the heatmap will now use the custom styles defined in your CSS file.

API

| Prop | Type | Description | | -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | data | arrayofobj | Array of objects containing date and contributions for the heatmap. | | startDate | string | The start date for the heatmap data range in YYYY-MM-DD format. | | endDate | string | The end date for the heatmap data range in YYYY-MM-DD format. | | tooltipContent | function | Function to customize the content of the tooltip displayed on hover. | | tooltipOptions | object | Object to configure tooltip behavior and appearance. See React Tooltip Docs |