Datepicker

API for datepicker

API reference for Angular Material datepicker

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

Provides the default date range selection behavior.

Methods
createPreview
Parameters

activeDate

D

currentRange

DateRange<D>

selectionFinished
Parameters

date

D

currentRange

DateRange<D>

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.

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

A selection model that contains a single date.

Properties
Name Description

selection: S

The current selection.

selectionChanged: Observable<DateSelectionModelChange<S>>

Emits when the selection has changed.

Methods
add

Adds a date to the current selection. In the case of a single date selection, the added date simply overwrites the previous selection

Parameters

date

D

isComplete

Checks whether the current selection is complete. In the case of a single date selection, this is true if the current selection is not null.

isValid

Checks whether the current selection is valid.

Returns
boolean

updateSelection

Updates the current selection in the model.

Parameters

value

S

New selection that should be assigned.

source

unknown

Object that triggered the selection change.

A selection model that contains a date range.

Properties
Name Description

selection: S

The current selection.

selectionChanged: Observable<DateSelectionModelChange<S>>

Emits when the selection has changed.

Methods
add

Adds a date to the current selection. In the case of a date range selection, the added date fills in the next null value in the range. If both the start and the end already have a date, the selection is reset so that the given date is the new start and the end is null.

Parameters

date

D

isComplete

Checks whether the current selection is complete. In the case of a date range selection, this is true if the current selection has a non-null start and end.

Returns
boolean

isValid

Checks whether the current selection is valid.

Returns
boolean

updateSelection

Updates the current selection in the model.

Parameters

value

S

New selection that should be assigned.

source

unknown

Object that triggered the selection change.

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

@Input()

matDatepicker: MatDatepicker<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

@Output()

dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>

@Output()

dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>

stateChanges: Subject<void>

Methods
getConnectedOverlayOrigin

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

Returns
ElementRef

The element to connect the popup to.

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

registerOnValidatorChange
Parameters

fn

() => void

validate
Parameters

c

AbstractControl

Returns
ValidationErrors | null

Deprecated
getPopupConnectionElementRef
Returns
ElementRef

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>

@Input()

color: ThemePalette

@Input()

dateClass: MatCalendarCellClassFunction<D>

@Input()

disabled: boolean

@Input()

opened: boolean

@Input()

panelClass: string | string[]

@Input()

startAt: D | null

@Input()

startView: 'month' | 'year' | 'multi-year'

@Input()

touchUi: boolean

@Input()

xPosition: DatepickerDropdownPositionX

@Input()

yPosition: DatepickerDropdownPositionY

@Output('closed')

closedStream: EventEmitter<void>

@Output()

monthSelected: EventEmitter<D>

@Output('opened')

openedStream: EventEmitter<void>

@Output()

yearSelected: EventEmitter<D>

id: string

Methods
close
open
select
Parameters

date

D

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

Selector: input[matStartDate]

Properties
Name Description
@Input()

disabled: boolean

@Input()

value: D | null

@Output()

dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>

@Output()

dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>

errorState: boolean

errorStateMatcher: ErrorStateMatcher

ngControl: NgControl

stateChanges: Subject<void>

Methods
focus
getMirrorValue

Gets the value that should be used when mirroring the input's size.

Returns
string

isEmpty
Returns
boolean

registerOnValidatorChange
Parameters

fn

() => void

updateErrorState
validate
Parameters

c

AbstractControl

Returns
ValidationErrors | null

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

Selector: input[matEndDate]

Properties
Name Description
@Input()

disabled: boolean

@Input()

value: D | null

@Output()

dateChange: EventEmitter<MatDatepickerInputEvent<D, S>>

@Output()

dateInput: EventEmitter<MatDatepickerInputEvent<D, S>>

errorState: boolean

errorStateMatcher: ErrorStateMatcher

ngControl: NgControl

stateChanges: Subject<void>

Methods
focus
isEmpty
Returns
boolean

registerOnValidatorChange
Parameters

