Skip to main content

​
Overview

The <mat-datepicker> allows users to enter a date either through text input or by choosing a date from the calendar. It is made up of several components and directives that work together.

​
Basic Usage

import { Component } from '@angular/core';
import { MatDatepickerModule } from '@angular/material/datepicker';
import { MatNativeDateModule } from '@angular/material/core';
import { MatFormFieldModule } from '@angular/material/form-field';
import { MatInputModule } from '@angular/material/input';

@Component({
  selector: 'app-datepicker-example',
  standalone: true,
  imports: [
    MatFormFieldModule,
    MatInputModule,
    MatDatepickerModule,
    MatNativeDateModule
  ],
  template: `
    <mat-form-field>
      <mat-label>Choose a date</mat-label>
      <input matInput [matDatepicker]="picker">
      <mat-datepicker-toggle matIconSuffix [for]="picker"></mat-datepicker-toggle>
      <mat-datepicker #picker></mat-datepicker>
    </mat-form-field>
  `
})
export class DatepickerExample {}

​
API Reference

​
MatDatepicker

Selector: mat-datepicker Exported as: matDatepicker

​
Inputs

​
startAt
D | null
default:"null"
The date to open the calendar to initially.
​
startView
'month' | 'year' | 'multi-year'
default:"'month'"
The view that the calendar should start in.
​
color
ThemePalette
Theme color of the datepicker’s calendar. This API is supported in M2 themes only.
​
touchUi
boolean
default:"false"
Whether the calendar UI is in touch mode. In touch mode the calendar opens in a dialog rather than a dropdown.
​
disabled
boolean
default:"false"
Whether the datepicker pop-up should be disabled.
​
xPosition
'start' | 'end'
default:"'start'"
Preferred position of the datepicker in the X axis.
​
yPosition
'above' | 'below'
default:"'below'"
Preferred position of the datepicker in the Y axis.
​
restoreFocus
boolean
default:"true"
Whether to restore focus to the previously-focused element when the calendar is closed.
​
dateClass
MatCalendarCellClassFunction<D>
Function that can be used to add custom CSS classes to dates.
​
panelClass
string | string[]
Classes to be passed to the date picker panel.
​
opened
boolean
default:"false"
Whether the calendar is open.
​
calendarHeaderComponent
ComponentType<any>
An input indicating the type of the custom header component for the calendar, if set.

​
Outputs

​
yearSelected
EventEmitter<D>
Emits selected year in multiyear view. This doesn’t imply a change on the selected date.
​
monthSelected
EventEmitter<D>
Emits selected month in year view. This doesn’t imply a change on the selected date.
​
viewChanged
EventEmitter<MatCalendarView>
Emits when the current view changes.
​
opened
EventEmitter<void>
Emits when the datepicker has been opened.
​
closed
EventEmitter<void>
Emits when the datepicker has been closed.

​
Methods

​
open()
void
Opens the calendar.
​
close()
void
Closes the calendar.
​
select(date: D)
void
Selects the given date.
​
registerInput(input: C)
MatDateSelectionModel<S, D>
Registers an input with this datepicker.

​
Date Range Selection

<mat-form-field>
  <mat-label>Enter a date range</mat-label>
  <mat-date-range-input [rangePicker]="picker">
    <input matStartDate placeholder="Start date">
    <input matEndDate placeholder="End date">
  </mat-date-range-input>
  <mat-datepicker-toggle matIconSuffix [for]="picker"></mat-datepicker-toggle>
  <mat-date-range-picker #picker></mat-date-range-picker>
</mat-form-field>

​
Accessibility

  • The datepicker input uses role="combobox" with appropriate ARIA attributes
  • The calendar dialog uses role="dialog" and is properly labeled
  • Full keyboard navigation support:
    • ALT + DOWN_ARROW: Open the calendar
    • ESCAPE: Close the calendar
    • ARROW KEYS: Navigate between dates
    • PAGE_UP/PAGE_DOWN: Navigate between months
    • ENTER: Select the currently focused date
  • Screen readers announce the selected date and navigation actions
  • Use aria-label on the datepicker toggle for better accessibility

​
Advanced Usage

​
Custom Date Formats

import { MAT_DATE_FORMATS } from '@angular/material/core';

export const MY_DATE_FORMATS = {
  parse: {
    dateInput: 'DD/MM/YYYY',
  },
  display: {
    dateInput: 'DD/MM/YYYY',
    monthYearLabel: 'MMM YYYY',
    dateA11yLabel: 'LL',
    monthYearA11yLabel: 'MMMM YYYY',
  },
};

@Component({
  providers: [
    {provide: MAT_DATE_FORMATS, useValue: MY_DATE_FORMATS}
  ]
})
export class DatepickerFormatsExample {}

​
Min and Max Dates

<mat-form-field>
  <input matInput [matDatepicker]="picker" [min]="minDate" [max]="maxDate">
  <mat-datepicker #picker></mat-datepicker>
</mat-form-field>

​
Date Validation

<mat-form-field>
  <input matInput [matDatepicker]="picker" [matDatepickerFilter]="myFilter">
  <mat-datepicker #picker></mat-datepicker>
</mat-form-field>

myFilter = (d: Date | null): boolean => {
  const day = (d || new Date()).getDay();
  // Prevent Saturday and Sunday from being selected.
  return day !== 0 && day !== 6;
};

​
Touch UI Mode

For mobile devices, use touch UI mode: 
<mat-datepicker touchUi="true"></mat-datepicker>

Build docs developers (and LLMs) love

Get started for freeTalk to us