Date Picker

Anatomy

Progressively enhanced date input with calendar dropdown, range selection support, and custom formatting.

maud_ui::primitives::date_picker

Props

Generated from public Rust fields. Defaults are evaluated from the implementation.

Prop	Type	Default	Description
`id`	`String`	`"date-picker"`	Unique identifier
`name`	`String`	`"date"`	HTML form name
`selected`	`Option<(u32, u32, u32)>`	`None`	Selected date as (year, month, day) — month is 1-based
`placeholder`	`String`	`"Pick a date"`	Placeholder text
`disabled`	`bool`	`false`	Whether the picker is disabled
`min_date`	`Option<(u32, u32, u32)>`	`None`	Minimum selectable date (year, month, day)
`max_date`	`Option<(u32, u32, u32)>`	`None`	Maximum selectable date (year, month, day)
`mode`	`Mode`	`Single`	Selection mode — `Single` (default) or `Range`.
`format`	`Option<String>`	`None`	Optional display-format token (e.g. `"yyyy-MM-dd"`). When supplied and a date is selected, the trigger label is rendered using this format; otherwise the existing long-form display (`"April 20, 2026"`) is used.

Examples

No selection (placeholder)

With selected date

Disabled

Custom format + range mode

Usage and composition

Import

use maud_ui::primitives::date_picker::{self, Props, Mode};

Example

use maud::html;
use maud_ui::primitives::date_picker;

html! {
    (date_picker::render(date_picker::Props {
        id: "dp".to_string(),
        name: "date".to_string(),
        selected: Some((2026, 4, 20)),
        placeholder: "Pick a date".to_string(),
        mode: date_picker::Mode::Single,
        format: Some("yyyy-MM-dd".to_string()),
        ..Default::default()
    }))
}

Mode Enum

Variant	Description
`Single`	Single-date selection (default)
`Range`	Choose a start and end date. The picker stays open after the first selection and closes after the second; reversed selections are ordered automatically.

Features

Format tokens: yyyy (4-digit year), MM (2-digit month), dd (2-digit day). Without format, displays long form ("April 20, 2026")
Hidden input: Single mode submits YYYY-MM-DD. A completed range submits YYYY-MM-DD/YYYY-MM-DD under the same name; an incomplete range submits an empty value. In range mode, selected supplies an optional initial start date.
Form reset: On browsers supporting form-associated custom elements, native reset restores the initial picker value and label, and canceled resets leave the selection unchanged. A private nameless, readonly helper participates in form.elements but adds no submitted value. Older browsers use a deferred fallback with limited late-cancellation fidelity.
Inline calendar: Month/year navigation buttons, disabled date ranges via min/max
Selection event: Enhanced selection dispatches mui-date-change synchronously. In Nova, the same calendar node stays in its owned portal during the finite exit; reset, history snapshot, and teardown restore it synchronously.
Day-of-week calculation: Uses Tomohiko Sakamoto's algorithm; no external date library needed
Leap year handling: Correct February counts for leap years

Without JavaScript, Single mode uses a native date input with the configured name, value and min/max bounds. Range mode uses one text input carrying the same ISO interval; native validation checks its syntax, while applications must validate the dates, ordering and bounds on submission. Disabled pickers are not successful form controls. Enhanced form reset restores the initial value even after a history clone. Years 1–9999 are supported; invalid date triples or reversed bounds produce a noninteractive alert.

Dialog
Input
Combobox

Shadcn reference

https://ui.shadcn.com/docs/components/date-picker

Accessibility

Trigger button has aria-expanded and aria-haspopup="dialog"
Calendar buttons labeled with aria-label for month navigation
In Nova, day buttons use a roving tab stop. Arrows move by day or week, Home/End move to the week's edges, PageUp/PageDown move by month, and Shift modifies arrow or Page movement by month or year. Month-end dates are clamped to the target month's last day. Escape closes the popup and returns focus to the trigger.
Disabled dates rendered with disabled attribute and visually distinct

← Back to Gallery