fn

() => void

updateErrorState
validate
Parameters

c

AbstractControl

Returns
ValidationErrors | null

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

Component responsible for managing the datepicker popup/dialog.

Selector: mat-datepicker

Exported as: matDatepicker
Properties
Name Description
@Input()

calendarHeaderComponent: ComponentType<any>

@Input()

color: ThemePalette

@Input()

dateClass: MatCalendarCellClassFunction<D>

@Input()

disabled: boolean

@Input()

opened: boolean

@Input()

panelClass: string | string[]

@Input()

startAt: D | null

@Input()

startView: 'month' | 'year' | 'multi-year'

@Input()

touchUi: boolean

@Input()

xPosition: DatepickerDropdownPositionX

@Input()

yPosition: DatepickerDropdownPositionY

@Output('closed')

closedStream: EventEmitter<void>

@Output()

monthSelected: EventEmitter<D>

@Output('opened')

openedStream: EventEmitter<void>

@Output()

yearSelected: EventEmitter<D>

id: string

Methods
close
open
select
Parameters

date

D

Can be used to override the icon of a matDatepickerToggle.

Selector: [matDatepickerToggleIcon]

Selector: mat-datepicker-toggle

Exported as: matDatepickerToggle
Properties
Name Description
@Input('for')

datepicker: MatDatepickerBase<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.

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: MatDateRangePicker<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

getStartValue

Gets the date at which the calendar should start.

Returns
D | null

getThemePalette

Gets the input's theme palette.

Returns
ThemePalette

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.

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.

A selection model containing a date selection.

Properties
Name Description

selection: S

The current selection.

selectionChanged: Observable<DateSelectionModelChange<S>>

Emits when the selection has changed.

Methods
add

Adds a date to the current selection.

Parameters

date

D

isComplete

Checks whether the current selection is complete.

Returns
boolean

isValid

Checks whether the current selection is valid.

Returns
boolean

updateSelection

Updates the current selection in the model.

Parameters

value

S

New selection that should be assigned.

source

unknown

Object that triggered the selection change.

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

Date that the user has activated. Will be null if the user moved focus to an element that's no a calendar cell.

currentRange

DateRange<D>

Range that is currently shown in the calendar.

event

Event

DOM event that caused the preview to be changed. Will be either a mouseenter/mouseleave or focus/blur depending on how the user is navigating.

Returns
DateRange<D>

selectionFinished

Called when the user has finished selecting a value.

Parameters

date

D

Date that was selected. Will be null if the user cleared the selection.

currentRange

DateRange<D>

Range that is currently show in the calendar.

event

Event

DOM event that triggered the selection. Currently only corresponds to a click event, but it may get expanded in the future.

Returns
DateRange<D>

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

Properties
Name Description

event: Event

value: D

Event emitted by the date selection model when its selection changes.

Properties
Name Description

selection: S

New value for the selection.

source: unknown

Object that triggered the change.

Possible positions for the datepicker dropdown along the X axis.

type DatepickerDropdownPositionX = 'start' | 'end';

Possible positions for the datepicker dropdown along the Y axis.

type DatepickerDropdownPositionY = 'above' | 'below';

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

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

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

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

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;

Injection token used to customize the date range selection behavior.

const MAT_DATE_RANGE_SELECTION_STRATEGY: InjectionToken<MatDateRangeSelectionStrategy<any>>;

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

const MAT_DATEPICKER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
const yearsPerPage: 24;
const yearsPerRow: 4;

Used to provide a single selection model to a component.

const MAT_SINGLE_DATE_SELECTION_MODEL_PROVIDER: FactoryProvider;

Used to provide a range selection model to a component.

const MAT_RANGE_DATE_SELECTION_MODEL_PROVIDER: FactoryProvider;

API reference for Angular Material datepicker-testing

import {MatDatepickerInputHarness} from '@angular/material/datepicker/testing';

Harness for interacting with a standard Material datepicker inputs in tests.

