persian_calendar_pro #

A lightweight, zero-dependency Persian (Jalali) and Gregorian calendar for Flutter — scrollable views, single & range date pickers, a standalone date converter, and a fluent Builder configuration API.

No runtime dependencies. No bundled assets or fonts. Pure Dart + Flutter, so it runs on every platform Flutter supports — including web/wasm.

Screenshots #

Month view	Week-row view

Features #

• Two calendars, one widget — Jalali and Gregorian, switchable at runtime (the focused month and selection convert with you).
• Three scroll modes — vertical month list, vertical week-row list, and a horizontal month pager.
• Two month-scroll styles — free (normal) or indexed for precise jump-to-month / jump-to-row.
• Single & range selection with a one-selected-day guard.
• Standalone converter — use CalendarService with no widget at all.
• Fully localizable — Farsi/English digits, RTL/LTR, week start, short/long names and formats.
• Themeable — Material 3, colors, shapes, typography, transparent background, injectable fonts.
• Responsive — cap the width on web/desktop with maxWidth.

Install #

dependencies:
  persian_calendar_pro: ^0.1.0

import 'package:persian_calendar_pro/persian_calendar_pro.dart';

Quick start #

PersianCalendar(
  maxWidth: 560, // keeps cells sensible on web/desktop; omit on phones
  onSelectionChanged: (selection) {
    if (selection == null) return;
    debugPrint(selection.jalali.faLong);    // ۶ تیر ۱۴۰۵
    debugPrint(selection.gregorian.enLong); // June 27, 2026
  },
)

By default the system is auto-detected from the device locale, today is selected, and the view scrolls vertically by month.

Configuration (Builder API) #

Everything is configured through CalendarConfigBuilder:

final config = CalendarConfigBuilder()
    .localization((l) => l
      ..system = CalendarSystem.jalali     // or null = auto-detect
      ..digitMode = DigitMode.farsi
      ..weekStart = WeekStart.saturday)
    .scroll((s) => s
      ..mode = ScrollMode.verticalMonth
      ..monthScrollStyle = MonthScrollStyle.indexed)
    .selection((s) => s
      ..mode = SelectionMode.range
      ..selectTodayByDefault = true)
    .header((h) => h
      ..visible = true
      ..source = HeaderSource.selected)
    .theme((t) => t
      ..useMaterial3 = true
      ..shapes = const CalendarShapes(dayShape: DayCellShape.circle))
    .build();

PersianCalendar(config: config);

Programmatic control #

Use a CalendarController to drive the calendar:

final controller = CalendarController(config: config);

controller.goToToday();
controller.scrollToMonthIndex(120); // indexed month style
controller.scrollToRowIndex(50);    // indexed month style
controller.switchSystem(CalendarSystem.gregorian);

PersianCalendar(controller: controller);

Standalone converter #

No widget required:

final service = CalendarService.instance;

final jalali = service.toJalali(GregorianDate.ymd(2026, 6, 27));
final gregorian = service.toGregorian(JalaliDate.ymd(1405, 4, 6));

Supported range #

Dates are supported for Jalali years 1178–1633 (≈ Gregorian 1799–2255), matching the well-validated Jalali conversion range. Dates outside this window throw a DateRangeError; in grids, out-of-range positions render as blanks.

Platforms #

Android · iOS · web · macOS · Windows · Linux.

Roadmap #

• Events & reminders
• Built-in accessibility/semantics labels
• Keyboard navigation for web/desktop

Contributing #

Issues and PRs welcome. Please run dart format ., flutter analyze, and flutter test before submitting.

License #

MIT — see LICENSE.