date_picker_timeline 1.3.0

Flutter Date Picker Library that provides a calendar as a horizontal timeline.

DatePickerTimeline

Flutter Date Picker Library that provides a calendar as a horizontal timeline.

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  date_picker_timeline: ^1.3.0

Then import it in your Dart file:

import 'package:date_picker_timeline/date_picker_timeline.dart';

Quick start

Drop a DatePicker anywhere in your widget tree. The only required argument is the start date — the timeline renders from there onwards:

DatePicker(
  DateTime.now(),
  initialSelectedDate: DateTime.now(),
  selectionColor: Colors.black,
  selectedTextColor: Colors.white,
  onDateChange: (date) {
    setState(() => _selectedDate = date);
  },
)

Parameters

Parameter	Type	Default	Description
startDate	DateTime	required (positional)	First date on the timeline (or the centered anchor when showPastDates is on). Dates continue for daysCount days
width	double	60	Width of a single date tile
height	double	80	Height of the picker. Labels scale down automatically if the text styles don't fit
controller	DatePickerController?	null	Drives the picker programmatically — see DatePickerController
initialSelectedDate	DateTime?	null	Date highlighted when the picker first builds
selectionColor	Color	Color(0x30000000)	Background color of the selected tile
selectedTextColor	Color	Colors.white	Text color inside the selected tile
deactivatedColor	Color	Color(0xFF666666)	Text color for deactivated dates
monthTextStyle	TextStyle	11px, w500, black	Style for the month label
dateTextStyle	TextStyle	24px, w500, black	Style for the day-of-month number
dayTextStyle	TextStyle	11px, w500, black	Style for the weekday label
inactiveDates	List<DateTime>?	null	These dates are greyed out and can't be selected (e.g. weekends, holidays)
activeDates	List<DateTime>?	null	Only these dates can be selected; everything else is deactivated. Can't be combined with inactiveDates
daysCount	int	500	How many days to render, counted from startDate
showPastDates	bool	false	Also show past dates: half of daysCount falls before startDate, the picker opens with the selection (or startDate) centered, and controller methods scroll dates to the center instead of the leading edge
onDateChange	void Function(DateTime)?	null	Called with the tapped date whenever the selection changes
locale	String	"en_US"	Locale for month and weekday names (e.g. "de_DE", "fr_FR")
calendarType	CalendarType	gregorianDate	gregorianDate or persianDate (Jalali)
directionality	TextDirection?	null	Overrides scroll direction; defaults to RTL for the Persian calendar, LTR otherwise

Time-of-day components are ignored everywhere — dates are compared by calendar day, so passing DateTime.now() is always safe.

DatePickerController

Attach a controller to move the timeline from code:

final _controller = DatePickerController();

DatePicker(
  DateTime.now(),
  controller: _controller,
  ...
)

// Somewhere in your code:
_controller.animateToSelection();                 // scroll back to the selected date
_controller.jumpToSelection();                    // same, without animation
_controller.animateToDate(someDate);              // scroll to a date (selection unchanged)
_controller.setDateAndAnimate(someDate);          // select a date AND scroll to it

Member	Description
jumpToSelection()	Jumps instantly to the selected date
animateToSelection({duration, curve})	Animates to the selected date
animateToDate(date, {duration, curve})	Animates to date without changing the selection
setDateAndAnimate(date, {duration, curve})	Selects date, repaints the highlight, and animates to it
isAttached	Whether the controller is attached to a mounted DatePicker

All methods are safe no-ops when the controller isn't attached, nothing is selected yet, or the target date is outside the rendered range. With showPastDates: true every method centers the target date in the viewport instead of aligning it to the leading edge.

Design showcase

The example app contains eight ready-made designs you can copy into your project — Classic, Past & future (showPastDates), Midnight (dark theme), Booking (weekends disabled), Sunset (gradient hero), Compact, Localized, and a controller playground:

Run it with:

cd example && flutter run

Recipes

Timeline with history — today opens centered, past on the left:

DatePicker(
  DateTime.now(),
  showPastDates: true,   // 60 past days + 60 future days
  daysCount: 120,
  initialSelectedDate: DateTime.now(),
  ...
)

Disable weekends (Booking design):

final weekends = [
  for (var i = 0; i < 60; i++)
    if (DateUtils.addDaysToDate(DateTime.now(), i).weekday >= DateTime.saturday)
      DateUtils.addDaysToDate(DateTime.now(), i),
];

DatePicker(
  DateTime.now(),
  inactiveDates: weekends,
  daysCount: 60,
  ...
)

Dark theme (Midnight design) — provide explicit text styles, since the defaults are black:

DatePicker(
  DateTime.now(),
  selectionColor: const Color(0xFF7C4DFF),
  selectedTextColor: Colors.white,
  deactivatedColor: Colors.white24,
  monthTextStyle: const TextStyle(color: Colors.white54, fontSize: 11),
  dayTextStyle: const TextStyle(color: Colors.white54, fontSize: 11),
  dateTextStyle: const TextStyle(color: Colors.white, fontSize: 24),
  ...
)

Compact strip for app bars and bottom sheets:

DatePicker(
  DateTime.now(),
  width: 44,
  height: 64,
  monthTextStyle: const TextStyle(fontSize: 9),
  dayTextStyle: const TextStyle(fontSize: 9),
  dateTextStyle: const TextStyle(fontSize: 16),
  ...
)

Author

• Vivek Kaushik

Contributors

• BradInTheUSA
• Roger