API reference for Angular Material datepicker

import {MatDatepickerModule} from '@angular/material/datepicker';

Services

`DefaultMatCalendarRangeStrategy`

Provides the default date range selection behavior.

Methods

createPreview
Parameters
activeDate `D`
currentRange `DateRange<D>`

selectionFinished
Parameters
date `D`
currentRange `DateRange<D>`

`MatDatepickerIntl`

Datepicker data that requires internationalization.

Properties

Name	Description
`calendarLabel: string`	A label for the calendar popup (used by screen readers).
`changes: Subject<void>`	Stream that emits whenever the labels here are changed. Use this to notify components if the labels have changed after initialization.
`closeCalendarLabel: string`	Label for the button used to close the calendar popup.
`nextMonthLabel: string`	A label for the next month button (used by screen readers).
`nextMultiYearLabel: string`	A label for the next multi-year button (used by screen readers).
`nextYearLabel: string`	A label for the next year button (used by screen readers).
`openCalendarLabel: string`	A label for the button used to open the calendar popup (used by screen readers).
`prevMonthLabel: string`	A label for the previous month button (used by screen readers).
`prevMultiYearLabel: string`	A label for the previous multi-year button (used by screen readers).
`prevYearLabel: string`	A label for the previous year button (used by screen readers).
`switchToMonthViewLabel: string`	A label for the 'switch to month view' button (used by screen readers).
`switchToMultiYearViewLabel: string`	A label for the 'switch to year view' button (used by screen readers).

Methods

formatYearRange
Formats a range of years.
Parameters
start `string`
end `string`
Returns
`string`

Directives

`MatDatepickerInput`

Directive used to connect an input to a MatDatepicker.

Selector: input[matDatepicker]

Exported as: matDatepickerInput

Properties

Name	Description
@Input('matDatepickerFilter') `dateFilter: DateFilterFn<D>`	Function that can be used to filter out dates within the datepicker.
@Input() `disabled: boolean`	Whether the datepicker-input is disabled.
@Input() `matDatepicker: MatDatepickerPanel<MatDatepickerControl<D>, D, D>`	The datepicker that this input is associated with.
@Input() `max: D \| null`	The maximum valid date.
@Input() `min: D \| null`	The minimum valid date.
@Input() `value: D \| null`	The value of the input.
@Output() `dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>`	Emits when a `change` event is fired on this `<input>`.
@Output() `dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>`	Emits when an `input` event is fired on this `<input>`.
`stateChanges: Subject<void>`	Emits when the internal state has changed

Methods

getConnectedOverlayOrigin

getConnectedOverlayOrigin
Gets the element that the datepicker popup should be connected to.
`ElementRef`	The element to connect the popup to.

Gets the element that the datepicker popup should be connected to.

Returns

ElementRef

The element to connect the popup to.

getOverlayLabelId
Gets the ID of an element that should be used a description for the calendar overlay.
Returns
`string \| null`

getStartValue
Gets the value at which the calendar should start.
Returns
`D \| null`

getThemePalette
Returns the palette used by the input's form field, if any.
Returns
`ThemePalette`

`MatDateRangePicker`

Component responsible for managing the date range picker popup/dialog.

Selector: mat-date-range-picker

Exported as: matDateRangePicker

Properties

Name	Description
@Input() `calendarHeaderComponent: ComponentType<any>`	An input indicating the type of the custom header component for the calendar, if set.
@Input() `color: ThemePalette`	Color palette to use on the datepicker's calendar.
@Input() `dateClass: MatCalendarCellClassFunction<D>`	Function that can be used to add custom CSS classes to dates.
@Input() `disabled: boolean`	Whether the datepicker pop-up should be disabled.
@Input() `opened: boolean`	Whether the calendar is open.
@Input() `panelClass: string \| string[]`	Classes to be passed to the date picker panel. Supports string and string array values, similar to `ngClass`.
@Input() `restoreFocus: boolean`	Whether to restore focus to the previously-focused element when the calendar is closed. Note that automatic focus restoration is an accessibility feature and it is recommended that you provide your own equivalent, if you decide to turn it off.
@Input() `startAt: D \| null`	The date to open the calendar to initially.
@Input() `startView: 'month' \| 'year' \| 'multi-year'`	The view that the calendar should start in.
@Input() `touchUi: boolean`	Whether the calendar UI is in touch mode. In touch mode the calendar opens in a dialog rather than a dropdown and elements have more padding to allow for bigger touch targets.
@Input() `xPosition: DatepickerDropdownPositionX`	Preferred position of the datepicker in the X axis.
@Input() `yPosition: DatepickerDropdownPositionY`	Preferred position of the datepicker in the Y axis.
@Output('closed') `closedStream: EventEmitter<void>`	Emits when the datepicker has been closed.
@Output() `monthSelected: EventEmitter<D>`	Emits selected month in year view. This doesn't imply a change on the selected date.
@Output('opened') `openedStream: EventEmitter<void>`	Emits when the datepicker has been opened.
@Output() `viewChanged: EventEmitter<MatCalendarView>`	Emits when the current view changes.
@Output() `yearSelected: EventEmitter<D>`	Emits selected year in multiyear view. This doesn't imply a change on the selected date.
`datepickerInput: C`	The input element this datepicker is associated with.
`id: string`	The id for the datepicker calendar.
`stateChanges: Subject<void>`	Emits when the datepicker's state changes.

