Skip to main content

hijri_date 1.2.0 copy "hijri_date: ^1.2.0" to clipboard
hijri_date: ^1.2.0 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.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')}');
  }
}
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.

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