Skip to main content

hijri_date 1.2.1 copy "hijri_date: ^1.2.1" to clipboard
hijri_date: ^1.2.1 copied to clipboard

Enhanced Hijri Calendar library with comprehensive date operations, Islamic events, multi-language support, and advanced utilities for Arabic, English, and Turkish locales.

🌙 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.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')}');
  }
}
20
likes
150
points
1.48k
downloads

Documentation

Documentation
API reference

Publisher

verified publisheralheekmahlib.com

Weekly Downloads

Enhanced Hijri Calendar library with comprehensive date operations, Islamic events, multi-language support, and advanced utilities for Arabic, English, and Turkish locales.

Homepage
Repository (GitHub)
View/report issues

Topics

#hijri #islamic-calendar #date-conversion #arabic #islamic-events

License

BSD-2-Clause (license)

Dependencies

flutter, flutter_svg, intl

More

Packages that depend on hijri_date