Methods

close
Close the calendar.

open
Open the calendar.

registerActions
Registers a portal containing action buttons with the datepicker.
Parameters
portal `TemplatePortal<any>`

registerInput
Register an input with this datepicker.
Parameters
input `C`
Returns
`MatDateSelectionModel<S, D>`	Selection model that the input should hook itself up to.

removeActions
Removes a portal containing action buttons from the datepicker.
Parameters
portal `TemplatePortal<any>`

select
Selects the given date
Parameters
date `D`

`MatStartDate`

Input for entering the start date in a mat-date-range-input.

Selector: input[matStartDate]

Properties

Name	Description
@Input() `disabled: boolean`	Whether the datepicker-input is disabled.
@Input() `errorStateMatcher: ErrorStateMatcher`	An object used to control the error state of the component.
@Input() `value: D \| null`	The value of the input.
@Output() `dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>`	Emits when a `change` event is fired on this `<input>`.
@Output() `dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>`	Emits when an `input` event is fired on this `<input>`.
`errorState: boolean`	Whether the component is in an error state.
`stateChanges: Subject<void>`	Emits whenever the component state changes.

Methods

focus
Focuses the input.

getMirrorValue
Gets the value that should be used when mirroring the input's size.
Returns
`string`

isEmpty
Gets whether the input is empty.
Returns
`boolean`

updateErrorState
Updates the error state based on the provided error state matcher.

`MatEndDate`

Input for entering the end date in a mat-date-range-input.

Selector: input[matEndDate]

Properties

Name	Description
@Input() `disabled: boolean`	Whether the datepicker-input is disabled.
@Input() `errorStateMatcher: ErrorStateMatcher`	An object used to control the error state of the component.
@Input() `value: D \| null`	The value of the input.
@Output() `dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>`	Emits when a `change` event is fired on this `<input>`.
@Output() `dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>`	Emits when an `input` event is fired on this `<input>`.
`errorState: boolean`	Whether the component is in an error state.
`stateChanges: Subject<void>`	Emits whenever the component state changes.

Methods

focus
Focuses the input.

isEmpty
Gets whether the input is empty.
Returns
`boolean`

updateErrorState
Updates the error state based on the provided error state matcher.

`MatCalendarHeader`

Default header for MatCalendar

Selector: mat-calendar-header

Exported as: matCalendarHeader

Properties

Name	Description
`calendar: MatCalendar<D>`
`nextButtonLabel: string`	The label for the next button.
`periodButtonLabel: string`
`periodButtonText: string`	The label for the current calendar view.
`prevButtonLabel: string`	The label for the previous button.

Methods

currentPeriodClicked
Handles user clicks on the period label.

nextClicked
Handles user clicks on the next button.

nextEnabled
Whether the next period button is enabled.
Returns
`boolean`

previousClicked
Handles user clicks on the previous button.

previousEnabled
Whether the previous period button is enabled.
Returns
`boolean`

`MatCalendar`

A calendar that is used as part of the datepicker.

Selector: mat-calendar

Exported as: matCalendar

Properties

Name	Description
@Input() `comparisonEnd: D \| null`	End of the comparison range.
@Input() `comparisonStart: D \| null`	Start of the comparison range.
@Input() `dateClass: MatCalendarCellClassFunction<D>`	Function that can be used to add custom CSS classes to dates.
@Input() `dateFilter: (date: D) => boolean`	Function used to filter which dates are selectable.
@Input() `headerComponent: ComponentType<any>`	An input indicating the type of the header component, if set.
@Input() `maxDate: D \| null`	The maximum selectable date.
@Input() `minDate: D \| null`	The minimum selectable date.
@Input() `selected: DateRange<D> \| D \| null`	The currently selected date.
@Input() `startAt: D \| null`	A date representing the period (month or year) to start the calendar in.
@Input() `startView: MatCalendarView`	Whether the calendar should be started in month or year view.
@Output() `monthSelected: EventEmitter<D>`	Emits the month chosen in year view. This doesn't imply a change on the selected date.
@Output() `selectedChange: EventEmitter<D \| null>`	Emits when the currently selected date changes.
@Output() `viewChanged: EventEmitter<MatCalendarView>`	Emits when the current view changes.
@Output() `yearSelected: EventEmitter<D>`	Emits the year chosen in multiyear view. This doesn't imply a change on the selected date.
`activeDate: D`	The current active date. This determines which time period is shown and which date is highlighted when using keyboard navigation.
`currentView: MatCalendarView`	Whether the calendar is in month view.
`monthView: MatMonthView<D>`	Reference to the current month view component.
`multiYearView: MatMultiYearView<D>`	Reference to the current multi-year view component.
`stateChanges: Subject<void>`	Emits whenever there is a state change that the header may need to respond to.
`yearView: MatYearView<D>`	Reference to the current year view component.

