MonthRangePicker class

A custom date picker modal that allows users to select a month/year or a date range.

This widget provides two modes:

  • Monthly: Select a specific month and year
  • Custom: Select a custom date range with preset options (Last 3 months, Last 6 months, or custom range)

Example usage:

final result = await CustomDatePickerModal.show(
  context,
  initialDate: DateTime.now(),
  firstDate: DateTime(2020),
  lastDate: DateTime.now(),
);

if (result != null) {
  final (selectedDate, dateTimeRange, actionType) = result;
  if (actionType == ActionType.confirm) {
    // Handle date selection
  }
}
Inheritance

Constructors

MonthRangePicker({Key? key, DateTime? initialDate, DateTime? firstDate, DateTime? lastDate, int selectedTab = 0, dynamic onConfirm(DateTime)?, DateTimeRange<DateTime>? initialDateTimeRange, bool showTabs = true, bool showOnlyCustomRange = false, String headerText = 'Select month and year', bool showAllMonths = false, Color? primaryColor, Color? unselectedTextColor, String? fontFamily, TextStyle? tabTextStyle, TextStyle? headerTextStyle, TextStyle? pickerTextStyle, TextStyle? dateTextStyle, TextStyle? buttonTextStyle, TextStyle? errorTextStyle, TextStyle? labelTextStyle, int? maxRangeMonths, int? maxRangeYears, Widget confirmButtonBuilder(VoidCallback onConfirm)?, void onValidationError(BuildContext context, String message)?})
const

Properties

buttonTextStyle TextStyle?
Text style for button text. If null, uses Theme.of(context).textTheme.labelLarge with white color.
final
confirmButtonBuilder Widget Function(VoidCallback onConfirm)?
Builder for custom confirm button. If provided, this will be used instead of the default button. The builder receives a VoidCallback that should be called when the button is pressed. If null, uses the default ElevatedButton.
final
dateTextStyle TextStyle?
Text style for date field labels and values. If null, uses Theme.of(context).textTheme.bodyLarge.
final
errorTextStyle TextStyle?
Text style for error messages. If null, uses Theme.of(context).textTheme.bodyMedium with red color.
final
firstDate DateTime?
The earliest date that can be selected. Used to limit the available years in the picker.
final
fontFamily String?
Global font family that applies across all text in the picker. This font family will be merged into all TextStyles (both custom and default). If null, uses Theme.of(context).textTheme.bodyMedium?.fontFamily.
final
hashCode int
The hash code for this object.
no setterinherited
headerText String
The header text displayed at the top of the picker modal. Defaults to 'Select month and year'.
final
headerTextStyle TextStyle?
Text style for header text. If null, uses Theme.of(context).textTheme.titleMedium.
final
initialDate DateTime?
The initial date to be selected when the picker opens. If both initialDate and initialDateTimeRange are provided, an assertion error will be thrown.
final
initialDateTimeRange DateTimeRange<DateTime>?
The initial date range to be selected when the picker opens. If both initialDate and initialDateTimeRange are provided, an assertion error will be thrown.
final
key Key?
Controls how one widget replaces another widget in the tree.
finalinherited
labelTextStyle TextStyle?
Text style for info/label text. If null, uses Theme.of(context).textTheme.bodyMedium.
final
lastDate DateTime?
The latest date that can be selected. Used to limit the available years and months in the picker. If showAllMonths is false, months beyond this date will be filtered out.
final
maxRangeMonths int?
Maximum allowed range in months for custom date range selection. If null and maxRangeYears is also null, no limit is applied (unlimited range). If maxRangeYears is provided, this parameter is ignored.
final
maxRangeYears int?
Maximum allowed range in years for custom date range selection. If provided, takes precedence over maxRangeMonths. For example, 1 year = 12 months, 2 years = 24 months. If both maxRangeYears and maxRangeMonths are null, no limit is applied (unlimited range).
final
onConfirm → dynamic Function(DateTime)?
Callback function that is called when a date is confirmed.
final
onValidationError → void Function(BuildContext context, String message)?
Callback for showing validation errors. If null, uses a default inline error display.
final
pickerTextStyle TextStyle?
Text style for month/year picker text. If null, uses Theme.of(context).textTheme.headlineSmall.
final
primaryColor Color?
Primary color for the picker. If null, uses Theme.of(context).colorScheme.primary.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
selectedTab int
The selected tab index. 0 for Monthly, 1 for Custom. Defaults to 0.
final
showAllMonths bool
Whether to show all 12 months regardless of lastDate restriction. When true, all months are displayed even if they exceed lastDate. When false, months are filtered based on lastDate (e.g., if current month is November, only months up to November will be shown). Defaults to false.
final
showOnlyCustomRange bool
Whether to show only the Custom range picker (without tabs or Monthly picker). When true, only the Custom date range picker is displayed. Defaults to false.
final
showTabs bool
Whether to show tabs for switching between "Monthly" and "Custom" date range selection modes. Defaults to true.
final
tabTextStyle TextStyle?
Text style for tab labels. If null, uses Theme.of(context).textTheme.titleMedium with default font weight.
final
unselectedTextColor Color?
Color for unselected text. If null, uses Theme.of(context).textTheme.bodyMedium?.color with opacity.
final

Methods

createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() State<MonthRangePicker>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Methods

show(BuildContext context, {DateTime? initialDate, DateTime? firstDate, DateTime? lastDate, int selectedTab = 0, bool showTabs = true, bool showOnlyCustomRange = false, DateTimeRange<DateTime>? initialDateTimeRange, String headerText = 'Select month and year', bool showAllMonths = false, Color? primaryColor, Color? unselectedTextColor, String? fontFamily, TextStyle? tabTextStyle, TextStyle? headerTextStyle, TextStyle? pickerTextStyle, TextStyle? dateTextStyle, TextStyle? buttonTextStyle, TextStyle? errorTextStyle, TextStyle? labelTextStyle, int? maxRangeMonths, int? maxRangeYears, Widget confirmButtonBuilder(VoidCallback onConfirm)?, void onValidationError(BuildContext context, String message)?}) Future<(DateTime?, DateTimeRange<DateTime>?, ActionType)?>
Shows the date picker modal as a bottom sheet.