React Heatmap Grid

An accessible, data-agnostic, and highly customizable heatmap component for React, built with TypeScript. Visualize your data in a clean grid layout, styled effortlessly with CSS variables.

✨ Features

• 🎨 Highly Customizable: Easily theme colors, cell sizes, gaps, and borders using CSS variables.
• 🔌 Data-Agnostic: Works with any data structure through simple accessor props (getX, getValue).
• ✅ Fully Typed: Built with TypeScript for a superior developer experience and type safety.
• 🦴 Skeleton Loader: Includes a <HeatmapSkeleton /> component for elegant loading states.
• ♿ Accessibility-Ready: Built with semantic HTML and ARIA attributes in mind.
• 📦 Lightweight: Minimal dependencies to keep your bundle size small.

🚀 Installation

Install the package and its peer dependencies using your favorite package manager.

npm install @botanicalcoder/react-heatmap-grid react react-dom

or

yarn add @botanicalcoder/react-heatmap-grid react react-dom

Usage

To get started, import the Heatmap component and its corresponding stylesheet. Then, provide your data and the required accessor props.

Basic Example

Here's a simple example of how to render a heatmap:

import React from 'react';
import { Heatmap } from '@botanicalcoder/react-heatmap-grid';
import '@botanicalcoder/react-heatmap-grid/styles.css';

// 1. Define your data type
type SalesData = {
  quarter: string; // Corresponds to an xLabel
  total: number; // The value to visualize
};

// 2. Prepare your data, organized by rows
const salesByRegion = [
  {
    y: 'North America', // Corresponds to a yLabel
    data: [
      { quarter: 'Q1', total: 15 },
      { quarter: 'Q2', total: 25 },
      { quarter: 'Q3', total: 18 },
      { quarter: 'Q4', total: 30 },
    ],
  },
  {
    y: 'Europe',
    data: [
      { quarter: 'Q1', total: 8 },
      { quarter: 'Q2', total: 12 },
      { quarter: 'Q3', total: 22 },
      { quarter: 'Q4', total: 19 },
    ],
  },
];

const App = () => {
  return (
    <Heatmap<SalesData>
      // 3. Define the labels for your axes
      xLabels={['Q1', 'Q2', 'Q3', 'Q4']}
      yLabels={['North America', 'Europe']}
      // 4. Pass the data
      rows={salesByRegion}
      // 5. Provide accessor functions
      getX={(item) => item.quarter}
      getValue={(item) => item.total}
    />
  );
};

export default App;

Loading State with Skeleton

Use the HeatmapSkeleton component to provide a better user experience while your data is loading.

import { HeatmapSkeleton } from '@botanicalcoder/react-heatmap-grid';
import '@botanicalcoder/react-heatmap-grid/styles.css';

function MyComponent() {
  const [loading, setLoading] = React.useState(true);
  // ... fetch data

  if (loading) {
    return <HeatmapSkeleton />;
  }

  return <Heatmap /* ...props */ />;
}

Component Props (API)

The <Heatmap /> component is highly configurable through its props.

| Prop | Type | Default | Description | | -------------------- | --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------- | | xLabels | Array<string \| number> | [0, 1, ..., 23] | Labels for the columns (X-axis). | | yLabels | string[] | ['Mon', ..., 'Sun'] | Labels for the rows (Y-axis). Defines the row order. | | rows | Array<{ y: string; data: T[] }> | undefined | Your dataset, structured as an array of row objects. (Preferred) | | getX | (item: T) => string \| number | - | Required. A function to extract the X-value from a data item. | | getValue | (item: T) => number | - | Required. A function to extract the numerical value from a data item. | | colorRange | object | { empty, low, medium, high } | An object of hex codes to define the color palette. | | thresholds | object | { low: 0, medium: 10, high: 20 } | Numerical thresholds for applying the low, medium, and high colors. | | cellSizePx | number | 24 | The size (width and height) of each cell in pixels. | | cellGapPx | number | 2 | The gap between cells in pixels. | | cellBorderRadiusPx | number | 4 | The border radius for each cell. | | caption | string | 'Heatmap' | A caption displayed above the heatmap. | | showCaption | boolean | true | Toggles the visibility of the caption. | | getTitle | (args) => string | A default formatted string | A function to generate the title attribute (tooltip) for each cell. | | classNames | object | {} | An object to override the default CSS class names for different elements. |

🛠️ Technologies Used

| Technology | Link | | ---------- | ------------------------------------------------------------------ | | React | https://react.dev/ | | TypeScript | https://www.typescriptlang.org/ | | tsup | https://tsup.egoist.dev/ | | Vite | https://vitejs.dev/ |

🤝 Contributing

Contributions are always welcome! If you have suggestions for improvements or want to report a bug, please feel free to open an issue or submit a pull request.

• Fork the repository on GitHub.
• Clone your fork: git clone https://github.com/botanicalcoder/react-heatmap-grid.git
• Create a new branch: git checkout -b feature/your-feature-name
• Make your changes and commit them: git commit -m 'Add some feature'
• Push to the branch: git push origin feature/your-feature-name
• Open a pull request.

📄 License

This project is licensed under the MIT License.

👤 Author

Botanicalcoder

• Email: [email protected]
• LinkedIn: Chibueze E. Okocha
• Twitter: @chisageo