🌙 Hijri Date — Hijri Calendar & Moon Phases Library

pub package pub points likes Pub Downloads License: MIT

Web Windows macOS Android iOS

Professional Dart/Flutter library for the Islamic (Hijri, Umm al-Qura) calendar: accurate Hijri↔Gregorian conversion, moon phases, Islamic events with authentic hadiths, multi-language support with localized numerals, and robust calendar utilities. Each section provides concise, non-duplicated examples.

Contents

Features Installation Quick Start Core Concepts Formatting Date Operations Calendar Utilities Horizontal Week Calendar Moon Phases Moon Phase Widget Islamic Events Localization & Numerals Compact Example

Features

  • Accurate Hijri↔Gregorian conversion (Umm al-Qura)
  • Strong validation with clear error messages
  • Flexible formatting with tokens and locale-aware numerals
  • Full date math: add/subtract days, months, years (overflow-safe)
  • Comparisons (<, <=, >, >=, ==) and difference in days
  • Utilities: days in month/year, week number, weekend detection
  • Moon phases, illumination, hilal visibility, and statistics
  • Built-in Islamic events with authentic hadiths and stats
  • Multi-language support: ar, en, tr, id, ms, fil, bn, ur

Installation

Add to your pubspec.yaml:

dependencies:
  hijri_date: ^1.2.0

Single entry import:

import 'package:hijri_date/hijri.dart';

Quick Start

import 'package:hijri_date/hijri.dart';

void main() {
  // Current Hijri date
  final today = HijriDate.now();
  print(today.fullDate()); // Wednesday, Rajab 15, 1445 h

  // From Gregorian date
  final fromGregorian = HijriDate.fromDate(DateTime(2024, 3, 15));
  print(fromGregorian.fullDate());

  // Locale (affects names and numerals)
  HijriDate.setLocal('ar');
  print(today.fullDate()); // الأربعاء، رجب ١٥، ١٤٤٥ هـ

  // Moon phase
  final moon = today.getMoonPhase();
  print('${today.getMoonPhaseName()} • ${(moon.illumination * 100).toStringAsFixed(1)}%');

  // Events
  final todays = IslamicEventsManager.getTodaysEvents();
  final next = IslamicEventsManager.getNextEvent();
  print("Today's events: ${todays.length}");
  print('Next: ${next?.getTitle('en')} in ${next?.daysUntilEvent()} day(s)');
}

Core Concepts

// Create dates
final d1 = HijriDate.now();
final d2 = HijriDate.fromDate(DateTime(2024, 3, 15));
final d3 = HijriDate.fromHijri(1445, 9, 15); // validates month/day

// Convert
final g = d3.hijriToGregorian(d3.hYear, d3.hMonth, d3.hDay); // DateTime
final h = HijriDate.fromDate(DateTime.now());                 // HijriDate

// Validation
try {
  HijriDate.fromHijri(1445, 13, 1);
} catch (e) {
  print(e); // Invalid Hijri date: 1445/13/1
}

Formatting

final date = HijriDate.fromHijri(1445, 9, 15);
print(date.fullDate());                    // Wednesday, Ramadan 15, 1445 h
print(date.toString());                    // 15/09/1445H (or yyyy/mm/dd in ar)
print(date.toFormat('DDDD, MMMM dd, yyyy')); // Wednesday, Ramadan 15, 1445
print(date.toFormat('dd/mm/yyyy'));         // 15/09/1445

// Tokens:
// DDDD: full weekday | DD: short weekday
// MMMM: full month   | MM: short month
// yyyy: full year    | yy: 2-digit year
// dd/mm: day/month digits localized to current language

Date Operations

final t = HijriDate.fromHijri(1445, 9, 15);
final after30 = t.addDays(30);
final minus2m = t.subtractMonths(2);
final nextYear = t.addYears(1);

// Comparisons and difference
final a = HijriDate.fromHijri(1445, 9, 15);
final b = HijriDate.fromHijri(1445, 10, 1);
print(a < b);                      // true
print(a.differenceInDays(b));      // -16
print(t.ageInYears(HijriDate.now()));

Calendar Utilities

final today = HijriDate.now();
print(today.lengthOfMonth);
print(today.lengthOfYear(year: today.hYear));
print(today.dayOfYear);
print(today.weekOfYear);
print(today.isWeekend);

print(today.firstDayOfMonth.fullDate());
print(today.lastDayOfMonth.fullDate());

final monthDays = today.getMonthDays(9, 1445); // map: day -> weekday name
final months = today.getMonths();               // localized month names

final json = today.toJson();
final copy = HijriDate.fromJson(json);
print(copy.isoFormat);                          // yyyy-mm-dd

Horizontal Week Calendar

import 'package:hijri_date/hijri.dart';

final hijriMin = HijriDate.fromHijri(1440, 1, 1);
final hijriMax = HijriDate.fromHijri(1460, 12, 30);
final hijriInitial = HijriDate.fromDate(DateTime(2024, 3, 10));

