toc

Date picker

A date picker lets people select a date or a range of dates.

<md-gb-date-picker label="Event date"></md-gb-date-picker>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-date-picker.json (setup)

Usage guidelines

Link to “Usage guidelines”

Match the context. Use the docked picker, a calendar under a text field, on medium and expanded windows. Use a modal picker on compact ones.
Pick or type. A modal picker has a calendar mode and an input mode for typing a date.
Select a range. Add range to choose a start and an end date.
Offer a way to clear. Add clearable so people can remove a selection.

This component is new in M3 Expressive.

Anatomy

Link to “Anatomy”

A date picker is one element. A docked picker renders a text field and a calendar popup; a modal picker renders a dialog.

<md-gb-date-picker label="Due date"></md-gb-date-picker>

Examples

Link to “Examples”

Link to “Modal”

Set variant="modal" and call show() to open the picker in a dialog. Use mode="input" to start with the date input.

HTML

<md-gb-button id="open-picker">Pick a date</md-gb-button>
<md-gb-date-picker id="picker" variant="modal"></md-gb-date-picker>

document.querySelector('#open-picker')!.addEventListener('click', () => {
  document.querySelector('md-gb-date-picker')!.show();
});

Range

Link to “Range”

Add range to select a start and an end date. The value is an ISO interval such as 2026-08-17/2026-08-23.

<md-gb-date-picker range label="Trip dates"></md-gb-date-picker>

Value, min and max

Link to “Value, min and max”

Set value to an ISO date (YYYY-MM-DD). Limit the choices with min and max.

<md-gb-date-picker label="Check-in" value="2026-08-17" min="2026-08-01" max="2026-12-31"></md-gb-date-picker>

Full screen

Link to “Full screen”

Add fullscreen to a modal picker for compact windows. It has a close button and a Save button.

<md-gb-date-picker variant="modal" fullscreen range open></md-gb-date-picker>

Accessibility

Link to “Accessibility”

Name the field with label, such as "Event date", and use supporting-text to show the expected format.
Calendar targets stay 48px, so density only affects the text fields.
Page Up and Page Down move by month, and Shift with them moves by year.
The modal picker closes with Escape, and the docked picker confirms with Enter.

Compatibility

Link to “Compatibility”

Material Design 30 uncovered77% tokens

79 of 379 buildable spec units are tested, 11 are excluded with a written reason and 0 are uncovered (the target is 0). 112 of 146 token declarations match the spec (77%), 1 differ on purpose or are being fixed, and 33 have no spec token.

date-pickers on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

