🎹 keyboard-heatmap

A beautiful, lightweight TypeScript package for tracking keyboard usage and generating stunning heatmap visualizations

🚀 Live Demo • 📖 Documentation • 💻 Examples • 🤝 Contributing

✨ Features

🎯 Minimal API

• Simple, intuitive interface
• Just 3 core functions
• Works out of the box

🔐 Privacy First

• No sensitive data stored
• Only key frequencies tracked
• Local processing only

⚛️ React Ready

• Built-in React hook
• Auto cleanup on unmount
• Real-time updates

🎨 Beautiful Visuals

• SVG heatmap generation
• Customizable colors
• Responsive design

🪶 Lightweight

• Zero dependencies
• < 50KB bundle size
• Tree-shakeable

📱 Cross Platform

• Works everywhere
• Desktop & mobile
• All modern browsers

🚀 Quick Start

Installation

npm install keyboard-heatmap

Basic Usage

import { createKeyboardTracker } from 'keyboard-heatmap';

// 🎯 Create and start tracking
const tracker = createKeyboardTracker();
tracker.startTracking();

// 📊 Get real-time data
const data = tracker.getHeatmapData();
console.log(`Total presses: ${data.totalPresses}`);

// 🛑 Stop and get final results
const finalData = tracker.stopTracking();

React Hook

import { useKeyboardHeatmap } from 'keyboard-heatmap';

function MyComponent() {
  const { data, isTracking, startTracking, stopTracking } = useKeyboardHeatmap({
    autoStart: true,
    updateInterval: 1000
  });

  return (
    <div>
      <h2>Keyboard Stats</h2>
      <p>Status: {isTracking ? '🟢 Tracking' : '🔴 Stopped'}</p>
      <p>Total Presses: {data?.totalPresses || 0}</p>
      
      <button onClick={startTracking} disabled={isTracking}>
        Start Tracking
      </button>
      <button onClick={stopTracking} disabled={!isTracking}>
        Stop Tracking
      </button>
    </div>
  );
}

Generate Beautiful Heatmaps

import { generateHeatmapSVG } from 'keyboard-heatmap';

const svgString = generateHeatmapSVG(data, {
  width: 800,
  height: 300,
  colorScale: ['#e3f2fd', '#1976d2'],
  showLabels: true
});

// Use in React
<div dangerouslySetInnerHTML={{ __html: svgString }} />

💡 Use Cases

| 📊 Analytics | 🎮 Gaming | 📚 Education | ♿ Accessibility | |:---:|:---:|:---:|:---:| | User behavior tracking | Hotkey optimization | Typing practice | Motor difficulty analysis | | Website analytics | Gaming performance | Speed training | Adaptive keyboards | | UX research | Macro analysis | Learning progress | Usage patterns |

📖 Documentation

Core API

createKeyboardTracker(options?)

Creates a new keyboard tracker instance.

const tracker = createKeyboardTracker({
  ignoreModifierKeys: false,  // Ignore Ctrl, Alt, Shift, etc.
  ignoreSpecialKeys: false,   // Ignore F1-F12, Escape, etc.
  caseSensitive: false        // Treat 'A' and 'a' as different
});

Tracker Methods

| Method | Description | Returns | |--------|-------------|---------| | startTracking() | Begin listening to keyboard events | void | | stopTracking() | Stop tracking and return final data | HeatmapData | | getHeatmapData() | Get current data without stopping | HeatmapData | | isTracking() | Check if currently tracking | boolean | | reset() | Clear all data and stop tracking | void |

React Hook

useKeyboardHeatmap(options?)

const {
  data,           // Current heatmap data
  isTracking,     // Whether tracking is active
  startTracking,  // Function to start tracking
  stopTracking,   // Function to stop tracking
  reset,          // Function to reset all data
  getCurrentData  // Function to get current data
} = useKeyboardHeatmap({
  autoStart: true,        // Start tracking on mount
  updateInterval: 1000,   // Update frequency in milliseconds
  onUpdate: (data) => {}, // Callback for data updates
  // ... other tracker options
});

Visualization

generateHeatmapSVG(data, options?)

const svg = generateHeatmapSVG(heatmapData, {
  width: 800,                    // SVG width
  height: 300,                   // SVG height
  colorScale: ['#fff', '#000'],  // [min color, max color]
  showLabels: true,              // Show key labels and counts
  minOpacity: 0.1,               // Minimum color intensity
  maxOpacity: 1.0                // Maximum color intensity
});

Data Structure

interface HeatmapData {
  frequencies: { [key: string]: number };  // Key press counts
  totalPresses: number;                    // Total number of key presses
  startTime: number;                       // Tracking start timestamp
  endTime?: number;                        // Tracking end timestamp
}

💻 Examples

Real-time Analytics Dashboard

import { createKeyboardTracker, generateHeatmapSVG } from 'keyboard-heatmap';

class KeyboardAnalytics {
  private tracker = createKeyboardTracker({
    ignoreModifierKeys: true
  });
  
  start() {
    this.tracker.startTracking();
    
    // Update dashboard every 5 seconds
    setInterval(() => {
      const data = this.tracker.getHeatmapData();
      this.updateDashboard(data);
    }, 5000);
  }
  
  updateDashboard(data: HeatmapData) {
    const svg = generateHeatmapSVG(data, {
      colorScale: ['#e8f5e8', '#2e7d32']
    });
    
    document.getElementById('heatmap')!.innerHTML = svg;
    document.getElementById('total')!.textContent = `${data.totalPresses}`;
  }
}

