datepicker.html

<div class="docs-markdown"><p>The 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, directives and <a href="#choosing-a-date-implementation-and-date-format-settings">the date implementation module</a> that work together.</p>
<div material-docs-example="datepicker-overview"></div>


        <h3 id="connecting-a-datepicker-to-an-input" class="docs-header-link">
          <span header-link="connecting-a-datepicker-to-an-input"></span>
          Connecting a datepicker to an input
        </h3>
      <p>A datepicker is composed of a text input and a calendar pop-up, connected via the <code>matDatepicker</code>
property on the text input.</p>
<p>There is also an optional datepicker toggle button that gives the user an easy way to open the datepicker pop-up.</p>
<div material-docs-example="datepicker-overview"
                             file="datepicker-overview-example.html"
                             region="toggle"></div>

<p>This works exactly the same with an input that is part of an <code>&lt;mat-form-field&gt;</code> and the toggle
can easily be used as a prefix or suffix on the Material input:</p>
<div material-docs-example="datepicker-overview"
                             file="datepicker-overview-example.html"
                             ></div>

<p>If you want to customize the icon that is rendered inside the <code>mat-datepicker-toggle</code>, you can do so
by using the <code>matDatepickerToggleIcon</code> directive:</p>
<div material-docs-example="datepicker-custom-icon"></div>


        <h3 id="date-range-selection" class="docs-header-link">
          <span header-link="date-range-selection"></span>
          Date range selection
        </h3>
      <p>If you want your users to select a range of dates, instead of a single date, you can use the
<code>mat-date-range-input</code> and <code>mat-date-range-picker</code> components. They work in tandem, similarly to the
<code>mat-datepicker</code> and the basic datepicker input.</p>
<p>The <code>mat-date-range-input</code> component requires two <code>input</code> elements for the start and end dates,
respectively:</p>
<pre><code class="language-html"><span class="hljs-tag">&lt;<span class="hljs-name">mat-date-range-input</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">matStartDate</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">&quot;Start date&quot;</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">matEndDate</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">&quot;End date&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">mat-date-range-input</span>&gt;</span>
</code></pre>
<p>The <code>mat-date-range-picker</code> component acts as the pop-up panel for selecting dates. This works in
the same way as <code>mat-datepicker</code>, but allows the user to select multiple times:</p>
<pre><code class="language-html"><span class="hljs-tag">&lt;<span class="hljs-name">mat-date-range-picker</span> #<span class="hljs-attr">picker</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">mat-date-range-picker</span>&gt;</span>
</code></pre>
<p>Connect the range picker and range input using the <code>rangePicker</code> property:</p>
<pre><code class="language-html"><span class="hljs-tag">&lt;<span class="hljs-name">mat-date-range-input</span> [<span class="hljs-attr">rangePicker</span>]=<span class="hljs-string">&quot;picker&quot;</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">matStartDate</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">&quot;Start date&quot;</span>&gt;</span>
  <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">matEndDate</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">&quot;End date&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;/<span class="hljs-name">mat-date-range-input</span>&gt;</span>

<span class="hljs-tag">&lt;<span class="hljs-name">mat-date-range-picker</span> #<span class="hljs-attr">picker</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">mat-date-range-picker</span>&gt;</span>
</code></pre>
<div material-docs-example="date-range-picker-overview"></div>


        <h3 id="date-range-input-forms-integration" class="docs-header-link">
          <span header-link="date-range-input-forms-integration"></span>
          Date range input forms integration
        </h3>
      <p>The <code>mat-date-range-input</code> component can be used together with the <code>FormGroup</code> directive from
<code>@angular/forms</code> to group the start and end values together and to validate them as a group.</p>
<div material-docs-example="date-range-picker-forms"></div>


        <h3 id="setting-the-calendar-starting-view" class="docs-header-link">
          <span header-link="setting-the-calendar-starting-view"></span>
          Setting the calendar starting view
        </h3>
      <p>The <code>startView</code> property of <code>&lt;mat-datepicker&gt;</code> can be used to set the view that will show up when
the calendar first opens. It can be set to <code>month</code>, <code>year</code>, or <code>multi-year</code>; by default it will open
to month view.</p>
<p>The month, year, or range of years that the calendar opens to is determined by first checking if any
date is currently selected, if so it will open to the month or year containing that date. Otherwise
it will open to the month or year containing today&#39;s date. This behavior can be overridden by using
the <code>startAt</code> property of <code>&lt;mat-datepicker&gt;</code>. In this case the calendar will open to the month or
year containing the <code>startAt</code> date.</p>
<div material-docs-example="datepicker-start-view"></div>


        <h4 id="watching-the-views-for-changes-on-selected-years-and-months" class="docs-header-link">
          <span header-link="watching-the-views-for-changes-on-selected-years-and-months"></span>
          Watching the views for changes on selected years and months
        </h4>
      <p>When a year or a month is selected in <code>multi-year</code> and <code>year</code> views respectively, the <code>yearSelected</code>
