🌙 Hijri Date — Hijri Calendar & Moon Phases Library
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
- 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.1
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 calculations are approximate and account for the supplied instant.
HijriDate.now() and HijriDate.fromDate(date) retain that instant for
getMoonPhase(), while a Hijri date without a time uses local midnight. To
calculate a phase directly for an instant, use
MoonPhaseCalculator.getMoonPhase(DateTime.now()). The four principal phase
names cover a short interval around their exact astronomical events.
Moon Phase Widget
A Flutter widget that displays the current moon phase using a PNG or SVG image and a softly edged geometric shadow, with an optional background.
Default assets included in the package:
- assets/moon.png (default)
- assets/moon.svg (alternative)
- 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.png', // PNG, JPEG, WebP, or SVG asset
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 opacity defaults to 0.8; set overlayOpacity to 0 to hide it.
Custom moon assets can use SVG or any image format supported by Flutter. Use
assetPackage: null for assets bundled by the host app, and adjust moonScale
if the moon occupies a different proportion of the image.
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