custom_month_picker

A lightweight, customizable month picker popup for Flutter. Display the months of the year in a responsive grid inside a rounded card, let the user pick one, and (optionally) disable months past a given index.

• ✅ Drop-in widget or one-line dialog helper
• ✅ Fully theme-able (colors, radii, font sizes, padding, grid spacing)
• ✅ Auto-detected phone vs tablet layout (overridable)
• ✅ Disable months past a given index (e.g. future months in the current year)
• ✅ Custom month labels (any length / language)
• ✅ Pure Dart/Flutter — no native code, no extra dependencies

Installation

Add this to your pubspec.yaml:

dependencies:
  custom_month_picker: ^0.1.0

Then run:

flutter pub get

Usage

Show as a modal dialog

import 'package:custom_month_picker/custom_month_picker.dart';

final picked = await CustomMonthPicker.show(
  context,
  selectedMonth: 'Mar',
  enabledUpToIndex: DateTime.now().month, // disable future months this year
);

if (picked != null) {
  debugPrint('User picked: $picked');
}

Embed inline in any layout

CustomMonthPicker(
  selectedMonth: selected,
  enabledUpToIndex: DateTime.now().month,
  onMonthSelected: (month) {
    setState(() => selected = month);
  },
);

Customize colors and shape

CustomMonthPicker.show(
  context,
  selectedMonth: selected,
  theme: const CustomMonthPickerTheme(
    primaryColor: Color(0xFFFF6F00),
    backgroundColor: Colors.white,
    titleColor: Colors.black,
    enabledTextColor: Colors.black87,
    borderRadius: 24,
    tileBorderRadius: 8,
    titleFontSize: 16,
    tileFontSize: 12,
    gridSpacing: 12,
  ),
  title: 'Pick a month',
);

Use custom labels (any length / language)

CustomMonthPicker.show(
  context,
  months: const [
    'January', 'February', 'March', 'April',
    'May',     'June',     'July',  'August',
    'September','October', 'November','December',
  ],
  crossAxisCount: 4,
);

Force a layout

CustomMonthPicker(
  compact: false,            // force tablet layout
  horizontalMargin: 100,     // override the default margin
  onMonthSelected: (m) {},
);

API overview

Class	Purpose
CustomMonthPicker	The widget. Embed directly or present via show().
CustomMonthPicker.show()	Presents the picker as a modal dialog and resolves with the picked month.
CustomMonthPickerTheme	Visual configuration (colors, radii, font sizes, padding, spacing).

CustomMonthPicker parameters

Name	Type	Default	Description
months	List<String>	kDefaultMonthLabels (Jan..Dec)	Labels shown in display order.
selectedMonth	String?	null	Currently selected month label.
enabledUpToIndex	int?	null	1-based index of the last enabled month. Tiles past it are disabled.
onMonthSelected	ValueChanged<String>	required	Called when an enabled tile is tapped.
title	String	'Select a Month'	Title above the grid.
crossAxisCount	int	3	Number of columns.
theme	CustomMonthPickerTheme	const CustomMonthPickerTheme()	Visual configuration.
compact	bool?	auto	Force compact (phone) or regular (tablet) layout.
horizontalMargin	double?	auto	Outer horizontal margin around the popup card.

Example

A complete runnable example lives in example/.

cd example
flutter run

Maintainer

This package is built and maintained by Mohamed Rizwan.

GitHub	github.com/riz9882
LinkedIn	linkedin.com/in/mohamed-rizwan-b667a1248
Email	riz9882@gmail.com

Contributing

Contributions, issues, and feature requests are welcome.

• Found a bug? Please open an issue with steps to reproduce, expected vs. actual behavior, and your Flutter / Dart version (flutter --version).
• Want a feature? Open an issue first to discuss the design before sending a pull request.
• Sending a PR?
  1. Fork the repo and create a feature branch (git checkout -b feat/my-change).
  2. Run flutter analyze and flutter test — both must be green.
  3. Update the CHANGELOG.md under an Unreleased heading describing your change.
  4. Open the PR against main and link any related issue.

If you find this package useful, please consider starring the GitHub repository — it helps others discover it.

License

This package is released under the MIT License © Mohamed Rizwan.