Methods

focusActiveCell
Focuses the active date.

updateTodaysDate
Updates today's date after an update of the active date

`MatDatepicker`

Component responsible for managing the datepicker popup/dialog.

Selector: mat-datepicker

Exported as: matDatepicker

Properties

Name	Description
@Input() `calendarHeaderComponent: ComponentType<any>`	An input indicating the type of the custom header component for the calendar, if set.
@Input() `color: ThemePalette`	Color palette to use on the datepicker's calendar.
@Input() `dateClass: MatCalendarCellClassFunction<D>`	Function that can be used to add custom CSS classes to dates.
@Input() `disabled: boolean`	Whether the datepicker pop-up should be disabled.
@Input() `opened: boolean`	Whether the calendar is open.
@Input() `panelClass: string \| string[]`	Classes to be passed to the date picker panel. Supports string and string array values, similar to `ngClass`.
@Input() `restoreFocus: boolean`	Whether to restore focus to the previously-focused element when the calendar is closed. Note that automatic focus restoration is an accessibility feature and it is recommended that you provide your own equivalent, if you decide to turn it off.
@Input() `startAt: D \| null`	The date to open the calendar to initially.
@Input() `startView: 'month' \| 'year' \| 'multi-year'`	The view that the calendar should start in.
@Input() `touchUi: boolean`	Whether the calendar UI is in touch mode. In touch mode the calendar opens in a dialog rather than a dropdown and elements have more padding to allow for bigger touch targets.
@Input() `xPosition: DatepickerDropdownPositionX`	Preferred position of the datepicker in the X axis.
@Input() `yPosition: DatepickerDropdownPositionY`	Preferred position of the datepicker in the Y axis.
@Output('closed') `closedStream: EventEmitter<void>`	Emits when the datepicker has been closed.
@Output() `monthSelected: EventEmitter<D>`	Emits selected month in year view. This doesn't imply a change on the selected date.
@Output('opened') `openedStream: EventEmitter<void>`	Emits when the datepicker has been opened.
@Output() `viewChanged: EventEmitter<MatCalendarView>`	Emits when the current view changes.
@Output() `yearSelected: EventEmitter<D>`	Emits selected year in multiyear view. This doesn't imply a change on the selected date.
`datepickerInput: C`	The input element this datepicker is associated with.
`id: string`	The id for the datepicker calendar.
`stateChanges: Subject<void>`	Emits when the datepicker's state changes.

Methods

close
Close the calendar.

open
Open the calendar.

registerActions
Registers a portal containing action buttons with the datepicker.
Parameters
portal `TemplatePortal<any>`

registerInput
Register an input with this datepicker.
Parameters
input `C`
Returns
`MatDateSelectionModel<S, D>`	Selection model that the input should hook itself up to.

removeActions
Removes a portal containing action buttons from the datepicker.
Parameters
portal `TemplatePortal<any>`

select
Selects the given date
Parameters
date `D`

`MatDatepickerToggleIcon`

Can be used to override the icon of a matDatepickerToggle.

Selector: [matDatepickerToggleIcon]

`MatDatepickerToggle`

Selector: mat-datepicker-toggle

Exported as: matDatepickerToggle

Properties

Name	Description
@Input('aria-label') `ariaLabel: string`	Screenreader label for the button.
@Input('for') `datepicker: MatDatepickerPanel<MatDatepickerControl<any>, D>`	Datepicker instance that the button will toggle.
@Input() `disableRipple: boolean`	Whether ripples on the toggle should be disabled.
@Input() `disabled: boolean`	Whether the toggle button is disabled.

`MatDateRangeInput`

Selector: mat-date-range-input

Exported as: matDateRangeInput

Properties

