horizontal_date_range_picker 1.3.0

A horizontally-scrollable date picker widget with single date and date range selection modes.

Horizontal Date Range Picker

A horizontally-scrollable date picker widget for Flutter with single date and date range selection modes, PageView-based month navigation, and fully customizable styling.

Features

• Horizontal swipe between months (PageView-based)
• Single date selection mode
• Date range selection mode
• Fully customizable styling via DatePickerStyle
• Custom indicator shapes (circle, square, rounded rectangle)
• Locale-aware weekday and month formatting via intl
• Min/max date boundary enforcement
• Initial date / date range pre-selection
• Today indicator (toggleable)
• Accessibility: semantic labels, state announcements, 48x48 tap targets
• Drop-in widget (not a modal) — wrap it however you want

Installation

flutter pub add horizontal_date_range_picker

Usage

Single Date Selection

import 'package:horizontal_date_range_picker/horizontal_date_range_picker.dart';

SizedBox(
  height: 400,
  child: HorizontalDateRangePicker(
    selectionMode: SelectionMode.single,
    minDate: DateTime.utc(2024, 1, 1),
    maxDate: DateTime.utc(2026, 12, 31),
    onDateSelected: (date) {
      print('Selected: $date');
    },
  ),
)

Date Range Selection

import 'package:horizontal_date_range_picker/horizontal_date_range_picker.dart';

SizedBox(
  height: 400,
  child: HorizontalDateRangePicker(
    selectionMode: SelectionMode.range,
    minDate: DateTime.utc(2024, 1, 1),
    maxDate: DateTime.utc(2026, 12, 31),
    onDateRangeChanged: (start, end) {
      print('Range: $start - $end');
    },
  ),
)

Custom Styling

Use DatePickerStyle to override the visual appearance. All properties are optional — pass only what you want to change.

import 'package:horizontal_date_range_picker/horizontal_date_range_picker.dart';

SizedBox(
  height: 400,
  child: HorizontalDateRangePicker(
    selectionMode: SelectionMode.range,
    minDate: DateTime.utc(2024, 1, 1),
    maxDate: DateTime.utc(2026, 12, 31),
    style: DatePickerStyle(
      selectedDateBackground: Colors.indigo,
      selectedDateForeground: Colors.white,
      rangeSelectionBackground: Colors.indigo.withValues(alpha: 0.15),
      headerTextStyle: const TextStyle(
        fontSize: 18,
        fontWeight: FontWeight.bold,
        color: Colors.indigo,
      ),
      selectedIndicatorShape: DatePickerIndicatorShape.roundedRectangle(8),
    ),
    onDateRangeChanged: (start, end) {
      print('Range: $start - $end');
    },
  ),
)

Initial Selection

Pre-select a date or range when the picker opens:

import 'package:horizontal_date_range_picker/horizontal_date_range_picker.dart';

// Single mode: open on a specific pre-selected date
HorizontalDateRangePicker(
  selectionMode: SelectionMode.single,
  minDate: DateTime.utc(2024, 1, 1),
  maxDate: DateTime.utc(2026, 12, 31),
  initialDate: DateTime.utc(2025, 6, 15),
  onDateSelected: (date) => print('Selected: $date'),
)

// Range mode: open with a pre-selected range
HorizontalDateRangePicker(
  selectionMode: SelectionMode.range,
  minDate: DateTime.utc(2024, 1, 1),
  maxDate: DateTime.utc(2026, 12, 31),
  initialStartDate: DateTime.utc(2025, 6, 10),
  initialEndDate: DateTime.utc(2025, 6, 20),
  onDateRangeChanged: (start, end) => print('Range: $start - $end'),
)

API Reference

HorizontalDateRangePicker

Parameter	Type	Required	Default	Description
selectionMode	SelectionMode	yes	—	Whether to select a single date or a date range
minDate	DateTime	yes	—	Earliest month the user can navigate to
maxDate	DateTime	yes	—	Latest month the user can navigate to
locale	String	no	'en_US'	Locale string for weekday and month formatting
firstDayOfWeek	int?	no	null (Monday)	First day of week: ISO 8601 (0=Mon, 6=Sun)
style	DatePickerStyle?	no	null	Visual appearance overrides
initialDate	DateTime?	no	null	Pre-selected date for SelectionMode.single
initialStartDate	DateTime?	no	null	Pre-selected range start for SelectionMode.range
initialEndDate	DateTime?	no	null	Pre-selected range end (requires initialStartDate)
onDateSelected	void Function(DateTime)?	no	null	Callback when a date is selected in single mode
onDateRangeChanged	void Function(DateTime, DateTime)?	no	null	Callback when a complete range is selected in range mode
showTodayIndicator	bool	no	true	Whether to show the today dot indicator

DatePickerStyle

All properties are optional. Pass only the values you want to override from the widget's built-in defaults.

Property	Type	Description
selectedDateBackground	Color?	Background color for selected date(s)
selectedDateForeground	Color?	Text/foreground color for selected date(s)
rangeSelectionBackground	Color?	Background color for dates within a selected range
todayIndicatorColor	Color?	Color of the today indicator dot
disabledDateForeground	Color?	Text color for disabled (out-of-bounds) dates
headerTextStyle	TextStyle?	Text style for the month/year header
weekdayLabelTextStyle	TextStyle?	Text style for weekday labels (Mon, Tue, etc.)
dayTextStyle	TextStyle?	Text style for day number cells
selectedIndicatorShape	DatePickerIndicatorShape?	Shape of the selected date indicator (default: circle)
rangeIndicatorShape	DatePickerIndicatorShape?	Shape of the range highlight strip (default: square)
todayIndicatorShape	DatePickerIndicatorShape?	Shape of the today dot indicator (default: circle)

Use copyWith to derive a modified style from an existing one:

final myStyle = DatePickerStyle(selectedDateBackground: Colors.blue);
final modified = myStyle.copyWith(todayIndicatorColor: Colors.red);

SelectionMode

An enum that controls how dates are selected:

Value	Behavior
SelectionMode.single	Tapping a date selects it and fires onDateSelected
SelectionMode.range	First tap sets the start date; second tap sets the end date and fires onDateRangeChanged

DatePickerIndicatorShape

Factory constructors for the three available indicator shapes:

Constructor	Description
DatePickerIndicatorShape.circle()	Circular background (default for selected dates and today indicator)
DatePickerIndicatorShape.square()	Square background with sharp corners (default for range strip)
DatePickerIndicatorShape.roundedRectangle(double radius)	Rounded rectangle with configurable corner radius (default: 8 logical pixels)

Additional Information

License: MIT

Example: See the example for a complete demo with a mode switcher, live selection display, and custom theme styling.

Layout note: This is a drop-in widget, not a dialog or modal. Wrap it in a SizedBox, Expanded, or any layout widget to control its size.