Contribution Heatmap #

A high-performance, GitHub-like contribution heatmap widget for Flutter. This widget provides a visual representation of contribution data over time, similar to GitHub's contribution graph with proper i18n support and intelligent month separation.

[Contribution Heatmap minimal Screenshot]

✨ Features #

• 🚀 Ultra-High Performance: Custom RenderBox implementation with optimized rendering pipeline
• 👆 Interactive: Full tap support with proper hit testing and gesture handling
• 🎨 Fully Customizable: Colors, sizing, labels, and layout options
• 📅 Split Month View: Visual month separation with intelligent empty cell insertion
• 📊 Cell Date Display: NEW! Show day numbers inside contribution cells
• ♿ Accessibility Ready: Supports text scaling and high contrast modes
• 🌍 Internationalized: Locale-aware text rendering with customizable start weekdays
• 💾 Memory Efficient: Optimized data structures minimize memory usage and GC pressure
• 🔧 Smart Invalidation: Only recomputes what's needed, not on every frame

Visual Playground #

Visit our Visual Playground Website, play with ContributionHeatmap, copy the generated code, and seamlessly integrate it into your project. This is the quickest way! 🥰

[ContributionHeatmap Playground]

🚀 Quick Start #

Basic Usage #

import 'package:flutter/material.dart';
import 'package:contribution_heatmap/contribution_heatmap.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ContributionHeatmap(
      entries: [
        ContributionEntry(DateTime(2025, 11, 15), 5),
        ContributionEntry(DateTime(2025, 11, 16), 3),
        ContributionEntry(DateTime(2025, 11, 17), 8),
        // Add more entries...
      ],
      onCellTap: (date, value) {
        print('Tapped: $date with $value contributions');
      },
    );
  }
}

📊 Data Model #

ContributionEntry #

The data structure for contribution data:

class ContributionEntry {
  final DateTime date;  // Day-level precision
  final int count;      // Number of contributions (>= 0)
  const ContributionEntry(this.date, this.count);
}

🌍 i18n Support #

Currently, this package supports English (EN) and:

• 🇫🇷 French (fr-FR)
• 🇩🇪 German (de-DE)
• 🇪🇸 Spanish (es-ES)

More languages will be added soon.

Exemple de Contribution Heatmap en français (fr-FR) [Exemple de Contribution Heatmap en français (fr-FR)]

🎨 Customization Options #

Visual Properties #

Labels & Text #

Date & Layout #

Colors & Interaction #

⚡ Performance Characteristics #

Rendering Performance #

• O(1) cell value lookups during painting
• Custom RenderBox implementation bypasses widget rebuilds
• Smart invalidation - only recomputes when properties actually change
• Efficient hit testing with proper bounds checking
• Optimized split month rendering with minimal computational overhead
• Intelligent cell date rendering with automatic size detection

Memory Efficiency #

• HashMap-based data structure for fast lookups
• Minimal object allocation during painting
• Proper gesture recognizer cleanup prevents memory leaks
• Optimized text rendering with cached TextPainter objects
• Linear date sequence for efficient split month calculations

Scalability #

• Handles thousands of data points efficiently
• Constant time complexity for cell rendering
• Responsive layout adapts to available space
• Smooth interactions even with large datasets and split months

Migration (0.5.0) #

If you are upgrading from a version older than 0.5.0 that used the boolean showWeekdayLabels, apply the following replacements:

📝 Contributing #

Feel free to contribute! Check out the guides for more information.

❤️‍🔥 Enjoying this package? #

Here are a few ways you can show support:

• ⭐️ Star it on GitHub – stars help others discover it!
• 👍 Give it a thumbs up on pub.dev – every bit of appreciation counts!
• 👉 Try my TypeFast app, a fun way to sharpen your touch typing skills with games.
• 👉 Explore more of my work!