and <code>monthSelected</code> outputs emit a normalized date representing the chosen year or month. By
&quot;normalized&quot; we mean that the dates representing years will have their month set to January and
their day set to the 1st. Dates representing months will have their day set to the 1st of the
month. For example, if <code>&lt;mat-datepicker&gt;</code> is configured to work with javascript native Date
objects, the <code>yearSelected</code> will emit <code>new Date(2017, 0, 1)</code> if the user selects 2017 in
<code>multi-year</code> view. Similarly, <code>monthSelected</code> will emit <code>new Date(2017, 1, 1)</code> if the user
selects <strong>February</strong> in <code>year</code> view and the current date value of the connected <code>&lt;input&gt;</code> was
set to something like <code>new Date(2017, MM, dd)</code> when the calendar was opened (the month and day are
irrelevant in this case).</p>
<p>Notice that the emitted value does not affect the current value in the connected <code>&lt;input&gt;</code>, which
is only bound to the selection made in the <code>month</code> view. So if the end user closes the calendar
after choosing a year in <code>multi-view</code> mode (by pressing the <code>ESC</code> key, for example), the selected
year, emitted by <code>yearSelected</code> output, will not cause any change in the value of the date in the
associated <code>&lt;input&gt;</code>.</p>
<p>The following example uses <code>yearSelected</code> and <code>monthSelected</code> outputs to emulate a month and year
picker (if you&#39;re not familiar with the usage of <code>MomentDateAdapter</code> and <code>MAT_DATE_FORMATS</code>
you can <a href="#choosing-a-date-implementation-and-date-format-settings">read more about them</a> below in
this document to fully understand the example).</p>
<div material-docs-example="datepicker-views-selection"></div>


        <h3 id="setting-the-selected-date" class="docs-header-link">
          <span header-link="setting-the-selected-date"></span>
          Setting the selected date
        </h3>
      <p>The type of values that the datepicker expects depends on the type of <code>DateAdapter</code> provided in your
application. The <code>NativeDateAdapter</code>, for example, works directly with plain JavaScript <code>Date</code>
objects. When using the <code>MomentDateAdapter</code>, however, the values will all be Moment.js instances.
This use of the adapter pattern allows the datepicker component to work with any arbitrary date
representation with a custom <code>DateAdapter</code>.
See <a href="#choosing-a-date-implementation-and-date-format-settings"><em>Choosing a date implementation</em></a>
for more information.</p>
<p>Depending on the <code>DateAdapter</code> being used, the datepicker may automatically deserialize certain date
formats for you as well. For example, both the <code>NativeDateAdapter</code> and <code>MomentDateAdapter</code> allow
<a href="https://tools.ietf.org/html/rfc3339">ISO 8601</a> strings to be passed to the datepicker and
automatically converted to the proper object type. This can be convenient when binding data directly
from your backend to the datepicker. However, the datepicker will not accept date strings formatted
in user format such as <code>&quot;1/2/2017&quot;</code> as this is ambiguous and will mean different things depending on
the locale of the browser running the code.</p>
<p>As with other types of <code>&lt;input&gt;</code>, the datepicker works with <code>@angular/forms</code> directives such as
<code>formGroup</code>, <code>formControl</code>, <code>ngModel</code>, etc.</p>
<div material-docs-example="datepicker-value"></div>


        <h3 id="changing-the-datepicker-colors" class="docs-header-link">
          <span header-link="changing-the-datepicker-colors"></span>
          Changing the datepicker colors
        </h3>
      <p>The datepicker popup will automatically inherit the color palette (<code>primary</code>, <code>accent</code>, or <code>warn</code>)
from the <code>mat-form-field</code> it is attached to. If you would like to specify a different palette for
the popup you can do so by setting the <code>color</code> property on <code>mat-datepicker</code>.</p>
<div material-docs-example="datepicker-color"></div>


        <h3 id="date-validation" class="docs-header-link">
          <span header-link="date-validation"></span>
          Date validation
        </h3>
      <p>There are three properties that add date validation to the datepicker input. The first two are the
<code>min</code> and <code>max</code> properties. In addition to enforcing validation on the input, these properties will
disable all dates on the calendar popup before or after the respective values and prevent the user
from advancing the calendar past the <code>month</code> or <code>year</code> (depending on current view) containing the
<code>min</code> or <code>max</code> date.</p>
<div material-docs-example="datepicker-min-max"></div>

<p>The second way to add date validation is using the <code>matDatepickerFilter</code> property of the datepicker
input. This property accepts a function of <code>&lt;D&gt; =&gt; boolean</code> (where <code>&lt;D&gt;</code> is the date type used by
the datepicker, see
<a href="#choosing-a-date-implementation-and-date-format-settings"><em>Choosing a date implementation</em></a>).
A result of <code>true</code> indicates that the date is valid and a result of <code>false</code> indicates that it is
not. Again this will also disable the dates on the calendar that are invalid. However, one important
difference between using <code>matDatepickerFilter</code> vs using <code>min</code> or <code>max</code> is that filtering out all
dates before or after a certain point, will not prevent the user from advancing the calendar past
that point.</p>
<div material-docs-example="datepicker-filter"></div>