Name	Description
@Input() `comparisonEnd: D \| null`	End of the comparison range that should be shown in the calendar.
@Input() `comparisonStart: D \| null`	Start of the comparison range that should be shown in the calendar.
@Input() `dateFilter: DateFilterFn<D>`	Function that can be used to filter out dates within the date range picker.
@Input() `disabled: boolean`	Whether the input is disabled.
@Input() `max: D \| null`	The maximum valid date.
@Input() `min: D \| null`	The minimum valid date.
@Input() `rangePicker: MatDatepickerPanel<MatDatepickerControl<D>, DateRange<D>, D>`	The range picker that this input is associated with.
@Input() `required: boolean`	Whether the input is required.
@Input() `separator: '–'`	Separator text to be shown between the inputs.
`controlType: 'mat-date-range-input'`	Name of the form control.
`empty: boolean`	Whether the datepicker input is empty.
`errorState: boolean`	Whether the input is in an error state.
`focused: false`	Whether the control is focused.
id: `mat-date-range-input-${nextUniqueId++}`	Unique ID for the input.
`shouldLabelFloat: boolean`	Whether the control's label should float.
`stateChanges: Subject<void>`	Emits when the input's state has changed.
`value:`	Current value of the range input.

Methods

getConnectedOverlayOrigin
Gets the element to which the calendar overlay should be attached.
Returns
`ElementRef`

getOverlayLabelId
Gets the ID of an element that should be used a description for the calendar overlay.
Returns
`string \| null`

getStartValue
Gets the date at which the calendar should start.
Returns
`D \| null`

getThemePalette
Gets the input's theme palette.
Returns
`ThemePalette`

`MatDatepickerApply`

Button that will close the datepicker and assign the current selection to the data model.

Selector: [matDatepickerApply] [matDateRangePickerApply]

`MatDatepickerCancel`

Button that will close the datepicker and discard the current selection.

Selector: [matDatepickerCancel] [matDateRangePickerCancel]

`MatDatepickerActions`

Container that can be used to project a row of action buttons to the bottom of a datepicker or date range picker.

Selector: mat-datepicker-actions mat-date-range-picker-actions

Classes

`MatDatepickerInputEvent`

An event used for datepicker input and change events. We don't always have access to a native input or change event because the event may have been triggered by the user clicking on the calendar popup. For consistency, we always use MatDatepickerInputEvent instead.

Properties

Name	Description
`target: MatDatepickerInputBase<S, D>`	Reference to the datepicker input component that emitted the event.
`targetElement: HTMLElement`	Reference to the native input element associated with the datepicker input.
`value: D \| null`	The new value for the target datepicker input.

`DateRange`

A class representing a range of dates.

Properties

Name	Description
`end: D \| null`	The end date of the range.
`start: D \| null`	The start date of the range.

Interfaces

`MatDateRangeSelectionStrategy`

Object that can be provided in order to customize the date range selection behavior.

Methods

createPreview
Called when the user has activated a new date (e.g. by hovering over it or moving focus) and the calendar tries to display a date range.
Parameters
activeDate `D`
currentRange `DateRange<D>`
event `Event`
Returns
`DateRange<D>`

selectionFinished
Called when the user has finished selecting a value.
Parameters
date `D`
currentRange `DateRange<D>`
event `Event`
Returns
`DateRange<D>`

`MatCalendarUserEvent`

Event emitted when a date inside the calendar is triggered as a result of a user action.

Properties

Name	Description
`event: Event`
`value: D`

Type aliases

`DatepickerDropdownPositionX`

Possible positions for the datepicker dropdown along the X axis.

type DatepickerDropdownPositionX = 'start' | 'end';

`DatepickerDropdownPositionY`

Possible positions for the datepicker dropdown along the Y axis.

type DatepickerDropdownPositionY = 'above' | 'below';

`DateFilterFn`

Function that can be used to filter out dates from a calendar.

type DateFilterFn = (date: D | null) => boolean;

`MatCalendarCellCssClasses`

Extra CSS classes that can be associated with a calendar cell.

type MatCalendarCellCssClasses = string | string[] | Set<string> | {
    [key: string]: any;
};

`MatCalendarCellClassFunction`

Function that can generate the extra classes that should be added to a calendar cell.

type MatCalendarCellClassFunction = (date: D, view: 'month' | 'year' | 'multi-year') => MatCalendarCellCssClasses;

Constants

`MAT_DATE_RANGE_SELECTION_STRATEGY`

Injection token used to customize the date range selection behavior.

const MAT_DATE_RANGE_SELECTION_STRATEGY: InjectionToken<MatDateRangeSelectionStrategy<any>>;

`MAT_DATEPICKER_SCROLL_STRATEGY`

Injection token that determines the scroll handling while the calendar is open.

const MAT_DATEPICKER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;

`yearsPerPage`

const yearsPerPage: 24;

`yearsPerRow`

const yearsPerRow: 4;