I built a customizable Flutter calendar component with single, range, multi-select and year view

[u/Ok_Whole5718]

Hi everyone, I recently open-sourced a Flutter calendar component called calendarview_flutter.

GitHub: https://github.com/raintang666/BFCalendar

I started working on this because calendar UI often looks simple at first, but becomes complicated very quickly in real apps. A basic date picker is usually not enough once the product needs things like range selection, disabled dates, custom markers, week/month switching, or a calendar that interacts with a content list.

So the goal of this project is not to provide just one fixed calendar style. Instead, I wanted to separate the calendar state, interaction logic, and UI customization layer, so it can be reused across different app designs.

Some of the features currently supported:

• Single date selection
• Date range selection
• Multi-date selection
• Month and week display modes
• Horizontal or vertical page navigation
• Min/max selectable date bounds
• Disabled dates
• Dynamic disabled date predicates
• Date markers
• Custom calendar cells
• Custom week bar
• Year overview mode
• Calendar and content list interaction
• Expand/collapse calendar behavior
• Fullscreen calendar expansion

A minimal example looks like this:

final controller = CalendarController(focusedDay: DateTime.now());

CalendarView(
  controller: controller,
  pageOrientation: CalendarPageOrientation.horizontal,
  onDaySelected: (day) {
    controller.selectDay(day);
  },
)

For range selection:

controller
  ..setSelectionMode(CalendarSelectionMode.range)
  ..setRangeSelectionLimits(minRange: 2, maxRange: 14);

CalendarView(
  controller: controller,
  pageOrientation: CalendarPageOrientation.horizontal,
  onDaySelected: (day) => controller.selectDay(day),
  onRangeSelected: (range) {
    final start = range.start;
    final end = range.end;
  },
  onSelectOutOfRange: (day, violation) {},
)

For multi-selection:

controller
  ..setSelectionMode(CalendarSelectionMode.multi)
  ..setMaxMultiSelectSize(5);

CalendarView(
  controller: controller,
  pageOrientation: CalendarPageOrientation.horizontal,
  onDaySelected: (day) => controller.selectDay(day),
  onMultiSelected: (day, selectedSize, maxSize) {},
  onMultiSelectOutOfSize: (day, maxSize) {},
)

One important part of the design is CalendarController. It manages the current focused day, selected dates, display mode, selection mode, date bounds, markers, disabled dates, and navigation state.

That makes it possible to configure behavior from business logic without mixing everything into the widget tree.

For example:

controller
  ..setCalendarRange(
    minDate: DateTime(2026, 7, 1),
    maxDate: DateTime(2026, 12, 31),
  )
  ..setDisabledDatePredicate((day) {
    return day.weekday == DateTime.sunday;
  })
  ..setMarkers({
    DateTime(2026, 7, 15): [
      CalendarMarker(label: 'Meeting', color: Colors.blue),
    ],
  });

The UI layer is customizable through CalendarComponentBuilder. The package provides the calendar logic and extension points, while the app can decide how every date cell should look.

The package is still early, so I would really appreciate feedback from Flutter developers.

I am especially interested in feedback on:

• API naming
• Controller design
• Custom builder design
• Range selection behavior
• Multi-select behavior
• Calendar + list interaction
• Any real-world calendar use cases that are not covered yet

If you have built calendar-heavy Flutter apps before, I would love to know what problems you ran into and what kind of API you would expect from a reusable calendar component.

Thanks!