flutter_ethiopian_date_picker 1.0.0

A customizable Ethiopian (Ge'ez) calendar date picker widget for Flutter.

flutter_ethiopian_date_picker

A Flutter Material 3 date picker for the Ethiopian (Ge'ez) calendar with Gregorian conversion, range selection, localization, theming, and form integration.

Why flutter_ethiopian_date_picker?

• Native Ethiopian (Ge'ez) calendar support
• Accurate Gregorian ⇄ Ethiopian conversion
• Material 3–styled date picker
• Embeddable calendar widget
• Date range selection
• Form integration
• Full localization support
• Customizable theming
• Keyboard and screen-reader accessible

Screenshots

[doc/screenshots/01-home-light.jpg] Example app — home	[doc/screenshots/03-picker-default-theme.jpg] Date picker — default theme
[doc/screenshots/05-range-picker.jpg] Range picker — selected range	[doc/screenshots/04-picker-custom-theme.jpg] Date picker — custom theme (deep orange)

More examples (dark theme, Amharic, Afaan Oromo, Tigrinya)

[doc/screenshots/02-home-dark.jpg] Example app — dark theme	[doc/screenshots/07-locale-am.jpg] Localized — Amharic (አማርኛ)
[doc/screenshots/08-locale-om.jpg] Localized — Afaan Oromo, with keyboard-focus tooltip	[doc/screenshots/06-locale-ti.jpg] Localized — Tigrinya (ትግርኛ)

Installation

dependencies:
  flutter_ethiopian_date_picker: ^1.0.0

flutter pub get

import 'package:flutter_ethiopian_date_picker/flutter_ethiopian_date_picker.dart';

Quick start

Show a date picker with the default configuration:

final date = await showEthiopianDatePicker(context: context);

Customization

final date = await showEthiopianDatePicker(
  context: context,
  initialDate: EthiopianDate.today(),
  firstDate: EthiopianDate(2010, 1, 1),
  lastDate: EthiopianDate(2020, 13, 5),
  locale: EthiopianLocale.amharic.code,
  theme: EthiopianDatePickerTheme.material3(context).copyWith(
    primaryColor: Colors.deepOrange,
    selectedColor: Colors.deepOrange,
    backgroundColor: Colors.white,
  ),
);

EthiopianDatePickerTheme has no lightweight constructor — every field (including onSelectedColor, todayBorderColor, disabledColor) is required. Build a custom theme by calling .material3(context) for the Material 3 defaults, then .copyWith(...) the colors you want to change.

Range selection

final range = await showEthiopianDateRangePicker(
  context: context,
  firstDate: EthiopianDate(2010, 1, 1),
  lastDate: EthiopianDate(2020, 13, 5),
);

if (range != null) {
  print('${range.start} → ${range.end}');
}

Converting between calendars

final ethiopian = EthiopianDate.fromGregorian(DateTime.now());
final gregorian = ethiopian.toGregorian();

// DateTime extension
final today = DateTime.now().toEthiopianDate();

Embedded calendar

class MyEmbeddedCalendar extends StatefulWidget {
  const MyEmbeddedCalendar({super.key});

  @override
  State<MyEmbeddedCalendar> createState() => _MyEmbeddedCalendarState();
}

class _MyEmbeddedCalendarState extends State<MyEmbeddedCalendar> {
  EthiopianDate _displayedMonth = EthiopianDate.today();
  EthiopianDate? _selectedDate;

  @override
  Widget build(BuildContext context) {
    return EthiopianCalendarView(
      displayedMonth: _displayedMonth,
      firstDate: EthiopianDate(2010, 1, 1),
      lastDate: EthiopianDate(2020, 13, 5),
      selectedDate: _selectedDate,
      onDateSelected: (date) => setState(() => _selectedDate = date),
      onMonthChanged: (month) => setState(() => _displayedMonth = month),
    );
  }
}

EthiopianCalendarView is fully stateless and controlled. The parent owns the displayed month and selected date (or selected range, which takes priority over selectedDate if both are set) and updates them through onMonthChanged and onDateSelected. It integrates naturally with setState, Provider, Riverpod, Bloc, or any other state management solution.

Form field usage

Form(
  key: _formKey,
  child: EthiopianDateFormField(
    firstDate: EthiopianDate(2010, 1, 1),
    lastDate: EthiopianDate(2020, 13, 5),
    decoration: const InputDecoration(labelText: 'Birth date'),
    validator: (value) => value == null ? 'Required' : null,
    onSaved: (value) => _birthDate = value,
  ),
)

Localization

showEthiopianDatePicker(
  context: context,
  locale: EthiopianLocale.oromo.code,
);

Supported locales:

• English (en)
• Amharic (am)
• Afaan Oromo (om)
• Tigrinya (ti)

Unsupported locale codes automatically fall back to English.

Theming

Pass an EthiopianDatePickerTheme to override primaryColor, selectedColor, backgroundColor, spacing, and typography. With no theme provided, the picker uses Material 3 defaults derived from the ambient Theme.of(context).

API reference

API	Description
EthiopianDate	Core date model: year, month, day, validation, today(), comparisons (compareTo, isBefore, isAfter, isAtSameMomentAs), toJson/fromJson.
EthiopianDate.fromGregorian(DateTime)	Convert a DateTime to EthiopianDate.
EthiopianDate.toGregorian()	Convert back to a Gregorian DateTime.
DateTime.toEthiopianDate()	Extension method, equivalent to EthiopianDate.fromGregorian.
showEthiopianDatePicker({...})	Opens the picker dialog, returns Future<EthiopianDate?>. null on cancel.
showEthiopianDateRangePicker({...})	Opens the range picker dialog, returns Future<EthiopianDateRange?>.
EthiopianDateRange	start, end date pair.
EthiopianCalendarView	Embeddable, stateless calendar grid widget. Required: displayedMonth, firstDate, lastDate, onDateSelected, onMonthChanged. Optional: selectedDate, selectedRange (takes priority over selectedDate), locale, theme.
EthiopianDateFormField	FormField<EthiopianDate> — works with standard Form/FormState.
EthiopianDatePickerTheme	Visual customization: colors, spacing, typography.
EthiopianLocale	en, am, om, ti — enum used for all localized text.

For complete API documentation, see the package page on pub.dev.

Features

• ✅ Gregorian ⇄ Ethiopian conversion (leap years, Pagume 5/6 days), fuzz-tested
• ✅ Material 3 date picker dialog
• ✅ Embeddable calendar widget
• ✅ Date range selection (same-day, cross-month, cross-year)
• ✅ Material 3 theming with full override support
• ✅ Localization: English, Amharic, Afaan Oromo, Tigrinya (fallback to English)
• ✅ Form/FormState integration via EthiopianDateFormField
• ✅ Accessibility: semantic labels, full keyboard navigation, ≥48px touch targets, screen reader smoke-tested (VoiceOver/TalkBack)
• ✅ No internal global/static mutable state — safe with Provider, Riverpod, and Bloc
• ✅ Golden-tested UI across all themes and locales
• ✅ Slide/fade month transitions, ripple selection, and dialog animations
• ✅ Verified building on Android, iOS, Web, Windows, macOS, and Linux

Example app

The example/ application demonstrates:

• Date picker dialog
• Embedded calendar widget
• Range selection
• Theme switching
• Locale switching
• Form integration

cd example
flutter pub get
flutter run

Contributing / development

Contributions, bug reports, and feature requests are welcome.

• flutter analyze and flutter test must pass before opening a PR (enforced in CI).
• Any change to the public API must update CHANGELOG.md.

License

MIT — see the LICENSE file for details.