<p>In this example the user cannot select any date that falls on a Saturday or Sunday, but all of the 
dates which fall on other days of the week are selectable.</p>
<p>Each validation property has a different error that can be checked:</p>
<ul>
<li>A value that violates the <code>min</code> property will have a <code>matDatepickerMin</code> error.</li>
<li>A value that violates the <code>max</code> property will have a <code>matDatepickerMax</code> error.</li>
<li>A value that violates the <code>matDatepickerFilter</code> property will have a <code>matDatepickerFilter</code> error.</li>
</ul>

        <h3 id="input-and-change-events" class="docs-header-link">
          <span header-link="input-and-change-events"></span>
          Input and change events
        </h3>
      <p>The input&#39;s native <code>(input)</code> and <code>(change)</code> events will only trigger due to user interaction with
the input element; they will not fire when the user selects a date from the calendar popup.
Therefore, the datepicker input also has support for <code>(dateInput)</code> and <code>(dateChange)</code> events. These
trigger when the user interacts with either the input or the popup.</p>
<p>The <code>(dateInput)</code> event will fire whenever the value changes due to the user typing or selecting a
date from the calendar. The <code>(dateChange)</code> event will fire whenever the user finishes typing input
(on <code>&lt;input&gt;</code> blur), or when the user chooses a date from the calendar.</p>
<div material-docs-example="datepicker-events"></div>


        <h3 id="disabling-parts-of-the-datepicker" class="docs-header-link">
          <span header-link="disabling-parts-of-the-datepicker"></span>
          Disabling parts of the datepicker
        </h3>
      <p>As with any standard <code>&lt;input&gt;</code>, it is possible to disable the datepicker input by adding the
<code>disabled</code> property. By default, the <code>&lt;mat-datepicker&gt;</code> and <code>&lt;mat-datepicker-toggle&gt;</code> will inherit
their disabled state from the <code>&lt;input&gt;</code>, but this can be overridden by setting the <code>disabled</code>
property on the datepicker or toggle elements. This can be useful if you want to disable text input
but allow selection via the calendar or vice-versa.</p>
<div material-docs-example="datepicker-disabled"></div>


        <h3 id="confirmation-action-buttons" class="docs-header-link">
          <span header-link="confirmation-action-buttons"></span>
          Confirmation action buttons
        </h3>
      <p>By default, clicking on a date in the calendar will select it and close the calendar popup. In some
cases this may not be desirable, because the user doesn&#39;t have a quick way of going back if they&#39;ve
changed their mind. If you want your users to be able to cancel their selection and to have to
explicitly accept the value that they&#39;ve selected, you can add a <code>&lt;mat-datepicker-actions&gt;</code> element
inside <code>&lt;mat-datepicker&gt;</code> with a &quot;Cancel&quot; and an &quot;Apply&quot; button marked with the
<code>matDatepickerCancel</code> and <code>matDatepickerApply</code> attributes respectively. Doing so will cause the
datepicker to only assign the value to the data model if the user presses &quot;Apply&quot;, whereas pressing
&quot;Cancel&quot; will close popup without changing the value.</p>
<div material-docs-example="datepicker-actions"
                             file="datepicker-actions-example.html"
                             region="datepicker-actions"></div>

<p>The actions element is also supported for <code>&lt;mat-date-range-picker&gt;</code> where that it is called
<code>&lt;mat-date-range-picker-actions&gt;</code> and the buttons are called <code>matDateRangePickerCancel</code> and
<code>matDateRangePickerApply</code> respectively.</p>
<div material-docs-example="datepicker-actions"
                             file="datepicker-actions-example.html"
                             region="date-range-picker-actions"></div>

<div material-docs-example="datepicker-actions"></div>


        <h3 id="comparison-ranges" class="docs-header-link">
          <span header-link="comparison-ranges"></span>
          Comparison ranges
        </h3>
      <p>If your users need to compare the date range that they&#39;re currently selecting with another range,
you can provide the comparison range start and end dates to the <code>mat-date-range-input</code> using the
<code>comparisonStart</code> and <code>comparisonEnd</code> bindings. The comparison range will be rendered statically
within the calendar, but it will change colors to indicate which dates overlap with the user&#39;s
selected range.</p>
<div material-docs-example="date-range-picker-comparison"></div>

<p>Note that comparison and overlap colors aren&#39;t derived from the current theme, due
to limitations in the Material Design theming system. They can be customized using the
<code>datepicker-date-range-colors</code> mixin.</p>
<pre><code class="language-scss"><span class="hljs-keyword">@use</span> <span class="hljs-string">&#x27;@angular/material&#x27;</span> as mat;

<span class="hljs-keyword">@include</span> mat.datepicker-date-range-colors(
  hotpink, teal, yellow, purple);
</code></pre>

        <h3 id="customizing-the-date-selection-logic" class="docs-header-link">
          <span header-link="customizing-the-date-selection-logic"></span>
          Customizing the date selection logic
        </h3>
      <p>The <code>mat-date-range-picker</code> supports custom behaviors for range previews and selection. To customize