Typing Practice App

import React, { useState } from 'react';
import { useKeyboardHeatmap, generateHeatmapSVG } from 'keyboard-heatmap';

function TypingPractice() {
  const [showResults, setShowResults] = useState(false);
  
  const { data, isTracking, startTracking, stopTracking, reset } = useKeyboardHeatmap({
    ignoreSpecialKeys: true,
    updateInterval: 500,
    onUpdate: (data) => {
      // Calculate typing speed, accuracy, etc.
      const wpm = calculateWPM(data);
      updateStats(wpm);
    }
  });

  const handleFinish = () => {
    stopTracking();
    setShowResults(true);
  };

  return (
    <div className="typing-practice">
      <h1>⌨️ Typing Practice</h1>
      
      {!isTracking ? (
        <button onClick={startTracking}>Start Practice</button>
      ) : (
        <button onClick={handleFinish}>Finish</button>
      )}
      
      {showResults && (
        <div className="results">
          <h2>📊 Your Results</h2>
          <p>Total Key Presses: {data?.totalPresses}</p>
          <div dangerouslySetInnerHTML={{ 
            __html: generateHeatmapSVG(data!, {
              colorScale: ['#fff3cd', '#dc3545']
            })
          }} />
        </div>
      )}
    </div>
  );
}

Gaming Hotkey Analyzer

const gameTracker = createKeyboardTracker({
  caseSensitive: true,
  ignoreModifierKeys: false
});

// Track gaming session
gameTracker.startTracking();

// After gaming session
const gameData = gameTracker.stopTracking();
const topKeys = Object.entries(gameData.frequencies)
  .sort(([,a], [,b]) => b - a)
  .slice(0, 10);

console.log('🎮 Most used gaming keys:', topKeys);

🎨 Customization

Color Themes

const themes = {
  ocean: ['#e3f2fd', '#1976d2'],
  forest: ['#e8f5e8', '#2e7d32'],
  sunset: ['#fff3e0', '#f57c00'],
  cherry: ['#fce4ec', '#c2185b'],
  night: ['#263238', '#37474f']
};

const svg = generateHeatmapSVG(data, {
  colorScale: themes.ocean,
  showLabels: true
});

Custom Layouts

// Create your own keyboard layout
const customLayout = {
  width: 600,
  height: 200,
  keys: [
    { key: 'w', x: 50, y: 50, width: 40, height: 40 },
    { key: 'a', x: 10, y: 90, width: 40, height: 40 },
    { key: 's', x: 50, y: 90, width: 40, height: 40 },
    { key: 'd', x: 90, y: 90, width: 40, height: 40 },
    // ... more keys
  ]
};

🛠️ Browser Compatibility

| Browser | Version | Status | |---------|---------|--------| | Chrome | 60+ | ✅ Full Support | | Firefox | 55+ | ✅ Full Support | | Safari | 12+ | ✅ Full Support | | Edge | 79+ | ✅ Full Support | | Mobile | iOS 12+, Android 7+ | ✅ Full Support |

📦 Bundle Size

keyboard-heatmap
├── Core (gzipped): ~15KB
├── React Hook: ~5KB
├── Visualization: ~25KB
└── Total: ~45KB

Tree-shakeable: Import only what you need!

// Import only core functionality
import { createKeyboardTracker } from 'keyboard-heatmap/core';

// Import only React hook
import { useKeyboardHeatmap } from 'keyboard-heatmap/react';

// Import only visualization
import { generateHeatmapSVG } from 'keyboard-heatmap/visualization';

🔒 Privacy & Security

| 🔐 What We Track | ❌ What We DON'T Track | |:---:|:---:| | Key press frequencies | Actual text content | | Timing data | Personal information | | Key combinations | Passwords or sensitive data | | Session duration | Keystrokes outside your app |

• ✅ Local Processing: All data stays in your browser
• ✅ No Network Calls: Package doesn't make external requests
• ✅ Clean Cleanup: Proper event listener removal
• ✅ GDPR Compliant: No personal data collection

🚧 Roadmap

• [ ] 🌐 Multiple Language Support (QWERTZ, AZERTY, etc.)
• [ ] 📱 Mobile Optimizations (Touch-friendly heatmaps)
• [ ] 🎨 More Visualization Types (3D heatmaps, charts)
• [ ] 🔌 Framework Integrations (Vue, Angular, Svelte)
• [ ] 📊 Advanced Analytics (Typing speed, patterns)
• [ ] 🎮 Gaming Features (APM tracking, combo detection)
• [ ] ♿ Accessibility Tools (Screen reader support)
• [ ] 🌙 Dark Mode (Built-in dark theme)

🤝 Contributing

We love contributions! See our Contributing Guide for details.

Quick Start for Contributors

# Clone the repo
git clone https://github.com/yourusername/keyboard-heatmap.git
cd keyboard-heatmap

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Start development
npm run dev

Ways to Contribute

• 🐛 Bug Reports: Found a bug? Open an issue
• ✨ Feature Requests: Have an idea? Start a discussion
• 📖 Documentation: Improve our docs
• 🌍 Translations: Help us support more languages
• 💻 Code: Submit a pull request

👥 Community

• 📧 Email

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• 🎨 Inspired by heat map visualizations
• ⌨️ Built for the developer community
• 🌟 Thanks to all our contributors!

Made with ❤️ by Yusif Jabrayilov

Star ⭐ this repo if you find it useful!