Methods
blur
Returns
Promise<void>

async
closeCalendar

Closes the calendar associated with the input.

Returns
Promise<void>

Promise that resolves when the action completes.

focus
Returns
Promise<void>

async
getCalendar

Gets the MatCalendarHarness that is associated with the trigger.

Parameters

filter

CalendarHarnessFilters = {}

Optionally filters which calendar is included.

Returns
Promise<MatCalendarHarness>

getMax
Returns
Promise<string | null>

getMin
Returns
Promise<string | null>

getPlaceholder
Returns
Promise<string>

getValue
Returns
Promise<string>

async
hasCalendar

Whether a calendar is associated with the input.

Returns
Promise<boolean>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isCalendarOpen

Gets whether the calendar associated with the input is open.

Returns
Promise<boolean>

isDisabled
Returns
Promise<boolean>

isFocused
Returns
Promise<boolean>

isRequired
Returns
Promise<boolean>

async
openCalendar

Opens the calendar associated with the input.

Returns
Promise<void>

Promise that resolves when the action completes.

setValue
Parameters

newValue

string

Returns
Promise<void>

Harness for interacting with a standard Material datepicker toggle in tests.

Methods
closeCalendar
Returns
Promise<void>

getCalendar
Parameters

filter

CalendarHarnessFilters = {}

Returns
Promise<MatCalendarHarness>

hasCalendar
Returns
Promise<boolean>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isCalendarOpen

Gets whether the calendar associated with the toggle is open.

Returns
Promise<boolean>

async
isDisabled

Whether the toggle is disabled.

Returns
Promise<boolean>

openCalendar
Returns
Promise<void>

Harness for interacting with a standard Material date range start input in tests.

Methods
blur
Returns
Promise<void>

focus
Returns
Promise<void>

getMax
Returns
Promise<string | null>

getMin
Returns
Promise<string | null>

getPlaceholder
Returns
Promise<string>

getValue
Returns
Promise<string>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

isDisabled
Returns
Promise<boolean>

isFocused
Returns
Promise<boolean>

isRequired
Returns
Promise<boolean>

setValue
Parameters

newValue

string

Returns
Promise<void>

Harness for interacting with a standard Material date range end input in tests.

Methods
blur
Returns
Promise<void>

focus
Returns
Promise<void>

getMax
Returns
Promise<string | null>

getMin
Returns
Promise<string | null>

getPlaceholder
Returns
Promise<string>

getValue
Returns
Promise<string>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

isDisabled
Returns
Promise<boolean>

isFocused
Returns
Promise<boolean>

isRequired
Returns
Promise<boolean>

setValue
Parameters

newValue

string

Returns
Promise<void>

Harness for interacting with a standard Material date range input in tests.

Methods
closeCalendar
Returns
Promise<void>

getCalendar
Parameters

filter

CalendarHarnessFilters = {}

Returns
Promise<MatCalendarHarness>

async
getEndInput

Gets the inner start date input inside the range input.

Returns
Promise<MatEndDateHarness>

async
getSeparator

Gets the separator text between the values of the two inputs.

Returns
Promise<string>

async
getStartInput

Gets the inner start date input inside the range input.

Returns
Promise<MatStartDateHarness>

async
getValue

Gets the combined value of the start and end inputs, including the separator.

Returns
Promise<string>

hasCalendar
Returns
Promise<boolean>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isCalendarOpen

Opens the calendar associated with the input.

Returns
Promise<boolean>

async
isDisabled

Gets whether the range input is disabled.

Returns
Promise<boolean>

async
isRequired

Gets whether the range input is required.

Returns
Promise<boolean>

openCalendar
Returns
Promise<void>

Harness for interacting with a standard Material calendar in tests.

Methods
async
changeView

Changes the calendar view by clicking on the view toggle button.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getCells

Gets a list of cells inside the calendar.

Parameters

filter

CalendarCellHarnessFilters = {}

Optionally filters which cells are included.

