Date pickers

Date pickers (COMPONENT_SPEC §27) are Compose's DatePicker (a calendar with a year grid, switchable to a date input), DateRangePicker (a scrolling list of months with the range band, switchable to start / end inputs) and DatePickerDialog, plus m3.material.io's docked date picker (a date field whose calendar drops down below it; Compose has none). Dates are UTC midnights, as Compose's states: ISO strings (2025-08-17) on the elements, milliseconds in React.

The calendar is an APG grid: arrows move a day or a week, Home / End go to the week's ends, Page Up / Down go a month (with Shift, a year), Enter or Space pick, and crossing a month's edge pages. The arrows page on Compose's spring(); a touch or pen swipe pages one month. The month and year button opens the year grid (a listbox, three years a row). The first day of the week, the names and the digits come from Intl for the nearest lang; the input's pattern is the locale's short date (MM/DD/YYYY in en-US), checked by a port of Compose's validator.

<m3e-date-picker value displayed-month year-range="1900-2100" display-mode="picker | input" hide-mode-toggle no-title no-headline> fires change (detail: { value }; the date field's native input / change do not reach the host), display-mode-change and displayed-month-change. The selectableDates property takes Compose's isSelectableDate(utcMillis) / isSelectableYear(year); labels overrides the strings.

display-mode-change and displayed-month-change bubble in 1.x, like every state event: a listener on an element also hears the same event from an element nested inside it, such as a tooltip in a dialog or a time picker in a tab panel. Check the target first: if (e.target !== host) return;. DECISIONS D25 proposes that 2.0 stop bubbling state events; item events such as action keep bubbling.

Calendar
Input
Weekdays from 2022, years 2020–2030

Date range picker (element)

<m3e-date-range-picker start end> takes the same attributes and fires change (detail: { start, end }; the end is null while only a start is picked). It fills its container: show it in <m3e-dialog variant="full-screen">, as Compose's samples do.

Range
Range input

Docked date picker (element)

<m3e-docked-date-picker value label year-range>: type a date or open the calendar from the field's button. The calendar's navigation row has the month and the year, each between arrows and with a menu; the other months' days show dimmed. In the open calendar, Shift + M and Shift + Y move to the month and year menu buttons, which announce them with aria-keyshortcuts. Picking a day fills the field and closes the calendar; Escape or a click outside closes it. Methods show() / close().

Dialogs (element)

Compose's DatePickerDialog: put the picker in a .m3e-date-picker-dialog surface (__content, __actions) inside <m3e-dialog variant="custom">. The range picker goes in a full-screen dialog with a Save action.

Picked: none

React

<DatePicker selectedDateMillis defaultSelectedDateMillis onSelectedDateChange displayedMonthMillis displayMode onDisplayModeChange yearRange selectableDates showModeToggle title showHeadline locale labels> (the boolean headline is the deprecated name of showHeadline, since 1.8, removed in 2.0; it warns once in development), <DateRangePicker selectedStartDateMillis selectedEndDateMillis onSelectedRangeChange …> and <DockedDatePicker selectedDateMillis onSelectedDateChange label …> render the same DOM as the elements. <DatePickerDialog dismissButton confirmButton> wraps a picker in <BasicAlertDialog>; put the range picker in <FullScreenDialog action>.

Sources

androidx Compose Material3 1.5.0-beta01 (19991f2c): DatePickerModalTokens.kt and DateInputModalTokens.kt as read by DatePicker.kt, DateRangePicker.kt, DateInput.kt (the input transformations, L380–444), DateRangeInput.kt, DatePickerDialog.kt / DatePickerDialog.android.kt and internal/CalendarModel*.kt (drift-tested in date-picker-sources.test.ts); the values Compose renders that are not tokens (cells and rows, paddings, the year grid, the dialog actions, the motion) in components/date-picker-defaults.css (lines in PARITY.md). The calendar math is checked against a JVM run of the vendored Kotlin.

m3.material.io Date pickers (Specs redlines for the docked picker, page 523144a0; Accessibility for the docked year arrows and the input format) and its token DB (TOKEN_TABLE.01c5310367774eb8, md.comp.date-picker.docked; the md.comp.date-picker.modal.* state layers). SOURCES register #44, #87 (the 456dp docked picker, DECISIONS D19 (24)), #88 (the state layers, D19 (25)), #89 and #90 (Compose's live input mask, D19 (26)); DECISIONS D20 (5) for the docked picker's Shift+M / Shift+Y, announced with aria-keyshortcuts.