Heatmap Calendar Plus (fork) #

This package is an actively maintained fork of flutter_heatmap_calendar, inspired by GitHub’s contribution graph.

• Original package: https://pub.dev/packages/flutter_heatmap_calendar
• Original author: Kim Seung Hwan (MIT)

Heatmap Calendar Plus maintains compatibility with the existing API and continues with bug fixes and new features. It provides the traditional HeatMap widget as well as its calendar version HeatMapCalendar.

Migración desde flutter_heatmap_calendar #

1. Update your pubspec.yaml to use this fork:

dependencies:
  heatmap_calendar_plus: ^1.0.0

2. Update your imports:

- import 'package:flutter_heatmap_calendar/flutter_heatmap_calendar.dart';
+ import 'package:heatmap_calendar_plus/heatmap_calendar_plus.dart';

🔥 Why use this fork #

• Actively maintained: keeps evolving with fixes, improvements, and support for modern Flutter/Dart (Dart 3 compatible).
• Smooth migration: almost drop-in replacement with a dedicated migration section and barrel import (heatmap_calendar_plus.dart).
• API modernization: consolidated TextStyle-based props (monthTextStyle, weekTextStyle, dayTextStyle) and clearer spacing controls (blockSpacing, colorTipSpacing).
• More control on calendar: header customization via headerBuilder, header margin with marginHeader, and a HeatMapCalendarController for programmatic control.
• Stability fixes: includes upstream fixes (overflow with startDate, DST week alignment) and general refactors.
• Better docs and example: refreshed README and runnable example app.
• Localization-ready: month and week labels adapt to your app locale (uses intl); the example includes flutter_localizations.

✨ Features #

• Two widgets: HeatMap (contribution grid) and HeatMapCalendar (calendar view).
• Color strategies: ColorMode.opacity and ColorMode.color with threshold-based colorsets.
• Customization: size, blockSpacing, borderRadius, scrollable/flexible, monthTextStyle, weekTextStyle, dayTextStyle.
• Interactivity: onClick on days and onMonthChange on month navigation.
• Calendar-specific add-ons:
  • headerBuilder for a custom header UI.
  • marginHeader to tweak header spacing.
  • HeatMapCalendarController for programmatic navigation/control.
• Localization (i18n): month/week labels localized via intl following your MaterialApp locale.

🌍 Localization (i18n) #

heatmap_calendar_plus utiliza intl para mostrar nombres de meses y etiquetas de semana según el locale de tu aplicación. Asegúrate de habilitar las localizaciones de Flutter:

import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
  // Usa los delegados por defecto de Flutter
  localizationsDelegates: GlobalMaterialLocalizations.delegates,

  // Declara los locales soportados por tu app
  supportedLocales: const [
    Locale('en'),
    Locale('es'),
    // agrega tus locales...
  ],

  // Opcional: fuerza un locale específico durante pruebas/desarrollo
  locale: const Locale('es'),
  // ...
)

El ejemplo incluido en example/ ya viene configurado con flutter_localizations y supportedLocales para es y en.

📦 Getting started #

Depend on it. #

flutter pub add heatmap_calendar_plus

or

Add below line to your personal package's pubspec.yaml.

dependencies:
  heatmap_calendar_plus: ^1.0.0

And run flutter pub get to install.

Import it. #

import 'package:heatmap_calendar_plus/heatmap_calendar_plus.dart';

Props #

HeatMap #

HeatMapCalendar #

Example #

HeatMap #

import 'package:heatmap_calendar_plus/heatmap_calendar_plus.dart';
...
HeatMap(
  datasets: {
    DateTime(2021, 1, 6): 3,
    DateTime(2021, 1, 7): 7,
    DateTime(2021, 1, 8): 10,
    DateTime(2021, 1, 9): 13,
    DateTime(2021, 1, 13): 6,
  },
  colorMode: ColorMode.opacity,
  showText: false,
  scrollable: true,
  colorsets: {
    1: Colors.red,
    3: Colors.orange,
    5: Colors.yellow,
    7: Colors.green,
    9: Colors.blue,
    11: Colors.indigo,
    13: Colors.purple,
  },
  onClick: (value) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(value.toString())));
  },
);

HeatMapCalendar #

import 'package:heatmap_calendar_plus/heatmap_calendar_plus.dart';
...
HeatMapCalendar(
  defaultColor: Colors.white,
  flexible: true,
  colorMode: ColorMode.color,
  datasets: {
    DateTime(2021, 1, 6): 3,
    DateTime(2021, 1, 7): 7,
    DateTime(2021, 1, 8): 10,
    DateTime(2021, 1, 9): 13,
    DateTime(2021, 1, 13): 6,
  },
  colorsets: const {
    1: Colors.red,
    3: Colors.orange,
    5: Colors.yellow,
    7: Colors.green,
    9: Colors.blue,
    11: Colors.indigo,
    13: Colors.purple,
  },
  onClick: (value) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(value.toString())));
  },
);

License #

Este proyecto es un fork bajo licencia MIT del trabajo original de Kim Seung Hwan. Consulta el archivo LICENSE para los avisos completos.