awesome_calendart 2.0.1
awesome_calendart: ^2.0.1 copied to clipboard
A highly customizable calendar widget with single, multiple and range selection, week and month formats, events, themes and 100+ languages. Works on all platforms.
Awesome CalenDart #
A highly customizable calendar widget for Flutter: single, multiple and range selection, month / two-week / week formats, date limits and rules, colored events with an agenda list, week numbers, month/year pickers, swipe and keyboard navigation, a controller, theming (including ThemeExtension), and 100+ languages (including right-to-left) via intl. Works on all platforms.
Range selection with limits · multiple selection with adjacent days · week numbers, weekends and special dates
Week and two-week formats · event list under the calendar · month and year picker
Arabic (right to left, native digits) · custom theme and dayBuilder · dark theme with colored events
Contents #
Getting started · Recipes · Selection · Limits and rules · Calendar format · Controller · Events · Week numbers, weekends and special days · Keyboard · Customization · Localization · Accessibility · Migrating from 1.x
Getting started #
Requires Flutter 3.19 or newer (Dart 3.3). Works on Android, iOS, web and desktop.
dependencies:
awesome_calendart: ^2.0.1
import 'package:awesome_calendart/awesome_calendart.dart';
AwesomeCalenDart(
onDateSelected: (date) => print(date),
)
Every parameter is optional. The sections below show each feature; Customization lists every parameter, and the API reference on pub.dev documents each one in detail. The example app shows all of them running.
Recipes #
A booking range picker #
Pick 2 to 14 nights, from today to next year, skipping dates that are already booked:
AwesomeCalenDart(
selectionMode: AwesomeSelectionMode.range,
minDate: DateTime.now(),
maxDate: DateTime.now().add(const Duration(days: 365)),
minRangeLength: 2,
maxRangeLength: 14,
disabledDates: bookedDates, // a List<DateTime>
showAdjacentMonthDays: true,
onRangeChanged: (start, end) {
if (end != null) print('Book from $start to $end');
},
)
A birthday picker #
The year picker opens when you tap the header, so far-away years are quick to reach:
AwesomeCalenDart(
initialDate: DateTime(1995, 6, 15),
maxDate: DateTime.now(),
highlightToday: false,
onDateSelected: (birthday) => print(birthday),
)
An agenda with a "Today" button #
final controller = AwesomeCalenDartController();
Column(
children: [
AwesomeCalenDart(
controller: controller,
events: myEvents, // a List<AwesomeEvent>
eventListBuilder: (context, date, dayEvents) => Column(
children: [
for (final event in dayEvents)
ListTile(
leading: Icon(Icons.circle, color: event.color, size: 12),
title: Text(event.label ?? 'Event'),
),
],
),
),
TextButton(
onPressed: () => controller.selectDate(DateTime.now()),
child: const Text('Today'),
),
],
)
Selection #
AwesomeCalenDart(
selectionMode: AwesomeSelectionMode.range, // single (default), multiple, range
onRangeChanged: (start, end) {}, // end is null until the 2nd tap
)
| Mode | Behavior | Callbacks |
|---|---|---|
single |
Tapping a day selects it (today by default). | onDateSelected |
multiple |
Tapping a day toggles it. | onDateSelected, onDatesChanged |
range |
1st tap sets the start, 2nd the end, 3rd restarts. | onDateSelected, onRangeChanged |
onMonthChanged(DateTime firstDayOfMonth) fires whenever the visible month changes, whatever the selection mode.
Limits, rules and disabled days #
AwesomeCalenDart(
minDate: DateTime.now(),
maxDate: DateTime(2027, 12, 31),
disabledDates: [DateTime(2026, 12, 25)],
selectableDayPredicate: (day) => day.weekday < DateTime.saturday, // weekdays only
)
Disabled days are greyed out and cannot be tapped; navigation and the pickers stop at minDate / maxDate. selectableDayPredicate handles rules a list of dates can't express.
Range length #
AwesomeCalenDart(
selectionMode: AwesomeSelectionMode.range,
minRangeLength: 2, // at least 2 days between start and end ("2 nights")
maxRangeLength: 14,
)
While the end is being picked, days that would make the range too short or too long are disabled. To pick another start, tap an earlier day; with minRangeLength > 0, tapping the pending start again cancels it.
Calendar format #
AwesomeCalenDart(
calendarFormat: AwesomeCalendarFormat.week, // month (default), twoWeeks, week
showFormatButton: true, // header button cycling the formats
onFormatChanged: (format) {},
)
Navigation, swipe, the keyboard and minDate / maxDate all work by week or two weeks in the shorter formats. The header shows the month of the visible week.
Controller #
Read or change the state from code:
final controller = AwesomeCalenDartController();
AwesomeCalenDart(controller: controller);
controller.jumpToMonth(DateTime(2027, 3));
controller.jumpToDate(DateTime(2027, 3, 14)); // the month, or the week in the week formats
controller.selectDate(DateTime(2027, 3, 14));
controller.selectRange(DateTime(2027, 3, 1), DateTime(2027, 3, 7));
print(controller.selectedDate); // also: selectedDates, selectedRange, visibleMonth
controller.clearSelection();
It is a ChangeNotifier: listen to it, and dispose() it when done. The calendar never disposes a controller you pass in. Without a controller, initialDate sets the first visible month (and, in single mode, the first selected date).
Events #
AwesomeCalenDart(
eventMarkers: [DateTime(2026, 10, 3)], // simple dots
events: [ // colored, with a label
AwesomeEvent(date: DateTime(2026, 10, 5), color: Colors.green, label: 'Dentist'),
AwesomeEvent(date: DateTime(2026, 10, 5), color: Colors.amber),
],
showEventList: true, // list the selected day's events below
)
Up to three markers are shown per day, and event labels are read by screen readers. showEventList draws a simple list of the labels; for your own design use eventListBuilder:
AwesomeCalenDart(
events: myEvents,
eventListBuilder: (context, date, events) => Column(
children: [for (final e in events) ListTile(title: Text(e.label ?? ''))],
),
)
The builder is called with the selected day (the last tapped day in the multiple and range modes) and its events, possibly none.
Week numbers, weekends and special days #
AwesomeCalenDart(
showWeekNumbers: true, // ISO week numbers
weekendDays: const [DateTime.friday, DateTime.saturday], // default: Saturday, Sunday
theme: const LightTheme().copyWith(
weekendDayTextStyle: const TextStyle(color: Colors.red),
),
specialDates: {
DateTime(2026, 12, 25): const AwesomeDayStyle(
backgroundColor: Color(0x3300AA55),
textStyle: TextStyle(fontWeight: FontWeight.bold),
),
},
)
AwesomeDayStyle accepts textStyle, backgroundColor and borderColor. Selected days keep the selected style.
Keyboard navigation #
When the calendar has keyboard focus (Tab on web and desktop), the arrow keys move between days, Enter or Space select the focused day, and Page Up / Page Down change the period. A ring (AwesomeTheme.focusedDayBorderColor) shows the focused day. Turn it off with enableKeyboardNavigation: false.
Customization #
All parameters #
| Parameter | Default | Description |
|---|---|---|
theme |
ThemeData extension, else LightTheme() |
Colors and text styles, see below |
controller |
— | Read / change the month and selection from code |
initialDate |
today | First visible month (and first selected date in single mode) |
selectionMode |
single |
single, multiple or range |
calendarFormat |
month |
month, twoWeeks or week |
showFormatButton / formatButtonTooltip / onFormatChanged |
false / "Change view" / — |
Header button cycling the formats |
minDate / maxDate / disabledDates |
— | Selectable range and disabled days |
selectableDayPredicate |
— | Custom rule: return false to disable a day |
minRangeLength / maxRangeLength |
— | Allowed distance in days between a range's start and end |
locale |
Locale('en') |
Language of month/weekday names; RTL languages mirror the layout |
useLocaleDigits |
true |
Digits of the locale (Arabic-Indic for ar, Persian for fa, ...); false always shows 0-9 |
firstDayOfWeek |
DateTime.monday |
DateTime.monday … DateTime.sunday |
weekendDays |
Saturday, Sunday | Days styled with weekendDayTextStyle |
displayFullWeekdayNames |
false |
"Monday" instead of "Mon" |
showWeekNumbers |
false |
ISO week number column |
highlightToday |
true |
Ring around today |
showAdjacentMonthDays |
false |
Fill empty cells with the previous/next month's days |
eventMarkers / events |
— | Dots under days (simple / colored with labels) |
specialDates |
— | Per-day AwesomeDayStyle |
showEventList / eventListBuilder |
false / — |
Events of the selected day under the grid |
enableSwipe |
true |
Swipe horizontally to change period |
enableKeyboardNavigation |
true |
Arrow keys, Enter/Space, Page Up/Down |
enableMonthYearPicker |
true |
Tap the header to open the month and year pickers |
elevation / borderRadius |
5 / 20 |
Card shape |
padding |
h10, v8 |
Space inside the card |
dayAspectRatio |
1.5 |
Width / height of a day cell (reduced automatically for large system fonts) |
animationDuration / animationCurve |
250 ms / easeInOut |
Use Duration.zero to disable animations |
previousMonthIcon / nextMonthIcon |
arrows | Replace the navigation icons |
monthYearFormatter |
"October 2026" | Custom header title |
dayBuilder / headerBuilder / weekdayBuilder |
— | Draw the day cells, the header or the weekday labels yourself |
onDateSelected / onDatesChanged / onRangeChanged / onMonthChanged |
— | Callbacks, see Selection |
Theme #
AwesomeCalenDart(
theme: const DarkTheme().copyWith(
selectedDateBackgroundColor: Colors.teal,
todayBorderColor: Colors.teal,
),
)
LightTheme and DarkTheme are ready-made; build your own with AwesomeTheme(...) or copyWith. Themes support ==, hashCode and lerp.
AwesomeTheme is a ThemeExtension: register it once and every calendar without an explicit theme follows your app theme.
MaterialApp(
theme: ThemeData(extensions: const [LightTheme()]),
darkTheme: ThemeData.dark().copyWith(extensions: const [DarkTheme()]),
)
| Field | Description |
|---|---|
backgroundColor, buttonColor |
Card and navigation button colors |
yearAndMonthHeaderTextStyle, weekDaysTextStyle |
Header and weekday labels |
selectedDateBackgroundColor, selectedDayTextStyle |
Selected days (and range end points) |
unselectedDayTextStyle, weekendDayTextStyle, disabledDayTextStyle, adjacentMonthDayTextStyle |
Other days (weekendDayTextStyle is optional) |
weekNumberTextStyle |
Week numbers column |
focusedDayBorderColor |
Keyboard focus ring |
rangeBackgroundColor, rangeDayTextStyle |
Days inside a selected range |
todayBorderColor, todayBorderWidth |
Today ring |
eventMarkerColorOnSelectedDay, eventMarkerColorOnUnselectedDay, eventMarkerSize |
Event dots |
Custom day cells #
dayBuilder replaces the content of each cell. Tapping, disabled state and accessibility are still handled for you:
AwesomeCalenDart(
dayBuilder: (context, day) => Center(
child: Text(
'${day.date.day}',
style: TextStyle(
color: day.isSelected ? Colors.teal : null,
fontWeight: day.isToday ? FontWeight.bold : null,
),
),
),
)
AwesomeDayDetails exposes date, isSelected, isToday, isDisabled, isWeekend, isFocused, isOutsideMonth, isRangeStart, isRangeEnd, isInRange and events.
Custom header and weekday labels #
AwesomeCalenDart(
headerBuilder: (context, header) => Row(
children: [
IconButton(onPressed: header.canGoPrevious ? header.goToPrevious : null, icon: const Icon(Icons.chevron_left)),
Expanded(child: TextButton(onPressed: header.openPicker, child: Text(header.title))),
IconButton(onPressed: header.canGoNext ? header.goToNext : null, icon: const Icon(Icons.chevron_right)),
],
),
weekdayBuilder: (context, weekday, label) => Center(child: Text(label[0])), // M T W T F S S
)
AwesomeHeaderDetails exposes month, title, canGoPrevious, canGoNext, goToPrevious, goToNext, openPicker and changeFormat (null when the corresponding feature is off). weekday is DateTime.monday … DateTime.sunday.
Localization #
Names come from intl, so any locale it supports works:
// Any locale supported by intl works: de, es, it, pl, ar, ja, ...
AwesomeCalenDart(locale: const Locale('fr'))
Right-to-left languages (Arabic, Hebrew, Persian, Urdu, ...) mirror the layout, swipe direction, keyboard arrows and navigation arrows.
Numbers follow the locale by default, using the digits intl defines: Arabic-Indic for every Arabic locale (ar, ar_EG, ...), Persian for fa, Bengali for bn, Devanagari for mr / ne, and so on. Locales that use 0-9 (English, French, German, ...) are unaffected. To always show 0-9, even in those languages:
AwesomeCalenDart(locale: const Locale('ar'), useLocaleDigits: false)
Accessibility #
Each day is announced with its full date (and event labels), selected state and disabled state; navigation buttons have tooltips naming the target month; day cells scale with the system font size; the days can be reached and operated with the keyboard.
Migrating from 1.x #
Code changes
| 1.x | 2.0 |
|---|---|
locale: LocaleType.fr |
locale: const Locale('fr') |
displayFullMonthName: true |
displayFullWeekdayNames: true (it always controlled the weekday labels) |
theme.buttonColor = Colors.red (mutable AwesomeTheme fields) |
theme: const LightTheme().copyWith(buttonColor: Colors.red) |
AwesomeTheme() / LightTheme() / DarkTheme() |
unchanged, and now const |
eventMarkers and every other 1.x parameter keep working.
Things that look different without any code change
- Month and weekday names come from
intl, so some spellings change: French and Polish weekdays get a trailing dot ("Lun.", "Pon."), and German weekdays are "Mo", "Di", "Mi", ... instead of "Mon", "Die", "Mit", ... - Today gets a ring. Turn it off with
highlightToday: false. - Digits follow the locale: Arabic and Persian calendars show native digits, English and French are unchanged. Turn it off with
useLocaleDigits: false. - Days are now placed under the correct weekday (1.x always started the month under Monday).
- Swiping changes the month, and tapping the header opens the month and year pickers. Turn them off with
enableSwipe: falseandenableMonthYearPicker: false. - The calendar now takes only the height it needs, instead of filling a bounded parent.
See the example for every feature in action, and the changelog.
Contributing #
- The screenshots above are generated from the real widgets: run
flutter test tool/generate_screenshots_test.dartto refresh the files inimages/. - The code of the recipes and of the examples in this file is compiled and run by
test/readme_snippets_test.dart. When you change an example here, change it there too. - Run
flutter analyzeandflutter testbefore opening a pull request. Every public member needs a doc comment (thepublic_member_api_docslint is on).
