GitHubopen_in_new

DateRangePicker ​

DateRangePicker is a standalone surface for choosing a start and end date. By default it shows two consecutive months on wide viewports and falls back to one month on narrow or coarse-pointer viewports.

update:open(false) is emitted when the native popover closes. closed follows after the DateRangePicker-owned exit motion finishes. The current calendar view is preserved during the exit and reset afterward.

Density ​

DatePicker and DateRangePicker inherit --md-density. Date cells keep equal width and height, while calendar width, weekday rows, month/year lists and action spacing adapt to density. Narrow viewports constrain cells to the available column width. Explicit component dimension tokens take precedence.

Examples ​

Default ​

Constraints ​

Reference ​

Anatomy

ElementPartSelector
<div>
root
[data-scope="date-range-picker"][data-part="root"]
left_clickLMBCopy
<div>
surface
[data-scope="date-range-picker"][data-part="surface"]
left_clickLMBCopy
<div>
summary
[data-scope="date-range-picker"][data-part="summary"]
left_clickLMBCopy
<span>
prompt
[data-scope="date-range-picker"][data-part="prompt"]
left_clickLMBCopy
<div>
endpoints
[data-scope="date-range-picker"][data-part="endpoints"]
left_clickLMBCopy
<button>
start-selector
[data-scope="date-range-picker"][data-part="start-selector"]
left_clickLMBCopy
<span>
value
[data-scope="date-range-picker"][data-part="value"]
left_clickLMBCopy
<button>
end-selector
[data-scope="date-range-picker"][data-part="end-selector"]
left_clickLMBCopy
<div>
header
[data-scope="date-range-picker"][data-part="header"]
left_clickLMBCopy
<IconButton>
previous-month
[data-scope="date-range-picker"][data-part="previous-month"]
left_clickLMBCopy
<Button>
month-switch
[data-scope="date-range-picker"][data-part="month-switch"]
left_clickLMBCopy
<IconButton>
next-month
[data-scope="date-range-picker"][data-part="next-month"]
left_clickLMBCopy
<IconButton>
previous-year
[data-scope="date-range-picker"][data-part="previous-year"]
left_clickLMBCopy
<Button>
year-switch
[data-scope="date-range-picker"][data-part="year-switch"]
left_clickLMBCopy
<IconButton>
next-year
[data-scope="date-range-picker"][data-part="next-year"]
left_clickLMBCopy
<div>
calendarsconditional
[data-scope="date-range-picker"][data-part="calendars"]
left_clickLMBCopy
<section>
calendar-pane
[data-scope="date-range-picker"][data-part="calendar-pane"]
left_clickLMBCopy
<div>
calendar-title
[data-scope="date-range-picker"][data-part="calendar-title"]
left_clickLMBCopy
<div>
weekdays
[data-scope="date-range-picker"][data-part="weekdays"]
left_clickLMBCopy
<span>
weekday
[data-scope="date-range-picker"][data-part="weekday"]
left_clickLMBCopy
<div>
grid
[data-scope="date-range-picker"][data-part="grid"]
left_clickLMBCopy
<span>
day-cell
[data-scope="date-range-picker"][data-part="day-cell"]
left_clickLMBCopy
<button>
day
[data-scope="date-range-picker"][data-part="day"]
left_clickLMBCopy
<div>
months
[data-scope="date-range-picker"][data-part="months"]
left_clickLMBCopy
<button>
month
[data-scope="date-range-picker"][data-part="month"]
left_clickLMBCopy
<span>
list-icon
[data-scope="date-range-picker"][data-part="list-icon"]
left_clickLMBCopy
<span>
list-label
[data-scope="date-range-picker"][data-part="list-label"]
left_clickLMBCopy
<div>
years
[data-scope="date-range-picker"][data-part="years"]
left_clickLMBCopy
<button>
year
[data-scope="date-range-picker"][data-part="year"]
left_clickLMBCopy
<div>
actions
[data-scope="date-range-picker"][data-part="actions"]
left_clickLMBCopy

Props

NameDescriptionDefaultControl
shapeOptional

Corner style; inherits the shared shape default.

M3Shape | undefined
-
-
idOptional

Optional explicit id for the popover element.

string | undefined
undefined
-
variantOptional

Visual and positioning mode. Auto uses docked layout until a narrow/coarse pointer viewport.

DatePickerVariant | undefined
"auto"
-
calendarsOptional

Number of calendar months to show. Auto shows two months on wide viewports and one on narrow/coarse inputs.

DateRangePickerCalendars | undefined
"auto"
-
anchorNameOptional

CSS anchor name used to position the docked popover.

string | undefined
undefined
-
anchorElementOptional

Element passed to showPopover as the source for focus and dismissal semantics.

HTMLElement | undefined
undefined
-
ariaLabelOptional

Accessible label for the picker surface.

string | undefined
undefined
minOptional

Earliest selectable date, formatted as YYYY-MM-DD.

string | undefined
undefined
maxOptional

Latest selectable date, formatted as YYYY-MM-DD.

string | undefined
undefined
localeOptional

BCP 47 locale used for month, weekday, and date accessibility labels.

string | undefined
undefined
-
firstDayOfWeekOptional

First day of the week, where 0 is Sunday and 6 is Saturday.

0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined
undefined
-
confirmTextOptional

Text for the confirmation button.

string | undefined
undefined
cancelTextOptional

Text for the cancel button.

string | undefined
undefined
startTextOptional

Text used for the start side of the range.

string | undefined
undefined
endTextOptional

Text used for the end side of the range.

string | undefined
undefined
todayOptional

Date treated as today, formatted as YYYY-MM-DD. Useful for deterministic tests.

string | undefined
undefined
-
modelValueOptional

-

DateRangePickerModelValue
-
-
openOptional

-

boolean | undefined
false

Events6

NameTypeDescription
update:open[value: boolean]-
cancel[]-
closed[]-
update:modelValue[value: DateRangePickerModelValue]-
change[value: DateRangePickerModelValue]-
confirm[value: DateRangePickerModelValue]-

Styling5

TokenDescription
--md-date-range-picker-docked-container-widthLayout
Fallback45rem

Controls docked container width when two calendars are visible.

--md-date-range-picker-range-container-colorState
Fallbackvar(--md-sys-color-primary-container)

Controls selected range container color.

--md-date-range-picker-range-label-text-colorState
Fallbackvar(--md-sys-color-on-primary-container)

Controls selected range label text color.

--md-date-range-picker-summary-label-text-colorColor
Fallbackvar(--md-sys-color-primary)

Controls summary label text color.

--md-date-range-picker-summary-value-text-colorColor
Fallbackvar(--md-sys-color-on-surface)

Controls summary value text color.