Date & time
DatePickerControl · TimePickerControl · DateRangePickerControl · CalendarControl · TimeSpanPickerControlType it or pick it: dates with a calendar drop-down, times from a stepped list, ranges, multi-day selections and durations.
Overview
DatePickerControl is a text box that parses what you type (sixteen built-in date formats, more with ShowTime) and opens a calendar
on the 📅 button, F4 or Enter on an empty field. TimePickerControl is an editable drop-down of times from Min
to Max every Step. DateRangePickerControl pairs two date pickers with a range calendar in a popup,
and CalendarControl is that calendar on its own, in single, multiple or range mode. TimeSpanPickerControl is a
row of number boxes for a duration. All five bind their value two ways and report validation through EditContext when
used inside an EditForm.
Examples
#Date, time and duration
MinDate greys out the past; ShowCalendarSidebar adds Today, Tomorrow and week shortcuts to the drop-down. The time list runs 8:00 to 18:00 in half hours, and typed times outside it are refused with the control's own message. The duration commits when a box loses focus.
Example
Razor
C#
Date
Start
Duration
h
m
Tue 20 Oct 2026, 9:30 AM – 11:00 AM
#Date range
One CalendarRange binds both pickers and the popup calendar. Min and Max bound the hire window. Put the end before the start and the control reports it; the bound value still updates, so the page can refuse to count nights.
Example
Razor
C#
3 day hire, Mon 26 Oct to Thu 29 Oct
#Calendar, several dates
SelectionMode="Multiple" toggles days into Values. DisabledDate greys out weekends, FirstDayOfWeek starts the grid on Monday, and the heading button switches to a year or decade view. Arrow keys move through the days.
Example
Razor
C#
MonTueWedThuFriSatSun
3 site visits: Tue 20 Oct, Thu 22 Oct, Mon 26 Oct
Documentation
DatePickerControl parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
Value | DateTime? | null | Selected date, or date and time with ShowTime. Two-way with @bind-Value. |
ValueChanged | EventCallback<DateTime?> | — | Fires when typed text parses (Enter or blur) or a day is picked. |
ValueExpression | Expression<Func<DateTime?>>? | null | Set by @bind-Value; marks the field changed on the cascaded EditContext. |
Format | string? | "MM/dd/yyyy" (with time: "MM/dd/yyyy hh:mm tt") | Display format. Typed text is tried against this first, then the built-in list. |
Placeholder | string? | the format | Input placeholder. |
ShowTime | bool | false | Adds a time box to the drop-down and time formats to parsing. |
MinDate / MaxDate | DateTime? | null | Days outside are disabled in the calendar and rejected when typed. |
ShowCalendarSidebar | bool | false | Expandable sidebar of shortcuts: Today, Yesterday, Tomorrow, Start and End of Week, Next Week, Start and End of Month, Clear Date. |
ParseFormats | IEnumerable<string>? | null | Extra formats tried before the sixteen built-in ones (ISO, US, day-month, dd-MMM-yy, digit runs). |
Culture | CultureInfo? | current | Parsing and formatting culture. |
ShowTriggerButton | bool | true | Shows the 📅 button. Without it Enter on an empty field no longer opens the calendar. |
OpenCalendarOnDoubleClick | bool | false | Double-click in the input opens the calendar. |
AutoFocus | bool | false | Focuses the input once after first render. |
AriaLabel | string? | null | Accessible name of the input. |
ValidationChanged | EventCallback<string?> | — | Fires with the parse message, or null when the text is valid again. |
Enabled / Visible / Id / CssClass / Style (base) | | — | All honoured on the host. |
Grid-cell hosting | | — | OpenOnRender, InitialText, Uncontrolled, InputValueChanged, ElementReferenceCaptured, OnKeyDown, CalendarButtonKeyDown serve the grid's cell editor; see the source comments before using them in a form. |
TimePickerControl parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
Value | TimeOnly? | null | Selected time. Two-way with @bind-Value. |
ValueChanged | EventCallback<TimeOnly?> | — | Fires when a list entry is chosen or typed text parses on Enter. |
ValueExpression | Expression<Func<TimeOnly?>>? | null | Set by @bind-Value; validation messages go to the EditContext. |
Min / Max | TimeOnly | 00:00 / 23:59:59.9999999 | First and last entry; typed times outside are refused. |
Step | TimeSpan | 30 minutes | Gap between entries. At least one second, and at most 1441 entries, or the control throws. |
Format | string | "hh:mm tt" | Display and parse format; free-form input is also tried with the culture's parser. |
Culture | CultureInfo | current | Formatting culture. |
Width | string? | null | CSS width of the drop-down. |
AriaLabel | string? | null | Accessible name of the input. |
ValidationChanged | EventCallback<string?> | — | Fires with the error text, or null once valid. |
OnKeyDown | EventCallback<KeyboardEventArgs> | — | Raw key events from the input. |
Enabled / Visible (base) | bool | true | Honoured. |
DateRangePickerControl parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
Value | CalendarRange | (null, null) | Start and end; either may be null. Two-way with @bind-Value. |
ValueChanged | EventCallback<CalendarRange> | — | Fires after either picker or the popup calendar changes the range, even when it is invalid. |
ValueExpression | Expression<Func<CalendarRange>>? | null | Set by @bind-Value; the error goes to the EditContext. |
Min / Max | DateTime? | null | Bounds for both dates. Min after Max throws. |
DisabledDate | Func<DateTime,bool>? | null | Days that cannot be inside the range. |
AriaLabel | string | "Date range" | Accessible name of the group. |
Enabled (base) | bool | true | false disables the pickers and the Choose range button. |
CalendarControl parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
Value / ValueChanged | DateTime? | null | Selection in Single mode. |
Values / ValuesChanged | IReadOnlyList<DateTime> | empty | Selection in Multiple mode; a click toggles the day and the list is kept sorted. |
Range / RangeChanged | CalendarRange | (null, null) | Selection in Range mode: first click sets the start, second the end; a click before the start swaps them. |
SelectionMode | CalendarSelectionMode | Single | Single, Multiple or Range. |
Min / Max | DateTime? | null | Days outside are disabled and the month buttons stop there. |
DisabledDate | Func<DateTime,bool>? | null | Extra disabled days. A range that would cross one is refused. |
Culture | CultureInfo | current | Day names, month names and the default first day. |
FirstDayOfWeek | DayOfWeek? | null | Overrides the culture's first day. |
DisplayDate / DisplayDateChanged | DateTime? | value or today | Month on show. Changes when the user navigates. |
View / ViewChanged | CalendarView | Month | Month, Year (pick a month) or Decade (pick a year). The heading button cycles them. |
ShowTodayButton | bool | true | Renders a Today button under the grid. |
DayTemplate | RenderFragment<CalendarCellContext>? | null | Custom day cell; receives CalendarCellContext. |
Enabled / Visible / Id (base) | | — | Honoured. |
TimeSpanPickerControl parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
Value | TimeSpan? | null | Duration. Two-way with @bind-Value; null shows zeros. |
ValueChanged | EventCallback<TimeSpan?> | — | Fires when a box commits (blur or Enter), not per keystroke. |
ShowDays | bool | false | Adds a days box (0 or more). |
ShowSeconds | bool | false | Adds a seconds box (0–59). |
Disabled | bool | false | Disables the boxes. The base Enabled and Visible are not read by this control. |
(unmatched attributes) | Dictionary<string,object> | — | Forwarded to the host <div>. |
CalendarRange and CalendarCellContext
| Property | Type | Default | Description |
|---|---|---|---|
CalendarRange.Start / End | DateTime? | — | Either bound may be null. Positional record: new(start, end), update with with. |
CalendarCellContext | record | — | Date, Selected, Disabled, InCurrentMonth: what a DayTemplate receives. |
Methods and read-only properties
| Method | Inputs | Returns | Description |
|---|---|---|---|
DatePickerControl.FocusAsync() | — | Task | Focuses the input. |
TimePickerControl.FocusAsync() | — | Task | Focuses the drop-down's input. |
TimePickerControl.ErrorMessage | — | string? | Current parse or bounds message, or null. |
DateRangePickerControl.SetValueAsync() | range | Task | Validates order, bounds and disabled days, publishes the error and raises ValueChanged. |
DateRangePickerControl.Error | — | string? | Current message, or null. |
CalendarControl.NavigateAsync() | direction | Task | Moves one period back (−1) or forward (+1) in the current view. |
CalendarControl.SelectAsync() | date | Task | Same as clicking the day: honours the selection mode and disabled days. |
CSS classes
| Class | Effect |
|---|---|
fx-datepicker-host · -input-group · -input · -trigger | Host, the input row, the text box and the 📅 button. -input-group-no-trigger when the button is hidden. |
fx-datepicker-dropdown · -popup-layer · -backdrop · -validation-pill | The calendar (expanded or minimal with the sidebar), its top-layer wrapper, the click-away backdrop and the error pill. |
fx-calendar-main · fx-calendar-sidebar · fx-shortcut-btn | Drop-down month panel, shortcut sidebar and its buttons. |
fx-timepicker · fx-timepicker-error | Host around the drop-down list and the error line. |
fx-date-range · fx-range-error | Flex row of the two pickers, the Choose range button and the error. |
fx-calendar · -header · -cells · -row · -cell | Standalone calendar; cells take selected, today and outside. |
fx-timespan-picker · -segment · -input · -unit | Bordered row of number boxes with unit letters; disabled greys it. |
CSS variables
| Variable | Fallback | Purpose |
|---|---|---|
--fx-border · --fx-surface · --fx-text · --fx-primary | #cbd5e1 · #fff · #202630 · #2563eb | Read by CalendarControl for its frame, background, text and the selected day. |
--fx-zoom | 1 | Scales the date picker's drop-down. |
(none) | — | The time, range and time span pickers read no variables. |
Keyboard and accessibility
Keyboard: date picker input
| Key | Action |
|---|---|
F4 / Alt+Arrow Down | Open or close the calendar. |
Enter | Parse the typed text. On an empty field, open the calendar instead. |
Escape | Close the calendar; typed text stays for correction. |
Arrow keys (calendar open) | Left and Right move a day, Up and Down a week. |
Page Up / Page Down | Previous or next month; with Shift, a year. |
Home / End | First or last day of the focused week. |
Enter / Space (calendar open) | Select the focused day. |
Keyboard: calendar grid
| Key | Action |
|---|---|
Arrow keys | Move the focused day; disabled days are skipped and the month follows. |
Page Up / Page Down | Same day in the previous or next month; with Shift, year. |
Home / End | First or last day of the week, honouring FirstDayOfWeek. |
Enter / Space | Select the focused day (a native button). |
- The date input carries
aria-label,aria-expandedandaria-invalid; the 📅 button is named "Toggle calendar". A parse error renders in arole="alert"pill witharia-live="assertive". - The time picker's error and the range picker's error are
role="alert". The range picker is arole="group"whose inputs are named "Start date" and "End date". - The calendar is a
role="grid"with column headers andaria-selectedcells. Each day is a button named with the full date; one day holds the Tab stop and the arrows move it. - The time span boxes have no label beyond the unit letters d, h, m, s; put a visible label before the control.