WDatePicker

WDatePicker(
  value: _selectedDate,
  onChanged: (date) => setState(() => _selectedDate = date),
  className: 'w-full p-3 border border-gray-300 rounded-lg',
  placeholder: 'Select a date',
)

Basic Usage#

WDatePicker renders a trigger container that opens a popover-based calendar on click. It handles month navigation, today highlighting, and date constraints out of the box.

DateTime? _selectedDate;

WDatePicker(
  value: _selectedDate,
  onChanged: (date) {
    setState(() => _selectedDate = date);
  },
  className: 'bg-white border rounded-md px-4 py-2 hover:border-blue-500',
)

When no className is provided, the trigger uses this default styling:

// Default trigger className
'bg-white border border-gray-300 rounded-lg p-3 dark:bg-gray-800 dark:border-gray-600'

The calendar popover opens below the trigger and auto-flips if there isn't enough space. In single mode, the popover closes automatically after a date is selected.

Constructor#

const WDatePicker({
  Key? key,
  WDatePickerMode mode = WDatePickerMode.single,
  DateTime? value,
  DateRange? range,
  ValueChanged<DateTime>? onChanged,
  ValueChanged<DateRange>? onRangeChanged,
  DateTime? minDate,
  DateTime? maxDate,
  String? className,
  String placeholder = 'Select date',
  bool disabled = false,
  Set<String> states = const {},
  DateDisplayFormat? displayFormat,
  int minuteStep = 5,
  String timeLabel = 'Time',
  String doneLabel = 'Done',
})

Props#

Types#

WDatePickerMode#

Determines whether the picker selects a single date, a date range, or a single date carrying a time of day.

enum WDatePickerMode {
  single,    // Pick a single date (time struck to midnight)
  range,     // Pick a start and end date
  dateTime,  // Pick a single date AND a time of day
}

single and range normalise every value to midnight. dateTime is the only mode that preserves an hour and a minute, so it is the one to use when the value is an instant rather than a calendar day. It adds a stepped time row below the calendar and keeps the popover open until the confirm control is pressed.

DateRange#

Represents a date range with a required start and optional end date.

class DateRange {
  final DateTime start;
  final DateTime? end;

  bool get isComplete => end != null;

  DateRange copyWith({DateTime? start, DateTime? end});
}

DateDisplayFormat#

A typedef for custom date formatting:

typedef DateDisplayFormat = String Function(DateTime date);

When no displayFormat is provided, dates display as "Jan 15, 2025" format.

Date Range Selection#

Setting mode: WDatePickerMode.range enables two-click range selection with hover preview.

DateRange? _dateRange;

WDatePicker(
  mode: WDatePickerMode.range,
  range: _dateRange,
  onRangeChanged: (range) => setState(() => _dateRange = range),
  placeholder: 'Check-in / Check-out',
  className: 'w-64 border p-3 rounded-lg',
)

How range selection works:

1. First click: Sets the range start. The onRangeChanged callback fires with a DateRange where end is null.
2. Hover: As the user moves the mouse, dates between start and the hovered date are highlighted with a blue tint.
3. Second click: Completes the range. If the second date is before the first, they're automatically swapped. The popover closes.

The trigger display text updates throughout: "Jan 15, 2025 - ..." while in progress, then "Jan 15, 2025 - Jan 20, 2025" when complete.

Date + Time Selection#

Setting mode: WDatePickerMode.dateTime keeps the time of day. The tapped day is composed with a stepped time row and emitted as a single local DateTime, where single and range strike everything to midnight.

DateTime? _startsAt;

WDatePicker(
  mode: WDatePickerMode.dateTime,
  value: _startsAt,
  onChanged: (value) => setState(() => _startsAt = value),
  minuteStep: 15,
  placeholder: 'Schedule the deploy',
  className: 'w-full p-3 border rounded-lg',
)

How the mode differs from single:

1. The popover stays open on a day tap. The time row below the calendar is the second half of the selection, so the confirm control (doneLabel) is what closes it.
2. onChanged fires on every change, both the day tap and each time step, always with the full composed instant. A time step only emits once a day has been picked: before that it moves the pending time and nothing is emitted. Closing the popover commits nothing new.
3. The mode is controlled. Feed each emitted value back through value or the calendar highlight, the time row, and the bounds will drift apart from what the user sees.
4. The time row is Wind markup, two 24-hour spinners plus the confirm control built from WDiv / WText / WIcon. It is not a Material showTimePicker dialog, so it themes with the rest of the picker.

The spinners never wrap: stepping up from 23:00 would move the instant a full day backwards while the calendar kept showing the same day, so an edge step renders disabled instead. minuteStep sets how far one press of the minute spinner moves (default 5).

Min/Max Constraints#

Use minDate and maxDate to restrict which dates are selectable. Dates outside the range appear dimmed and don't respond to clicks.

WDatePicker(
  value: _selectedDate,
  onChanged: (date) => setState(() => _selectedDate = date),
  minDate: DateTime.now(),
  maxDate: DateTime.now().add(const Duration(days: 90)),
  className: 'p-3 border rounded-lg',
  placeholder: 'Next 90 days only',
)

Bounds in dateTime mode#

Because the bound is compared as a full instant, a maxDate written as a bare day is that day at midnight, and the last day then admits only 00:00: every time you pick on it collapses back to midnight and its step controls render disabled. Spell out the end of the day when you mean the whole day.

WDatePicker(
  mode: WDatePickerMode.dateTime,
  value: _startsAt,
  onChanged: (value) => setState(() => _startsAt = value),
  minDate: DateTime.now(),
  // Not DateTime(2026, 8, 31), which caps the last day at 00:00.
  maxDate: DateTime(2026, 8, 31, 23, 59),
  className: 'p-3 border rounded-lg',
)