this, you first create a class that implements <code>MatDateRangeSelectionStrategy</code>, and then provide
the class via the <code>MAT_DATE_RANGE_SELECTION_STRATEGY</code> injection token. The following example
uses the range selection strategy to create a custom range picker that limits the user to five-day
ranges.</p>
<div material-docs-example="date-range-picker-selection-strategy"></div>


        <h3 id="touch-ui-mode" class="docs-header-link">
          <span header-link="touch-ui-mode"></span>
          Touch UI mode
        </h3>
      <p>The datepicker normally opens as a popup under the input. However this is not ideal for touch
devices that don&#39;t have as much screen real estate and need bigger click targets. For this reason
<code>&lt;mat-datepicker&gt;</code> has a <code>touchUi</code> property that can be set to <code>true</code> in order to enable a more
touch friendly UI where the calendar opens in a large dialog.</p>
<div material-docs-example="datepicker-touch"></div>


        <h3 id="manually-opening-and-closing-the-calendar" class="docs-header-link">
          <span header-link="manually-opening-and-closing-the-calendar"></span>
          Manually opening and closing the calendar
        </h3>
      <p>The calendar popup can be programmatically controlled using the <code>open</code> and <code>close</code> methods on the
<code>&lt;mat-datepicker&gt;</code>. It also has an <code>opened</code> property that reflects the status of the popup.</p>
<div material-docs-example="datepicker-api"></div>


        <h3 id="using-mat-calendar-inline" class="docs-header-link">
          <span header-link="using-mat-calendar-inline"></span>
          Using <code>mat-calendar</code> inline
        </h3>
      <p>If you want to allow the user to select a date from a calendar that is inlined on the page rather
than contained in a popup, you can use <code>&lt;mat-calendar&gt;</code> directly. The calendar&#39;s height is
determined automatically based on the width and the number of dates that need to be shown for a
month. If you want to make the calendar larger or smaller, adjust the width rather than the height.</p>
<div material-docs-example="datepicker-inline-calendar"></div>


        <h3 id="internationalization" class="docs-header-link">
          <span header-link="internationalization"></span>
          Internationalization
        </h3>
      <p>Internationalization of the datepicker is configured via four aspects:</p>
<ol>
<li>The date locale.</li>
<li>The date implementation that the datepicker accepts.</li>
<li>The display and parse formats used by the datepicker.</li>
<li>The message strings used in the datepicker&#39;s UI.</li>
</ol>

        <h4 id="setting-the-locale-code" class="docs-header-link">
          <span header-link="setting-the-locale-code"></span>
          Setting the locale code
        </h4>
      <p>By default, the <code>MAT_DATE_LOCALE</code> injection token will use the existing <code>LOCALE_ID</code> locale code
from <code>@angular/core</code>. If you want to override it, you can provide a new value for the
<code>MAT_DATE_LOCALE</code> token:</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">providers</span>: [
    {<span class="hljs-attr">provide</span>: MAT_DATE_LOCALE, <span class="hljs-attr">useValue</span>: <span class="hljs-string">&#x27;en-GB&#x27;</span>},
  ],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyApp</span> </span>{}
</code></pre>
<p>It&#39;s also possible to set the locale at runtime using the <code>setLocale</code> method of the <code>DateAdapter</code>.</p>
<p><strong>Note:</strong> if you&#39;re using the <code>MatDateFnsModule</code>, you have to provide the data object for your
locale to <code>MAT_DATE_LOCALE</code> instead of the locale code, in addition to providing a configuration
compatible with <code>date-fns</code> to <code>MAT_DATE_FORMATS</code>. Locale data for <code>date-fns</code> can be imported
from <code>date-fns/locale</code>.</p>
<div material-docs-example="datepicker-locale"></div>


        <h4 id="choosing-a-date-implementation-and-date-format-settings" class="docs-header-link">
          <span header-link="choosing-a-date-implementation-and-date-format-settings"></span>
          Choosing a date implementation and date format settings
        </h4>
      <p>The datepicker was built to be date implementation agnostic. This means that it can be made to work
with a variety of different date implementations. However it also means that developers need to make
sure to provide the appropriate pieces for the datepicker to work with their chosen implementation.</p>
<p>The easiest way to ensure this is to import one of the provided date modules:</p>
<p><code>MatNativeDateModule</code></p>
<table>
  <tbody>
    <tr>
      <th align="left" scope="row">Date type</th>
      <td><code>Date</code></td>
    </tr>
    <tr>
      <th align="left" scope="row">Supported locales</th>
      <td>en-US</td>
    </tr>
    <tr>
      <th align="left" scope="row">Dependencies</th>
      <td>None</td>
    </tr>
    <tr>
      <th align="left" scope="row">Import from</th>
      <td><code>@angular/material/core</code></td>
    </tr>
  </tbody>
</table>

