React Horizontal Heatmap Component for Activity Visualization

Description:

Horizontal Heatmap is a React component library that renders data as color-coded horizontal visualizations.

It allows you to display time-series data or activity levels using color-coded blocks with customizable color gradients and spacing controls.

Features

• 🎨 Color Customization: Define your own color gradient arrays to match brand guidelines or create distinct visual themes for different data types.
• 📏 Flexible Sizing: Adjust box dimensions and gap spacing through simple numeric props to fit layouts ranging from compact mobile views to expansive desktop displays.
• 🔢 Automatic Scaling: The component calculates maximum values from your dataset and distributes colors proportionally across the range.
• ⏱️ Tooltip Support: Each data point can include timestamp information and associated items with icons, labels, and clickable links for detailed context.

See It In Action

Use Cases

• System Health Monitoring: Track server uptime, API response times, or database performance across hourly or daily intervals, with color intensity indicating system load or error rates.
• User Activity Dashboards: Visualize engagement patterns showing when users log in, complete tasks, or interact with features throughout a day or week.
• Content Publishing Calendars: Display article publication frequency, social media post timing, or content update schedules where each box represents a time block and color depth shows activity volume.
• Resource Utilization Tracking: Monitor CPU usage, memory consumption, or bandwidth allocation over time with gradient colors representing percentage thresholds.

4. How to Use It

1. Install the package using your preferred package manager.

# Yarn
$ yarn add react-horizontal-heatmap
# NPM
$ npm install react-horizontal-heatmap
# PNPM
$ pnpm install react-horizontal-heatmap

2. Import the HorizontalHeatmap component into your React file.

import { HorizontalHeatmap } from 'react-horizontal-heatmap';

3. Prepare your data as an array of objects. Each object requires a value property containing the numeric data point, a time property for timestamp information, and an optional items array for tooltip content:

const activityData = [
  {
    value: 5,
    time: '2025-11-19 09:00',
    items: [
      { icon: <AlertIcon />, text: 'System Alert', link: '/alerts/1' },
      { icon: <UserIcon />, text: 'User Login', link: '/users/42' }
    ]
  },
  {
    value: 0,
    time: '2025-11-19 10:00',
    items: []
  },
  {
    value: 3,
    time: '2025-11-19 11:00',
    items: [
      { icon: <CheckIcon />, text: 'Task Completed', link: '/tasks/18' }
    ]
  }
];

4. Render the component by passing your data through the data prop. The component accepts additional props for visual customization:

function Dashboard() {
  return (
    <div>
      <h2>Server Activity</h2>
      <HorizontalHeatmap 
        data={activityData}
        boxSize={25}
        gap={4}
      />
    </div>
  );
}

5. Customize the color scheme by passing an array of hex color codes to the colors prop. The array should progress from lightest to darkest:

<HorizontalHeatmap 
  data={activityData}
  colors={['#fef3c7', '#fde68a', '#fbbf24', '#f59e0b', '#d97706']}
  boxSize={20}
  gap={3}
/>

6. Override the automatic maximum value calculation when you need consistent scaling across multiple heatmaps. Set the maxValue prop to establish a fixed ceiling:

<HorizontalHeatmap 
  data={activityData}
  maxValue={10}
  colors={['#dbeafe', '#93c5fd', '#3b82f6', '#1d4ed8']}
/>

The component maps your data values to colors using equal distribution across the provided gradient. A value of 0 receives the first color, while values at or above maxValue receive the final color. Intermediate values interpolate between gradient steps based on their position in the range.

7. All available props with default values.

• data (required): Array of objects containing visualization data. Each object must include a value number representing the data point magnitude, a time string for timestamp display, and an items array holding tooltip content with optional icon, text, and link properties.
• maxValue: Number defining the upper bound for color scaling calculations. Defaults to the maximum value found in the data array. Set this explicitly when comparing multiple heatmaps that need consistent color mapping.
• colors: Array of hex color strings defining the gradient progression. Defaults to cyan-based palette ["#e0f7fa", "#80deea", "#26c6da", "#00acc1", "#006064"]. Provide custom colors to match design systems or create semantic color coding.
• boxSize: Number specifying both width and height dimensions of each heatmap square in pixels. Defaults to 20. Adjust based on available space and desired visual prominence.
• gap: Number controlling the spacing between adjacent boxes in pixels. Defaults to 2. Increase for more visual separation or decrease for denser layouts.

Related Resources

• 9 Best Github Style Calendar Heatmap Plugins In JavaScript

FAQs

Q: How do I handle empty or missing data points?
A: Set the value property to 0 for time slots with no activity. The component renders these boxes using the first color in your gradient array, creating a visual distinction from active periods.

Q: Does the component support vertical orientation?
A: No, this library focuses exclusively on horizontal layouts. The design targets single-row timeline visualizations where horizontal space matches the natural reading direction for temporal data.

Q: What happens when my data array contains negative numbers?
A: The color scaling treats negative values as zero, applying the first gradient color. The component expects non-negative integers representing count or magnitude data rather than bidirectional metrics.