Custom Display Format#

Override the default "Jan 15, 2025" format with a custom function:

WDatePicker(
  value: _selectedDate,
  onChanged: (date) => setState(() => _selectedDate = date),
  displayFormat: (date) => '${date.day}/${date.month}/${date.year}',
  className: 'p-3 border rounded-lg',
)

In range mode, the format function applies to both start and end dates independently.

Event Handling#

Single Mode#

onChanged fires with a normalised DateTime (midnight, no time component) when the user selects a date:

WDatePicker(
  value: _date,
  onChanged: (date) {
    setState(() => _date = date);
    _loadSchedule(date);
  },
)

Range Mode#

onRangeChanged fires twice during a range selection: once on the first click (start only) and once on the second click (complete range):

WDatePicker(
  mode: WDatePickerMode.range,
  range: _range,
  onRangeChanged: (range) {
    setState(() => _range = range);
    if (range.isComplete) {
      _calculateDuration(range.start, range.end!);
    }
  },
)

DateTime Mode#

onChanged reuses the single-mode callback but fires on every change, the day tap and each time step alike, always carrying the full composed instant:

WDatePicker(
  mode: WDatePickerMode.dateTime,
  value: _startsAt,
  onChanged: (value) {
    // Fires again on every hour / minute step, not only on the day tap.
    setState(() => _startsAt = value);
  },
)

Treat it as a live value rather than a commit signal. The confirm control only closes the popover; if you need a "the user finished" moment, act on the value you already hold once the popover closes.

State Variants#

WDatePicker automatically manages several interactive states. Use state prefixes in className to apply conditional styles.

WDatePicker(
  value: _date,
  onChanged: (date) => setState(() => _date = date),
  className: 'p-3 border border-gray-300 rounded-lg '
      'hover:border-blue-400 '
      'focus:border-blue-500 focus:ring-2 focus:ring-blue-200 '
      'selected:bg-blue-50 '
      'disabled:opacity-50 disabled:bg-gray-100',
)

Disabled State#

When disabled: true, the trigger shows a forbidden cursor and the popover won't open:

WDatePicker(
  disabled: true,
  value: DateTime(2025, 6, 15),
  className: 'p-3 border rounded-lg disabled:opacity-50 disabled:bg-gray-100',
)

Styling Examples#

Default Styling#

Without a className, the trigger uses built-in defaults with dark mode support:

WDatePicker(
  value: _date,
  onChanged: (date) => setState(() => _date = date),
  // Uses: 'bg-white border border-gray-300 rounded-lg p-3
  //        dark:bg-gray-800 dark:border-gray-600'
)

Interactive with Ring Focus#

WDatePicker(
  value: _date,
  onChanged: (date) => setState(() => _date = date),
  className: 'w-full p-3 bg-white dark:bg-gray-800 '
      'border border-gray-300 dark:border-gray-600 rounded-lg '
      'hover:border-blue-400 dark:hover:border-blue-500 '
      'focus:border-blue-500 focus:ring-2 focus:ring-blue-200 '
      'dark:focus:ring-blue-800 '
      'selected:border-blue-500',
)

Compact Inline#

WDatePicker(
  value: _date,
  onChanged: (date) => setState(() => _date = date),
  className: 'px-2 py-1 text-sm border rounded bg-gray-50 hover:bg-white',
  placeholder: 'Date',
)

Borderless with Shadow#

WDatePicker(
  value: _date,
  onChanged: (date) => setState(() => _date = date),
  className: 'p-3 bg-white rounded-xl shadow-md hover:shadow-lg',
)

Calendar Internals#

The calendar popover is styled with a fixed-width container:

'w-[320px] bg-white dark:bg-gray-800 border border-gray-200
 dark:border-gray-700 rounded-xl shadow-xl p-4 overflow-y-auto'

The calendar grid consists of:

All Supported Classes#

Trigger (className)#

The className prop styles the trigger container. All Wind utility classes are supported:

What className Does NOT Control#

The calendar popover, header, weekday labels, and day cells use internal Wind classes that are not configurable via props.

Customizing Theme#

The calendar's selection colours route through the theme primary token (bg-primary for the selected day, bg-primary-100 / text-primary-700 for the in-range fill). Override primary to recolour the calendar to your brand; the neutral grays remain configurable via their own palette keys. The default primary is aliased to the Tailwind blue swatch, so leaving it unchanged keeps the original blue look.

WindTheme(
  data: WindThemeData(
    colors: {
      'primary': MaterialColor(0xFF16A34A, {
        100: Color(0xFFDCFCE7),  // Range fill
        300: Color(0xFF86EFAC),  // Dark mode range text
        500: Color(0xFF16A34A),  // Selected day (shade 500 == bg-primary)
        700: Color(0xFF15803D),  // Range text
        900: Color(0xFF14532D),  // Dark mode range
      }),
    },
  ),
  child: MyApp(),
)

The calendar only reads shades 100 / 300 / 500 / 700 / 900, so the partial swatch above is enough for it. Other primary-driven widgets read further shades (WSelect uses 400 / 600 / 700 for its raw icon colours and class tokens such as text-primary-800 for its selected chip text). A missing shade falls back to the swatch's base colour only for those raw icons, so nothing throws there; a class token such as text-primary-800 resolves to nothing when its shade is absent, and the requested colour is not applied. If you share one primary across widgets, use a complete 50-950 swatch (e.g. a generated MaterialColor) so every shade renders as intended.

Related Documentation#

• WFormDatePicker - Form-integrated date picker with validation
• WSelect - Dropdown selection component
• WPopover - The underlying overlay engine
• WInput - Standard text input widget