@starting-style (opens in a new tab) Newly available degrades safely where it is missing
Cursor styles (opens in a new tab) Limited availability degrades safely where it is missing
overscroll-behavior (opens in a new tab) Limited availability degrades safely where it is missing
scrollbar-color (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-gutter (opens in a new tab) Newly available degrades safely where it is missing
scrollbar-width (opens in a new tab) Newly available degrades safely where it is missing
user-select (opens in a new tab) Limited availability used inside an @supports guard
popover (opens in a new tab) Newly available JavaScript, feature-detected or optional

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonDialog (Modal)

Roles the component renders: button (opens in a new tab), dialog (opens in a new tab), grid (opens in a new tab), gridcell (opens in a new tab), group (opens in a new tab), heading (opens in a new tab), listbox (opens in a new tab), option (opens in a new tab), row (opens in a new tab), rowgroup (opens in a new tab), separator (opens in a new tab), textbox (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Dialog (Modal) (opens in a new tab), Grid (opens in a new tab), Listbox (opens in a new tab).

4 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse91 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

First Contentful Paint
Largest Contentful Paint
Largest Contentful Paint element
Eliminate render-blocking resources
Minify CSS
Minify JavaScript
Reduce unused CSS
Reduce unused JavaScript
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-date-picker>

Link to “<md-gb-date-picker>”

A Material Design date picker (docked or modal, single date or range).

Properties

Link to “Properties”

Property	Attribute	Type	Default
`clearable` Shows a Clear button that removes the selection.	`clearable`	`boolean`	`false`
`density` The density of the picker's text fields (the docked field and the modal input mode's fields), from 0 (default) to -3, as `md-gb-text-field` `density`. Values are clamped to that range. The calendar itself never gets denser (date-pickers.md, Accessibility: "Interactive targets for all elements meet Material's 48x48dp minimum touch target requirement. Increasing density would negatively impact accessibility by limiting tappable/clickable targets"): its dates, menus and buttons keep their size, including inside a dense container.	`density`	`Density`
`error` Forces the error state of the docked field.	`error`	`boolean`	`false`
`errorText` The message shown on the docked field while `error` is set.	`error-text`	`string`	`''`
`firstDayOfWeek` The first day of the week, 0 (Sunday) to 6 (Saturday). -1 (default) uses the locale's.	`first-day-of-week`	`number`	`-1`
`fullscreen` Modal: the full-screen layout the spec recommends on compact windows. The dialog covers the window and has a close (x) icon button and a Save button in place of Cancel and OK.	`fullscreen`	`boolean`	`false`
`hideActions` Hides the Cancel and OK buttons; a selection is committed right away.	`hide-actions`	`boolean`	`false`
`inline` Renders the calendar surface in the page flow, always visible, instead of a docked popup (without the text field) or a modal dialog.	`inline`	`boolean`	`false`
`isDateDisabled` Returns true for dates that can't be selected (in addition to dates outside `min` / `max`). Receives an ISO date.		`(date: string) => boolean`	`null`
`label` Docked: the text field label. Defaults to "Date" (range: "Dates").	`label`	`string`	`''`
`locale` A BCP 47 locale. Defaults to the document's `lang`, else the browser's.	`locale`	`string`	`''`
`max` The latest selectable date (ISO).	`max`	`string`	`''`
`min` The earliest selectable date (ISO).	`min`	`string`	`''`
`mode` Modal: shows the calendar (`picker`) or the date input (`input`).	`mode`	`DatePickerMode`	`'picker'`
`open` Whether the popup (docked) or dialog (modal) is open.	`open`	`boolean`
`quick` Skips animations.	`quick`	`boolean`	`false`
`range` Selects a start and end date.	`range`	`boolean`	`false`
`required` A value is required: with no date (or a range without an end date) the picker is invalid (`valueMissing`).	`required`	`boolean`	`false`
`strings` Overrides for the user-facing strings.		`Partial<DatePickerStrings>`	`{}`
`supportingText` Docked: the field's supporting text. Defaults to the date format, e.g. MM/DD/YYYY.	`supporting-text`	`string`	`''`
`value` The committed value: an ISO date (`YYYY-MM-DD`), or an ISO interval (`start/end`) when `range` is set. Empty when nothing is selected.	`value`	`string`	`''`
`variant` `docked` (default) or `modal`.	`variant`	`DatePickerVariant`	`'docked'`

Events

Link to “Events”

Event	Description
`cancel` Event	The selection was dismissed (Cancel, Escape or a click outside). Cancelable: canceling keeps the picker open.
`change` CustomEvent<DatePickerValueDetail>	The value was committed (OK, Enter, typing in the docked field, or a pick with `hide-actions`).
`close` CustomEvent<{reason: string}>	The popup or dialog began closing; `reason` is `confirm` or `cancel`.
`input` CustomEvent<DatePickerValueDetail>	The pending selection changed (a date was picked or a valid date typed).
`open` Event	The popup or dialog opened.

Methods

Link to “Methods”

Method	Description
`cancel` (reason?: string) => boolean	Discards the pending selection: fires a cancelable `cancel` event, then closes the popup or dialog.
`close` (reason?: string) => Promise<void>	Closes the popup or dialog without changing the value (use `confirm()` to commit the pending selection).
`confirm` () => boolean	Commits the pending selection to `value` (firing `change` if it changed) and closes the popup or dialog. In the date input mode, invalid text shows its error and keeps the picker open.
`focus` (options?: FocusOptions) => void	MDN Reference
`show` () => Promise<void>	Opens the calendar popup (docked) or dialog (modal). The pending selection starts from `value`, and focus moves to the selected date (or today).
`showMonth` (year: number, month: number) => void	Shows the given month (`year`, `month` 1-12) in the calendar.

CSS parts

Link to “CSS parts”

Part	Description
`::part(actions)`	The text buttons row.
`::part(container)`	The picker surface.
`::part(field)`	The docked text field.
`::part(grid)`	The month grid.
`::part(header)`	The header (modal headline region, or docked menus).

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--anchor-spacing`	Docked: distance between the field and the calendar.
`--container-color`	Surface color.
`--container-elevation`	Surface shadow.
`--container-shape`	Surface corner radius.
`--container-width`	Surface width.
`--date-container-height`	Date indicator height.
`--date-container-shape`	Date indicator shape.
`--date-container-width`	Date indicator width.
`--date-disabled-label-text-color`	Disabled date color.
`--date-label-text`	Date typography.
`--date-selected-container-color`	Selected date indicator color.
`--date-selected-label-text-color`	Selected date color.
`--date-today-container-outline-color`	Today's outline color.
`--date-today-container-outline-width`	Today's outline width.
`--date-today-label-text-color`	Today's date color.
`--date-unselected-label-text-color`	Unselected date color.
`--date-unselected-outside-month-label-text-color`	Docked: adjacent month date color.
`--divider-color`	Divider color.
`--header-headline`	Modal headline typography.
`--header-headline-color`	Modal headline color.
`--header-supporting-text`	Modal supporting text typography.
`--header-supporting-text-color`	Modal supporting text color.
`--menu-button-label-text-color`	Month / year menu button color.
`--menu-list-item-selected-container-color`	Docked selected month / year color.
`--range-selection-active-indicator-container-color`	In-range highlight color.
`--range-selection-container-elevation`	Full-screen surface shadow.
`--range-selection-container-shape`	Full-screen surface corner radius.
`--range-selection-date-in-range-label-text-color`	In-range date color.
`--range-selection-header-container-height`	Full-screen header height.
`--range-selection-month-subhead`	Modal range: month subhead typography.
`--range-selection-month-subhead-color`	Modal range: month subhead color.
`--scrim-color`	Modal scrim color.
`--scrim-opacity`	Modal scrim opacity.
`--weekdays-label-text`	Weekday label typography.
`--weekdays-label-text-color`	Weekday label color.
`--year-selection-year-selected-container-color`	Selected year color.
`--year-selection-year-selected-label-text-color`	Selected year label color.
`--year-selection-year-unselected-label-text-color`	Unselected year color.