Returns
Promise<MatCalendarCellHarness[]>

async
getCurrentView

Gets the current view that is being shown inside the calendar.

Returns
Promise<CalendarView>

async
getCurrentViewLabel

Gets the label of the current calendar view.

Returns
Promise<string>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
next

Goes to the next page of the current view (e.g. next month when inside the month view).

Returns
Promise<void>

Promise that resolves when the action completes.

async
previous

Goes to the previous page of the current view (e.g. previous month when inside the month view).

Returns
Promise<void>

Promise that resolves when the action completes.

async
selectCell

Selects a cell in the current calendar view.

Parameters

filter

CalendarCellHarnessFilters = {}

An optional filter to apply to the cells. The first cell matching the filter will be selected.

Returns
Promise<void>

Promise that resolves when the action completes.

Harness for interacting with a standard Material calendar cell in tests.

Methods
async
blur

Removes focus from the calendar cell.

Returns
Promise<void>

Promise that resolves when the action completes.

async
focus

Focuses the calendar cell.

Returns
Promise<void>

Promise that resolves when the action completes.

async
getAriaLabel

Gets the aria-label of the calendar cell.

Returns
Promise<string>

async
getText

Gets the text of the calendar cell.

Returns
Promise<string>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
hover

Hovers over the calendar cell.

Returns
Promise<void>

Promise that resolves when the action completes.

async
isActive

Whether the cell is currently activated using keyboard navigation.

Returns
Promise<boolean>

async
isComparisonRangeEnd

Whether the cell is the end of the comparison range.

Returns
Promise<boolean>

async
isComparisonRangeStart

Whether the cell is the start of the comparison range.

Returns
Promise<boolean>

async
isDisabled

Whether the cell is disabled.

Returns
Promise<boolean>

async
isInComparisonRange

Whether the cell is inside of the comparison range.

Returns
Promise<boolean>

async
isInPreviewRange

Whether the cell is inside of the preview range.

Returns
Promise<boolean>

async
isInRange

Whether the cell is part of the main range.

Returns
Promise<boolean>

async
isPreviewRangeEnd

Whether the cell is the end of the preview range.

Returns
Promise<boolean>

async
isPreviewRangeStart

Whether the cell is the start of the preview range.

Returns
Promise<boolean>

async
isRangeEnd

Whether the cell is the end of the main range.

Returns
Promise<boolean>

async
isRangeStart

Whether the cell is the start of the main range.

Returns
Promise<boolean>

async
isSelected

Whether the cell is selected.

Returns
Promise<boolean>

async
isToday

Whether the cell represents today's date.

Returns
Promise<boolean>

async
mouseAway

Moves the mouse away from the calendar cell.

Returns
Promise<void>

Promise that resolves when the action completes.

async
select

Selects the calendar cell. Won't do anything if the cell is disabled.

Returns
Promise<void>

Promise that resolves when the action completes.

A set of criteria that can be used to filter a list of datepicker input instances.

Properties
Name Description

placeholder: string | RegExp

Filters based on the placeholder text of the input.

value: string | RegExp

Filters based on the value of the input.

A set of criteria that can be used to filter a list of datepicker toggle instances.

A set of criteria that can be used to filter a list of calendar instances.

A set of criteria that can be used to filter a list of calendar cell instances.

Properties
Name Description

active: boolean

Filters based on whether the cell is activated using keyboard navigation

disabled: boolean

Filters based on whether the cell is disabled.

inComparisonRange: boolean

Filters based on whether the cell is inside of the comparison range.

inPreviewRange: boolean

Filters based on whether the cell is inside of the preview range.

inRange: boolean

Filters based on whether the cell is inside of the main range.

selected: boolean

Filters based on whether the cell is selected.

text: string | RegExp

Filters based on the text of the cell.

today: boolean

Filters based on whether the cell represents today's date.

A set of criteria that can be used to filter a list of date range input instances.

Properties
Name Description

value: string | RegExp

Filters based on the value of the input.