<p><code>MatDateFnsModule</code> (installed separately via <code class="language-bash">npm --install @angular/material-date-fns-adapter</code>)</p>
<table>
  <tbody>
    <tr>
      <th align="left" scope="row">Date type</th>
      <td><code>Date</code></td>
    </tr>
    <tr>
      <th align="left" scope="row">Supported locales</th>
      <td><a href="https://github.com/date-fns/date-fns/tree/master/src/locale/">See project for details</a></td>
    </tr>
    <tr>
      <th align="left" scope="row">Dependencies</th>
      <td><a href="https://date-fns.org/">date-fns</a></td>
    </tr>
    <tr>
      <th align="left" scope="row">Import from</th>
      <td><code>@angular/material-date-fns-adapter</code></td>
    </tr>
  </tbody>
</table>

<p><code>MatLuxonDateModule</code> (installed separately via <code class="language-bash">npm --install @angular/material-luxon-adapter</code>)</p>
<table>
  <tbody>
    <tr>
      <th align="left" scope="row">Date type</th>
      <td><code>DateTime</code></td>
    </tr>
    <tr>
      <th align="left" scope="row">Supported locales</th>
      <td><a href="https://moment.github.io/luxon/">See project for details</a></td>
    </tr>
    <tr>
      <th align="left" scope="row">Dependencies</th>
      <td><a href="https://moment.github.io/luxon/">Luxon</a></td>
    </tr>
    <tr>
      <th align="left" scope="row">Import from</th>
      <td><code>@angular/material-luxon-adapter</code></td>
    </tr>
  </tbody>
</table>

<p><code>MatMomentDateModule</code> (installed separately via <code class="language-bash">npm --install @angular/material-moment-adapter</code>)</p>
<table>
  <tbody>
    <tr>
      <th align="left" scope="row">Date type</th>
      <td><code>Moment</code></td>
    </tr>
    <tr>
      <th align="left" scope="row">Supported locales</th>
      <td><a href="https://github.com/moment/moment/tree/develop/src/locale">See project for details</a></td>
    </tr>
    <tr>
      <th align="left" scope="row">Dependencies</th>
      <td><a href="https://momentjs.com/">Moment.js</a></td>
    </tr>
    <tr>
      <th align="left" scope="row">Import from</th>
      <td><code>@angular/material-moment-adapter</code></td>
    </tr>
  </tbody>
</table>

<p><em>Please note: <code>MatNativeDateModule</code> is based off the functionality available in JavaScript&#39;s
native <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date"><code>Date</code> object</a>.
Thus it is not suitable for many locales. One of the biggest shortcomings of the native <code>Date</code>
object is the inability to set the parse format. We strongly recommend using an adapter based on
a more robust formatting and parsing library. You can use the <code>MomentDateAdapter</code>
or a custom <code>DateAdapter</code> that works with the library of your choice.</em></p>
<p>These modules include providers for <code>DateAdapter</code> and <code>MAT_DATE_FORMATS</code>.</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule, MatNativeDateModule],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyApp</span> </span>{}
</code></pre>
<p>Because <code>DateAdapter</code> is a generic class, <code>MatDatepicker</code> and <code>MatDatepickerInput</code> also need to be
made generic. When working with these classes (for example as a <code>ViewChild</code>) you should include the
appropriate generic type that corresponds to the <code>DateAdapter</code> implementation you are using. For
example:</p>
<pre><code class="language-ts"><span class="hljs-meta">@Component</span>({...})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyComponent</span> </span>{
  <span class="hljs-meta">@ViewChild</span>(MatDatepicker) datepicker: MatDatepicker&lt;<span class="hljs-built_in">Date</span>&gt;;
}
</code></pre>
<div material-docs-example="datepicker-moment"></div>

<p>By default the <code>MomentDateAdapter</code> creates dates in your time zone specific locale. You can change the default behaviour to parse dates as UTC by providing the <code>MAT_MOMENT_DATE_ADAPTER_OPTIONS</code> and setting it to <code>useUtc: true</code>.</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule, MatMomentDateModule],
  <span class="hljs-attr">providers</span>: [
    {<span class="hljs-attr">provide</span>: MAT_MOMENT_DATE_ADAPTER_OPTIONS, <span class="hljs-attr">useValue</span>: {<span class="hljs-attr">useUtc</span>: <span class="hljs-literal">true</span>}}
  ]
})
</code></pre>
<p>By default the <code>MomentDateAdapter</code> will parse dates in a
<a href="https://momentjs.com/guides/#/parsing/forgiving-mode/">forgiving way</a>. This may result in dates
being parsed incorrectly. You can change the default behaviour to
<a href="https://momentjs.com/guides/#/parsing/strict-mode/">parse dates strictly</a> by providing
the <code>MAT_MOMENT_DATE_ADAPTER_OPTIONS</code> and setting it to <code>strict: true</code>.</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule, MatMomentDateModule],
  <span class="hljs-attr">providers</span>: [
    {<span class="hljs-attr">provide</span>: MAT_MOMENT_DATE_ADAPTER_OPTIONS, <span class="hljs-attr">useValue</span>: {<span class="hljs-attr">strict</span>: <span class="hljs-literal">true</span>}}
  ]
})
</code></pre>
<p>It is also possible to create your own <code>DateAdapter</code> that works with any date format your app
requires. This is accomplished by subclassing <code>DateAdapter</code> and providing your subclass as the
<code>DateAdapter</code> implementation. You will also want to make sure that the <code>MAT_DATE_FORMATS</code> provided
in your app are formats that can be understood by your date implementation. See
<a href="#customizing-the-parse-and-display-formats"><em>Customizing the parse and display formats</em></a> for more
information about <code>MAT_DATE_FORMATS</code>.</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule],
  <span class="hljs-attr">providers</span>: [
    {<span class="hljs-attr">provide</span>: DateAdapter, <span class="hljs-attr">useClass</span>: MyDateAdapter},
    {<span class="hljs-attr">provide</span>: MAT_DATE_FORMATS, <span class="hljs-attr">useValue</span>: MY_DATE_FORMATS},
  ],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyApp</span> </span>{}
