hijri_picker 5.0.0

Hijri (Umm al-Qura) date picker for Flutter, implemented as a CalendarDelegate so Flutter's built-in showDatePicker UI is used directly.

Hijri Date Picker

Hijri (Umm al-Qura / Islamic calendar) date picker for Flutter.

Overview

Since v5.0.0, this package is a thin adapter that lets Flutter's built-in Material 3 date picker render Hijri dates. It implements the CalendarDelegate API introduced in Flutter 3.32, so you get Flutter's showDatePicker, CalendarDatePicker, DatePickerDialog, InputDatePickerFormField, and YearPicker for free — with Hijri month names, Hijri weekday offsets, Hijri month lengths, and full theming via DatePickerThemeData.

Requirements

• Flutter >=3.32.0
• Dart ^3.8.0
• hijri ^3.0.1 (runtime dependency)

Screenshots

Light theme — Colors.amber seed

1. Home — top: showHijriDatePicker launchers + embedded CalendarDatePicker showing Dhu Al-Hijjah 1447, Friday 5 selected.	2. Home — bottom: InputDatePickerFormField, the embedded 3-column YearPicker (1447 selected), and the theming legend card.	3. showHijriDatePicker — basic dialog. Header reads "Fri, 5 DhuH"; M3 mode-toggle pencil icon in the corner.	4. Full options: custom helpText: "SELECT HIJRI DATE", uppercase cancelText/confirmText, and a selectableDayPredicate that disables Fridays (note the circled-disabled Friday 5).
5. Input mode (the pencil icon toggles to text-input). Typing 12/5/1447 in the locale's compact format — accepted by HijriCalendarDelegate.parseCompactDate.

Dark theme — Colors.blue seed

6. Same home in dark mode — Material 3 picks up the blue seed for primary/selection colors via ColorScheme.fromSeed.	7. Dark home, scrolled: input field, year grid (1447 highlighted in blue), and the dark theming legend.	8. Basic showHijriDatePicker dialog in dark mode — Hijri month name in the header, blue selection chip on day 5.	9. Full-options dialog in dark mode — Fridays disabled by predicate, day 6 (Saturday) selected.
10. DatePickerEntryMode.inputOnly — opens straight into a compact text field, no calendar.		11. Dark home scrolled — Hijri year grid 1439–1450 with 1447 selected (out-of-range years 1439–1441 dimmed).

Arabic locale (RTL)

12. Locale switched to ar_SA via the AppBar toggle. Layout flipped to RTL; calendar uses Arabic weekday abbreviations and Eastern-Arabic digits.	13. showHijriDatePicker dialog in Arabic. The cancelText/confirmText are still the English overrides we passed (demonstrating they take precedence over MaterialLocalizations).	14. Arabic input mode — compact-date field typed as 1447/12/5.
15. Embedded CalendarDatePicker + InputDatePickerFormField in Arabic — same widgets, RTL layout, Arabic month name.	16. Embedded YearPicker in Arabic — 3-column M3 year grid (1441–1450), 1447 selected.

Quick start

Register the standard Material/Widgets localization delegates:

MaterialApp(
  localizationsDelegates: const [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en', 'US'),
    Locale('ar', 'SA'),
  ],
  // ...
);

Option 1 — showHijriDatePicker (typed convenience)

final HijriDateTime now = HijriDateTime.now();
final HijriDateTime? picked = await showHijriDatePicker(
  context: context,
  initialDate: now,
  firstDate: HijriDateTime(now.year - 5, 1, 1),
  lastDate: HijriDateTime(now.year + 5, 12, 29),
  hijriLanguage: 'ar', // 'en', 'ar', 'tr', or any locale added via HijriCalendar.addLocale
);

Option 2 — Flutter's showDatePicker with HijriCalendarDelegate

final HijriDateTime? picked = await showDatePicker(
  context: context,
  initialDate: HijriDateTime.now(),
  firstDate: HijriDateTime(1440, 1, 1),
  lastDate: HijriDateTime(1455, 12, 29),
  calendarDelegate: const HijriCalendarDelegate(language: 'ar'),
) as HijriDateTime?;

Option 3 — Embedded widgets

The same delegate plugs into the embeddable widgets too:

CalendarDatePicker(
  initialDate: HijriDateTime.now(),
  firstDate: HijriDateTime(1440, 1, 1),
  lastDate: HijriDateTime(1455, 12, 29),
  onDateChanged: (DateTime d) => setState(() => selected = d as HijriDateTime),
  calendarDelegate: const HijriCalendarDelegate(),
);

InputDatePickerFormField(
  initialDate: HijriDateTime.now(),
  firstDate: HijriDateTime(1440, 1, 1),
  lastDate: HijriDateTime(1455, 12, 29),
  onDateSubmitted: (DateTime d) { /* d is a HijriDateTime */ },
  calendarDelegate: const HijriCalendarDelegate(),
);

YearPicker(
  firstDate: HijriDateTime(1440, 1, 1),
  lastDate: HijriDateTime(1455, 12, 29),
  selectedDate: HijriDateTime.now(),
  currentDate: HijriDateTime.now(), // required workaround — see note below
  onChanged: (DateTime d) { /* ... */ },
  calendarDelegate: const HijriCalendarDelegate(),
);

Note on YearPicker: Flutter's YearPicker constructor defaults currentDate to DateTime.now() (plain Gregorian) rather than calendarDelegate.now(), which crashes with any non-Gregorian delegate. Workaround: always pass currentDate: HijriDateTime.now() explicitly. The other entry points (CalendarDatePicker, DatePickerDialog, showDatePicker) handle this correctly.

Theming

All theming flows through Flutter's DatePickerThemeData:

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.amber,
      brightness: Brightness.light,
    ),
    datePickerTheme: const DatePickerThemeData(
      backgroundColor: Color(0xFFFFF8E1),
      headerBackgroundColor: Colors.amber,
      headerForegroundColor: Colors.black87,
    ),
  ),
);

Working with results

HijriDateTime extends DateTime; its .year/.month/.day are the Hijri components. Convert via:

final HijriDateTime d = HijriDateTime.now();
final HijriCalendar h = d.toHijriCalendar();   // hijri package's calendar object
final DateTime gregorian = d.toGregorian();    // equivalent Gregorian date

// Construct from sources:
HijriDateTime.fromHijriCalendar(someHijriCalendar);
HijriDateTime.fromGregorian(DateTime(2026, 5, 22));

Migration from 4.x

v5.0.0 is a breaking rewrite. The custom widgets have been removed.

4.x	5.x
showHijriDatePicker(initialDate: HijriCalendar..)	showHijriDatePicker(initialDate: HijriDateTime(..))
HijriMonthPicker widget	Use Flutter's CalendarDatePicker with calendarDelegate: HijriCalendarDelegate()
HijriDayPicker / HijriYearPicker widgets	Use Flutter's built-ins (internal _DayPicker, public YearPicker)
HijriCalendarBuilders (custom day/weekday builders)	Removed — customize via DatePickerThemeData
Return type HijriCalendar?	Return type HijriDateTime? (call .toHijriCalendar() or .toGregorian() to interop)

License

MIT — see LICENSE.

Author

Ahmed Aljoaid — @ahmedoid