HorizontalWeekCalendar(
  minDate: DateTime(2020, 1, 1),
  maxDate: DateTime(2030, 12, 31),
  initialDate: DateTime(2024, 3, 10),
  useHijriDates: true,
  hijriMinDate: hijriMin,
  hijriMaxDate: hijriMax,
  hijriInitialDate: hijriInitial,
  showGregorianUnderHijri: true,
  gregorianDayFormat: 'd',
  translateNumbers: true,
  languageCode: 'ar',
  onDateChange: (date) => debugPrint('Selected: $date'),
);

Moon Phases

final h = HijriDate.fromHijri(1445, 9, 15);
final m = h.getMoonPhase();
print(h.getMoonPhaseName());
print((m.illumination * 100).toStringAsFixed(1));
print('Is full? ${h.isFullMoon()}  Is new? ${h.isNewMoon()}');
print('Days to next full: ${h.daysUntilNextFullMoon()}');

final fullMoons = HijriDate.getFullMoonDatesInYear(1445);
final newMoons  = HijriDate.getNewMoonDatesInYear(1445);

final stats = HijriDate.getMoonPhaseStatisticsForMonth(1445, 9); // {phase -> days}

Moon Phase Widget

A Flutter widget that displays the current moon phase using an SVG image and a geometric shadow, with an optional background.

Default assets included in the package:

  • assets/moon.svg
  • assets/moon_background.svg (optional)
import 'package:hijri_date/hijri.dart';

final moonInfo = HijriDate.now().getMoonPhase();

MoonPhaseWidget(
  moonInfo: moonInfo,
  size: 160,
  overlayColor: Colors.black,
  overlayOpacity: 0.35,
  backgroundAssetPath: 'assets/moon_background.svg', // Optional
  moonAssetPath: 'assets/moon.svg',
  showPhaseName: true, // Show the phase name below the moon
  phaseNameLanguage: 'ar', // Optional: ar or en; defaults to the app locale
  phaseNameStyle: const TextStyle(fontSize: 16), // Optional
);

The phase name is hidden by default; set showPhaseName: true to display it. The name is displayed in Arabic when the app locale is ar and in English for other locales. Use phaseNameLanguage to override the locale. The label adds height below the original widget size. The shadow is also hidden by default; set overlayOpacity above zero to display the phase.

Islamic Events

// Available via the same import: hijri.dart
final todays = IslamicEventsManager.getTodaysEvents();
final next = IslamicEventsManager.getNextEvent();

if (next != null) {
  print('Next: ${next.getTitle('en')} in ${next.daysUntilEvent()} day(s)');
}

final ramadanEvents = IslamicEventsManager.getEventsInMonth(9);
final stats = IslamicEventsManager.getEventsStatistics(); // totalEvents, mainEvents, reminders

final hadiths = IslamicEventsManager.getHadithsForEventType(IslamicEventType.ramadan);

Examples include: Islamic New Year, Tasoo'a/Ashura, Beginning of Ramadan, Laylat al-Qadr (reminder), Eid al-Fitr, Six of Shawwal (reminder), Ten Days of Dhul-Hijjah, Day of Arafah, Eid al-Adha.

Localization & Numerals

final date = HijriDate.fromHijri(1445, 1, 15);

for (final lang in ['ar','en','tr','id','ms','fil','bn','ur']) {
  HijriDate.setLocal(lang);
  print('$lang: ${date.toFormat('dd/mm/yyyy')} - ${date.getLongMonthName()}');
}

// Manual digit conversion utilities
final nAr = DigitsConverter.convertNumberToLocale(1445, 'ar'); // ١٤٤٥
final nUr = DigitsConverter.convertNumberToLocale(1445, 'ur'); // ۱۴۴۵

Compact Example

import 'package:hijri_date/hijri.dart';

void demo() {
  HijriDate.setLocal('en');
  final today = HijriDate.now();

  if (today.hMonth == 9) {
    final moon = today.getMoonPhase();
    print('Ramadan • ${today.getMoonPhaseName(language: 'en')} • ${(moon.illumination * 100).toStringAsFixed(1)}%');
  }

  if (today.hMonth == 12 && today.hDay >= 8 && today.hDay <= 13) {
    print('Hajj season');
  }

  for (final e in IslamicEventsManager.getTodaysEvents()) {
    print('Today: ${e.getTitle('en')}');
  }
}

Libraries

convert_number_extension
digits_converter
hijri
Hijri Date Library - مكتبة التاريخ الهجري A comprehensive Dart library for Islamic (Hijri) calendar operations
hijri_array
hijri_date
hijri_utils
Hijri Calendar Utilities and Constants Provides additional utility functions and constants for Hijri date operations
horizontal_week_calendar
moon_phase_widget
moon_phases
حساب أطوار القمر (Moon Phases Calculator) يوفر حسابات دقيقة لأطوار القمر المختلفة
religious_event