</code></pre>
<p>If you need to work with native <code>Date</code> objects, but need custom behavior (for example custom date
parsing), you can consider subclassing <code>NativeDateAdapter</code>.</p>

        <h4 id="customizing-the-parse-and-display-formats" class="docs-header-link">
          <span header-link="customizing-the-parse-and-display-formats"></span>
          Customizing the parse and display formats
        </h4>
      <p>The <code>MAT_DATE_FORMATS</code> object is a collection of formats that the datepicker uses when parsing
and displaying dates. These formats are passed through to the <code>DateAdapter</code> so you will want to make
sure that the format objects you&#39;re using are compatible with the <code>DateAdapter</code> used in your app.</p>
<p>If you want use one of the <code>DateAdapters</code> that ships with Angular Material, but use your own
<code>MAT_DATE_FORMATS</code>, you can import the <code>NativeDateModule</code> or <code>MomentDateModule</code>. These modules are
identical to the &quot;Mat&quot;-prefixed versions (<code>MatNativeDateModule</code> and <code>MatMomentDateModule</code>) except
they do not include the default formats. For example:</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule, NativeDateModule],
  <span class="hljs-attr">providers</span>: [
    {<span class="hljs-attr">provide</span>: MAT_DATE_FORMATS, <span class="hljs-attr">useValue</span>: MY_NATIVE_DATE_FORMATS},
  ],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyApp</span> </span>{}
</code></pre>
<div material-docs-example="datepicker-formats"></div>


        <h5 id="momentdatemodule-formats" class="docs-header-link">
          <span header-link="momentdatemodule-formats"></span>
          MomentDateModule formats
        </h5>
      <p>To use custom formats with the <code>MomentDateModule</code> you can pick from the parse formats documented
<a href="https://momentjs.com/docs/#/parsing/string-format/">here</a> and the display formats documented
<a href="https://momentjs.com/docs/#/displaying/format/">here</a>.</p>
<p>It is also possible to support multiple parse formats. For example:</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule, MomentDateModule],
  <span class="hljs-attr">providers</span>: [
    {
      <span class="hljs-attr">provide</span>: MAT_DATE_FORMATS,
      <span class="hljs-attr">useValue</span>: {
        <span class="hljs-attr">parse</span>: {
          <span class="hljs-attr">dateInput</span>: [<span class="hljs-string">&#x27;l&#x27;</span>, <span class="hljs-string">&#x27;LL&#x27;</span>],
        },
        <span class="hljs-attr">display</span>: {
          <span class="hljs-attr">dateInput</span>: <span class="hljs-string">&#x27;L&#x27;</span>,
          <span class="hljs-attr">monthYearLabel</span>: <span class="hljs-string">&#x27;MMM YYYY&#x27;</span>,
          <span class="hljs-attr">dateA11yLabel</span>: <span class="hljs-string">&#x27;LL&#x27;</span>,
          <span class="hljs-attr">monthYearA11yLabel</span>: <span class="hljs-string">&#x27;MMMM YYYY&#x27;</span>,
        },
      },
    },
  ],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyApp</span> </span>{}
</code></pre>

        <h4 id="customizing-the-calendar-header" class="docs-header-link">
          <span header-link="customizing-the-calendar-header"></span>
          Customizing the calendar header
        </h4>
      <p>The header section of the calendar (the part containing the view switcher and previous and next
buttons) can be replaced with a custom component if desired. This is accomplished using the
<code>calendarHeaderComponent</code> property of <code>&lt;mat-datepicker&gt;</code>. It takes a component class and constructs
an instance of the component to use as the header.</p>
<p>In order to interact with the calendar in your custom header component, you can inject the parent
<code>MatCalendar</code> in the constructor. To make sure your header stays in sync with the calendar,
subscribe to the <code>stateChanges</code> observable of the calendar and mark your header component for change
detection.</p>
<div material-docs-example="datepicker-custom-header"></div>


        <h4 id="localizing-labels-and-messages" class="docs-header-link">
          <span header-link="localizing-labels-and-messages"></span>
          Localizing labels and messages
        </h4>
      <p>The various text strings used by the datepicker are provided through <code>MatDatepickerIntl</code>.
Localization of these messages can be done by providing a subclass with translated values in your
application root module.</p>
<pre><code class="language-ts"><span class="hljs-meta">@NgModule</span>({
  <span class="hljs-attr">imports</span>: [MatDatepickerModule, MatNativeDateModule],
  <span class="hljs-attr">providers</span>: [
    {<span class="hljs-attr">provide</span>: MatDatepickerIntl, <span class="hljs-attr">useClass</span>: MyIntl},
  ],
})
<span class="hljs-keyword">export</span> <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">MyApp</span> </span>{}
</code></pre>

        <h4 id="highlighting-specific-dates" class="docs-header-link">
          <span header-link="highlighting-specific-dates"></span>
          Highlighting specific dates
        </h4>
      <p>If you want to apply one or more CSS classes to some dates in the calendar (e.g. to highlight a
holiday), you can do so with the <code>dateClass</code> input. It accepts a function which will be called
with each of the dates in the calendar and will apply any classes that are returned. The return
value can be anything that is accepted by <code>ngClass</code>.</p>
<div material-docs-example="datepicker-date-class"></div>


        <h3 id="accessibility" class="docs-header-link">
          <span header-link="accessibility"></span>
          Accessibility
        </h3>
      <p>The <code>MatDatepicker</code> pop-up uses the <code>role=&quot;dialog&quot;</code> interaction pattern. This dialog then contains
multiple controls, the most prominent being the calendar itself. This calendar implements the
<code>role=&quot;grid&quot;</code> interaction pattern.</p>
<p>Always enable <a href="#confirmation-action-buttons"><em>confirmation action buttons</em></a>. This allows assistive
technology users to explicitly confirm their selection before committing a value.</p>
<p>The <code>MatDatepickerInput</code> and <code>MatDatepickerToggle</code> directives both apply the <code>aria-haspopup</code>
attribute to the native input and button elements, respectively.</p>
<p><code>MatDatepickerIntl</code> includes strings that are used for <code>aria-label</code> attributes. Always provide
the datepicker text input a meaningful label via <code>&lt;mat-label&gt;</code>, <code>aria-label</code>, <code>aria-labelledby</code> or
<code>MatDatepickerIntl</code>.</p>
<p>Always communicate the date format (e.g. &#39;MM/DD/YYYY&#39;). This can be accomplished using <code>&lt;mat-hint&gt;</code>
or by providing an additional label adjacent to the form field.</p>
<p><code>MatDatepickerInput</code> adds <kbd>>Alt</kbd> + <kbd>Down Arrow</kbd> as a keyboard short to open the
datepicker pop-up. However, ChromeOS intercepts this key combination at the OS level such that the
browser only receives a <code>PageDown</code> key event. Because of this behavior, you should always include an
additional means of opening the pop-up, such as <code>MatDatepickerToggle</code>.</p>

        <h4 id="keyboard-interaction" class="docs-header-link">
          <span header-link="keyboard-interaction"></span>
          Keyboard interaction
        </h4>
      <p>The datepicker supports the following keyboard shortcuts:</p>
<table>
<thead>
<tr>
<th>Keyboard Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody><tr>
<td><kbd>Alt</kbd> + <kbd>Down Arrow</kbd></td>
<td>Open the calendar pop-up</td>
</tr>
<tr>
<td><kbd>Escape</kbd></td>
<td>Close the calendar pop-up</td>
</tr>
</tbody></table>
<p>In month view:</p>
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody><tr>
<td><kbd>Left Arrow</kbd></td>
<td>Go to previous day</td>
</tr>
<tr>
<td><kbd>Right Arrow</kbd></td>
<td>Go to next day</td>
</tr>
<tr>
<td><kbd>Up Arrow</kbd></td>
<td>Go to same day in the previous week</td>
</tr>
<tr>
<td><kbd>Down Arrow</kbd></td>
<td>Go to same day in the next week</td>
</tr>
<tr>
<td><kbd>Home</kbd></td>
<td>Go to the first day of the month</td>
</tr>
<tr>
<td><kbd>End</kbd></td>
<td>Go to the last day of the month</td>
</tr>
<tr>
<td><kbd>Page up</kbd></td>
<td>Go to the same day in the previous month</td>
</tr>
<tr>
<td><kbd>Alt</kbd> + <kbd>Page up</kbd></td>
<td>Go to the same day in the previous year</td>
</tr>
<tr>
<td><kbd>Page Down</kbd></td>
<td>Go to the same day in the next month</td>
</tr>
<tr>
<td><kbd>Alt</kbd> + <kbd>Page Down</kbd></td>
<td>Go to the same day in the next year</td>
</tr>
<tr>
<td><kbd>Enter</kbd></td>
<td>Select current date</td>
</tr>
</tbody></table>
<p>In year view:</p>
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody><tr>
<td><kbd>Left Arrow</kbd></td>
<td>Go to previous month</td>
</tr>
<tr>
<td><kbd>Right Arrow</kbd></td>
<td>Go to next month</td>
</tr>
<tr>
<td><kbd>Up Arrow</kbd></td>
<td>Go up a row (back 4 months)</td>
</tr>
<tr>
<td><kbd>Down Arrow</kbd></td>
<td>Go down a row (forward 4 months)</td>
</tr>
<tr>
<td><kbd>Home</kbd></td>
<td>Go to the first month of the year</td>
</tr>
<tr>
<td><kbd>End</kbd></td>
<td>Go to the last month of the year</td>
</tr>
<tr>
<td><kbd>Page Up</kbd></td>
<td>Go to the same month in the previous year</td>
</tr>
<tr>
<td><kbd>Alt</kbd> + <kbd>Page up</kbd></td>
<td>Go to the same month 10 years back</td>
</tr>
<tr>
<td><kbd>Page Down</kbd></td>
<td>Go to the same month in the next year</td>
</tr>
<tr>
<td><kbd>Alt</kbd> + <kbd>Page Down</kbd></td>
<td>Go to the same month 10 years forward</td>
</tr>
<tr>
<td><kbd>Enter</kbd></td>
<td>Select current month</td>
</tr>
</tbody></table>
<p>In multi-year view:</p>
<table>
<thead>
<tr>
<th>Shortcut</th>
<th>Action</th>
</tr>
</thead>
<tbody><tr>
<td><kbd>Left Arrow</kbd></td>
<td>Go to previous year</td>
</tr>
<tr>
<td><kbd>Right Arrow</kbd></td>
<td>Go to next year</td>
</tr>
<tr>
<td><kbd>Up Arrow</kbd></td>
<td>Go up a row (back 4 years)</td>
</tr>
<tr>
<td><kbd>Down Arrow</kbd></td>
<td>Go down a row (forward 4 years)</td>
</tr>
<tr>
<td><kbd>Home</kbd></td>
<td>Go to the first year in the current range</td>
</tr>
<tr>
<td><kbd>End</kbd></td>
<td>Go to the last year in the current range</td>
</tr>
<tr>
<td><kbd>Page up</kbd></td>
<td>Go back 24 years</td>
</tr>
<tr>
<td><kbd>Alt</kbd> + <kbd>Page up</kbd></td>
<td>Go back 240 years</td>
</tr>
<tr>
<td><kbd>Page Down</kbd></td>
<td>Go forward 24 years</td>
</tr>
<tr>
<td><kbd>Alt</kbd> + <kbd>Page Down</kbd></td>
<td>Go forward 240 years</td>
</tr>
<tr>
<td><kbd>Enter</kbd></td>
<td>Select current year</td>
</tr>
</tbody></table>

        <h3 id="troubleshooting" class="docs-header-link">
          <span header-link="troubleshooting"></span>
          Troubleshooting
        </h3>
      
        <h4 id="error-matdatepicker-no-provider-found-for-dateadaptermat_date_formats" class="docs-header-link">
          <span header-link="error-matdatepicker-no-provider-found-for-dateadaptermat_date_formats"></span>
          Error: MatDatepicker: No provider found for DateAdapter/MAT_DATE_FORMATS
        </h4>
      <p>This error is thrown if you have not provided all of the injectables the datepicker needs to work.
The easiest way to resolve this is to import the <code>MatNativeDateModule</code> or <code>MatMomentDateModule</code> in
your application&#39;s root module. See
<a href="#choosing-a-date-implementation-and-date-format-settings"><em>Choosing a date implementation</em></a>) for
more information.</p>

        <h4 id="error-a-matdatepicker-can-only-be-associated-with-a-single-input" class="docs-header-link">
          <span header-link="error-a-matdatepicker-can-only-be-associated-with-a-single-input"></span>
          Error: A MatDatepicker can only be associated with a single input
        </h4>
      <p>This error is thrown if more than one <code>&lt;input&gt;</code> tries to claim ownership over the same
<code>&lt;mat-datepicker&gt;</code> (via the <code>matDatepicker</code> attribute on the input). A datepicker can only be
associated with a single input.</p>

        <h4 id="error-attempted-to-open-an-matdatepicker-with-no-associated-input" class="docs-header-link">
          <span header-link="error-attempted-to-open-an-matdatepicker-with-no-associated-input"></span>
          Error: Attempted to open an MatDatepicker with no associated input.
        </h4>
      <p>This error occurs if your <code>&lt;mat-datepicker&gt;</code> is not associated with any <code>&lt;input&gt;</code>. To associate an
input with your datepicker, create a template reference for the datepicker and assign it to the
<code>matDatepicker</code> attribute on the input:</p>
<pre><code class="language-html"><span class="hljs-tag">&lt;<span class="hljs-name">input</span> [<span class="hljs-attr">matDatepicker</span>]=<span class="hljs-string">&quot;picker&quot;</span>&gt;</span>
<span class="hljs-tag">&lt;<span class="hljs-name">mat-datepicker</span> #<span class="hljs-attr">picker</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">mat-datepicker</span>&gt;</span>
</code></pre>
</div>