From c6a7aaaa1584509cd4a0a480dc105fac524c52e2 Mon Sep 17 00:00:00 2001
From: Zach Arend <zachzach@google.com>
Date: Mon, 28 Mar 2022 19:56:04 +0000
Subject: [PATCH] docs(material/datepicker): require communicating date format
 for a11y

In the accessibility section of the datepicker documentation, require communicating the date format
string (e.g. 'MM/DD/YYYY'). Update datepicker examples to show the date format string via
`<mat-hint>` and use 'en-US' as the locale.

This commit only changes examples and does not affect source code.

Addresses #11127
---
 .../date-range-picker-comparison-example.html |  2 ++
 .../date-range-picker-forms-example.html      |  1 +
 .../date-range-picker-overview-example.html   |  1 +
 ...nge-picker-selection-strategy-example.html |  1 +
 .../datepicker-actions-example.html           |  2 ++
 .../datepicker-api-example.html               |  1 +
 .../datepicker-color-example.html             |  2 ++
 .../datepicker-custom-header-example.html     |  1 +
 .../datepicker-custom-icon-example.html       |  1 +
 .../datepicker-date-class-example.html        |  1 +
 .../datepicker-disabled-example.html          |  3 +++
 .../datepicker-events-example.html            |  1 +
 .../datepicker-filter-example.html            |  1 +
 .../datepicker-formats-example.html           |  1 +
 .../datepicker-locale-example.html            |  2 +-
 .../datepicker-locale-example.ts              | 19 ++++++++++++++++---
 .../datepicker-min-max-example.html           |  1 +
 .../datepicker-moment-example.html            |  1 +
 .../datepicker-overview-example.html          |  1 +
 .../datepicker-start-view-example.html        |  1 +
 .../datepicker-touch-example.html             |  1 +
 .../datepicker-value-example.html             |  3 +++
 .../datepicker-views-selection-example.html   |  1 +
 .../material/datepicker/index.ts              |  8 +++++++-
 src/material/datepicker/datepicker.md         |  3 +++
 25 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/src/components-examples/material/datepicker/date-range-picker-comparison/date-range-picker-comparison-example.html b/src/components-examples/material/datepicker/date-range-picker-comparison/date-range-picker-comparison-example.html
index c6f6adda28ab..3203d2965de6 100644
--- a/src/components-examples/material/datepicker/date-range-picker-comparison/date-range-picker-comparison-example.html
+++ b/src/components-examples/material/datepicker/date-range-picker-comparison/date-range-picker-comparison-example.html
@@ -8,6 +8,7 @@
     <input matStartDate placeholder="Start date" formControlName="start">
     <input matEndDate placeholder="End date" formControlName="end">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="campaignOnePicker"></mat-datepicker-toggle>
   <mat-date-range-picker #campaignOnePicker></mat-date-range-picker>
 </mat-form-field>
@@ -23,5 +24,6 @@
     <input matEndDate placeholder="End date" formControlName="end">
   </mat-date-range-input>
   <mat-datepicker-toggle matSuffix [for]="campaignTwoPicker"></mat-datepicker-toggle>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-date-range-picker #campaignTwoPicker></mat-date-range-picker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/date-range-picker-forms/date-range-picker-forms-example.html b/src/components-examples/material/datepicker/date-range-picker-forms/date-range-picker-forms-example.html
index 3eb5eab449a8..44bbc438b05a 100644
--- a/src/components-examples/material/datepicker/date-range-picker-forms/date-range-picker-forms-example.html
+++ b/src/components-examples/material/datepicker/date-range-picker-forms/date-range-picker-forms-example.html
@@ -4,6 +4,7 @@
     <input matStartDate formControlName="start" placeholder="Start date">
     <input matEndDate formControlName="end" placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-date-range-picker #picker></mat-date-range-picker>
 
diff --git a/src/components-examples/material/datepicker/date-range-picker-overview/date-range-picker-overview-example.html b/src/components-examples/material/datepicker/date-range-picker-overview/date-range-picker-overview-example.html
index d74c95161364..4e1be94ff692 100644
--- a/src/components-examples/material/datepicker/date-range-picker-overview/date-range-picker-overview-example.html
+++ b/src/components-examples/material/datepicker/date-range-picker-overview/date-range-picker-overview-example.html
@@ -4,6 +4,7 @@
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-date-range-picker #picker></mat-date-range-picker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/date-range-picker-selection-strategy/date-range-picker-selection-strategy-example.html b/src/components-examples/material/datepicker/date-range-picker-selection-strategy/date-range-picker-selection-strategy-example.html
index d74c95161364..4e1be94ff692 100644
--- a/src/components-examples/material/datepicker/date-range-picker-selection-strategy/date-range-picker-selection-strategy-example.html
+++ b/src/components-examples/material/datepicker/date-range-picker-selection-strategy/date-range-picker-selection-strategy-example.html
@@ -4,6 +4,7 @@
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-date-range-picker #picker></mat-date-range-picker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html b/src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html
index e536b2a4bd89..5bfc980e4a58 100644
--- a/src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html
+++ b/src/components-examples/material/datepicker/datepicker-actions/datepicker-actions-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill" class="example-form-field">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="datepicker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="datepicker"></mat-datepicker-toggle>
 <!-- #docregion datepicker-actions -->
   <mat-datepicker #datepicker>
@@ -18,6 +19,7 @@
     <input matStartDate placeholder="Start date">
     <input matEndDate placeholder="End date">
   </mat-date-range-input>
+  <mat-hint>MM/DD/YYYY – MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="rangePicker"></mat-datepicker-toggle>
 <!-- #docregion date-range-picker-actions -->
   <mat-date-range-picker #rangePicker>
diff --git a/src/components-examples/material/datepicker/datepicker-api/datepicker-api-example.html b/src/components-examples/material/datepicker/datepicker-api/datepicker-api-example.html
index 8f076eb5a474..96cc5bc0d928 100644
--- a/src/components-examples/material/datepicker/datepicker-api/datepicker-api-example.html
+++ b/src/components-examples/material/datepicker/datepicker-api/datepicker-api-example.html
@@ -1,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
 <button mat-raised-button (click)="picker.open()">Open</button>
diff --git a/src/components-examples/material/datepicker/datepicker-color/datepicker-color-example.html b/src/components-examples/material/datepicker/datepicker-color/datepicker-color-example.html
index ba5dc7b98154..a73c4d3e190a 100644
--- a/src/components-examples/material/datepicker/datepicker-color/datepicker-color-example.html
+++ b/src/components-examples/material/datepicker/datepicker-color/datepicker-color-example.html
@@ -1,6 +1,7 @@
 <mat-form-field color="accent" appearance="fill">
   <mat-label>Inherited calendar color</mat-label>
   <input matInput [matDatepicker]="picker1">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker1"></mat-datepicker-toggle>
   <mat-datepicker #picker1></mat-datepicker>
 </mat-form-field>
@@ -8,6 +9,7 @@
 <mat-form-field color="accent" appearance="fill">
   <mat-label>Custom calendar color</mat-label>
   <input matInput [matDatepicker]="picker2">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker2"></mat-datepicker-toggle>
   <mat-datepicker #picker2 color="primary"></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-custom-header/datepicker-custom-header-example.html b/src/components-examples/material/datepicker/datepicker-custom-header/datepicker-custom-header-example.html
index 2031646fdb8a..b09066b3a38f 100644
--- a/src/components-examples/material/datepicker/datepicker-custom-header/datepicker-custom-header-example.html
+++ b/src/components-examples/material/datepicker/datepicker-custom-header/datepicker-custom-header-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Custom calendar header</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker [calendarHeaderComponent]="exampleHeader"></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-custom-icon/datepicker-custom-icon-example.html b/src/components-examples/material/datepicker/datepicker-custom-icon/datepicker-custom-icon-example.html
index 3003f3671856..b52a00fcf631 100644
--- a/src/components-examples/material/datepicker/datepicker-custom-icon/datepicker-custom-icon-example.html
+++ b/src/components-examples/material/datepicker/datepicker-custom-icon/datepicker-custom-icon-example.html
@@ -1,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker">
     <mat-icon matDatepickerToggleIcon>keyboard_arrow_down</mat-icon>
   </mat-datepicker-toggle>
diff --git a/src/components-examples/material/datepicker/datepicker-date-class/datepicker-date-class-example.html b/src/components-examples/material/datepicker/datepicker-date-class/datepicker-date-class-example.html
index b4406d995230..cce3c818d6d2 100644
--- a/src/components-examples/material/datepicker/datepicker-date-class/datepicker-date-class-example.html
+++ b/src/components-examples/material/datepicker/datepicker-date-class/datepicker-date-class-example.html
@@ -1,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker [dateClass]="dateClass" #picker></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-disabled/datepicker-disabled-example.html b/src/components-examples/material/datepicker/datepicker-disabled/datepicker-disabled-example.html
index cc5b04276aa2..855adc1311e0 100644
--- a/src/components-examples/material/datepicker/datepicker-disabled/datepicker-disabled-example.html
+++ b/src/components-examples/material/datepicker/datepicker-disabled/datepicker-disabled-example.html
@@ -2,6 +2,7 @@
   <mat-form-field appearance="fill">
     <mat-label>Completely disabled</mat-label>
     <input matInput [matDatepicker]="dp1" disabled>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <mat-datepicker-toggle matSuffix [for]="dp1"></mat-datepicker-toggle>
     <mat-datepicker #dp1></mat-datepicker>
   </mat-form-field>
@@ -11,6 +12,7 @@
   <mat-form-field appearance="fill">
     <mat-label>Popup disabled</mat-label>
     <input matInput [matDatepicker]="dp2">
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <mat-datepicker-toggle matSuffix [for]="dp2" disabled></mat-datepicker-toggle>
     <mat-datepicker #dp2></mat-datepicker>
   </mat-form-field>
@@ -20,6 +22,7 @@
   <mat-form-field appearance="fill">
     <mat-label>Input disabled</mat-label>
     <input matInput [matDatepicker]="dp3" disabled>
+    <mat-hint>MM/DD/YYYY</mat-hint>
     <mat-datepicker-toggle matSuffix [for]="dp3"></mat-datepicker-toggle>
     <mat-datepicker #dp3 disabled="false"></mat-datepicker>
   </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-events/datepicker-events-example.html b/src/components-examples/material/datepicker/datepicker-events/datepicker-events-example.html
index c1827726477e..d81a789f3b26 100644
--- a/src/components-examples/material/datepicker/datepicker-events/datepicker-events-example.html
+++ b/src/components-examples/material/datepicker/datepicker-events/datepicker-events-example.html
@@ -2,6 +2,7 @@
   <mat-label>Input & change events</mat-label>
   <input matInput [matDatepicker]="picker"
          (dateInput)="addEvent('input', $event)" (dateChange)="addEvent('change', $event)">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-filter/datepicker-filter-example.html b/src/components-examples/material/datepicker/datepicker-filter/datepicker-filter-example.html
index da52910c44b9..5eb224d819bd 100644
--- a/src/components-examples/material/datepicker/datepicker-filter/datepicker-filter-example.html
+++ b/src/components-examples/material/datepicker/datepicker-filter/datepicker-filter-example.html
@@ -1,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepickerFilter]="myFilter" [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-formats/datepicker-formats-example.html b/src/components-examples/material/datepicker/datepicker-formats/datepicker-formats-example.html
index 50d9fab91d51..0abd101c0d49 100644
--- a/src/components-examples/material/datepicker/datepicker-formats/datepicker-formats-example.html
+++ b/src/components-examples/material/datepicker/datepicker-formats/datepicker-formats-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Verbose datepicker</mat-label>
   <input matInput [matDatepicker]="dp" [formControl]="date">
+  <mat-hint>MMMM DD, YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.html b/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.html
index 1af16b36a861..c6c0c3ed5a03 100644
--- a/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.html
+++ b/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.html
@@ -1,8 +1,8 @@
 <mat-form-field appearance="fill">
   <mat-label>Different locale</mat-label>
   <input matInput [matDatepicker]="dp">
+  <mat-hint>{{getDateFormatString()}}</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
 </mat-form-field>
-
 <button mat-button (click)="french()">Dynamically switch to French</button>
diff --git a/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.ts b/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.ts
index e862b95210ad..155d94a437e7 100644
--- a/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.ts
+++ b/src/components-examples/material/datepicker/datepicker-locale/datepicker-locale-example.ts
@@ -1,4 +1,4 @@
-import {Component} from '@angular/core';
+import {Component, Inject} from '@angular/core';
 import {
   MAT_MOMENT_DATE_FORMATS,
   MomentDateAdapter,
@@ -30,9 +30,22 @@ import 'moment/locale/fr';
   ],
 })
 export class DatepickerLocaleExample {
-  constructor(private _adapter: DateAdapter<any>) {}
+  constructor(
+    private _adapter: DateAdapter<any>,
+    @Inject(MAT_DATE_LOCALE) private _locale: string,
+  ) {}
 
   french() {
-    this._adapter.setLocale('fr');
+    this._locale = 'fr';
+    this._adapter.setLocale(this._locale);
+  }
+
+  getDateFormatString(): string {
+    if (this._locale === 'ja-JP') {
+      return 'YYYY/MM/DD';
+    } else if (this._locale === 'fr') {
+      return 'DD/MM/YYYY';
+    }
+    return '';
   }
 }
diff --git a/src/components-examples/material/datepicker/datepicker-min-max/datepicker-min-max-example.html b/src/components-examples/material/datepicker/datepicker-min-max/datepicker-min-max-example.html
index b79bc61cb448..df9593d65b88 100644
--- a/src/components-examples/material/datepicker/datepicker-min-max/datepicker-min-max-example.html
+++ b/src/components-examples/material/datepicker/datepicker-min-max/datepicker-min-max-example.html
@@ -1,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [min]="minDate" [max]="maxDate" [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-moment/datepicker-moment-example.html b/src/components-examples/material/datepicker/datepicker-moment/datepicker-moment-example.html
index 372811336cc6..a46c9c8bc7ea 100644
--- a/src/components-examples/material/datepicker/datepicker-moment/datepicker-moment-example.html
+++ b/src/components-examples/material/datepicker/datepicker-moment/datepicker-moment-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Moment.js datepicker</mat-label>
   <input matInput [matDatepicker]="dp" [formControl]="date">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-overview/datepicker-overview-example.html b/src/components-examples/material/datepicker/datepicker-overview/datepicker-overview-example.html
index ddf98afc504b..6e07a096bce8 100644
--- a/src/components-examples/material/datepicker/datepicker-overview/datepicker-overview-example.html
+++ b/src/components-examples/material/datepicker/datepicker-overview/datepicker-overview-example.html
@@ -2,6 +2,7 @@
   <mat-label>Choose a date</mat-label>
 <!-- #docregion toggle -->
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker></mat-datepicker>
 <!-- #enddocregion toggle -->
diff --git a/src/components-examples/material/datepicker/datepicker-start-view/datepicker-start-view-example.html b/src/components-examples/material/datepicker/datepicker-start-view/datepicker-start-view-example.html
index 0ff5960d067a..928a46b13998 100644
--- a/src/components-examples/material/datepicker/datepicker-start-view/datepicker-start-view-example.html
+++ b/src/components-examples/material/datepicker/datepicker-start-view/datepicker-start-view-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker #picker startView="year" [startAt]="startDate"></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-touch/datepicker-touch-example.html b/src/components-examples/material/datepicker/datepicker-touch/datepicker-touch-example.html
index 46479024f39e..8a1662ea7fee 100644
--- a/src/components-examples/material/datepicker/datepicker-touch/datepicker-touch-example.html
+++ b/src/components-examples/material/datepicker/datepicker-touch/datepicker-touch-example.html
@@ -1,6 +1,7 @@
 <mat-form-field class="example-full-width" appearance="fill">
   <mat-label>Choose a date</mat-label>
   <input matInput [matDatepicker]="picker">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
   <mat-datepicker touchUi #picker></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-value/datepicker-value-example.html b/src/components-examples/material/datepicker/datepicker-value/datepicker-value-example.html
index d905912de51b..f2cd70a3d0be 100644
--- a/src/components-examples/material/datepicker/datepicker-value/datepicker-value-example.html
+++ b/src/components-examples/material/datepicker/datepicker-value/datepicker-value-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Angular forms</mat-label>
   <input matInput [matDatepicker]="picker1" [formControl]="date">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker1"></mat-datepicker-toggle>
   <mat-datepicker #picker1></mat-datepicker>
 </mat-form-field>
@@ -9,6 +10,7 @@
   <mat-label>Angular forms (w/ deserialization)</mat-label>
   <input matInput [matDatepicker]="picker2"
          [formControl]="serializedDate">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker2"></mat-datepicker-toggle>
   <mat-datepicker #picker2></mat-datepicker>
 </mat-form-field>
@@ -16,6 +18,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Value binding</mat-label>
   <input matInput [matDatepicker]="picker3" [value]="date.value">
+  <mat-hint>MM/DD/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="picker3"></mat-datepicker-toggle>
   <mat-datepicker #picker3></mat-datepicker>
 </mat-form-field>
diff --git a/src/components-examples/material/datepicker/datepicker-views-selection/datepicker-views-selection-example.html b/src/components-examples/material/datepicker/datepicker-views-selection/datepicker-views-selection-example.html
index 1e72b7504430..5c00f83f5271 100644
--- a/src/components-examples/material/datepicker/datepicker-views-selection/datepicker-views-selection-example.html
+++ b/src/components-examples/material/datepicker/datepicker-views-selection/datepicker-views-selection-example.html
@@ -1,6 +1,7 @@
 <mat-form-field appearance="fill">
   <mat-label>Month and Year</mat-label>
   <input matInput [matDatepicker]="dp" [formControl]="date">
+  <mat-hint>MM/YYYY</mat-hint>
   <mat-datepicker-toggle matSuffix [for]="dp"></mat-datepicker-toggle>
   <mat-datepicker #dp
                   startView="multi-year"
diff --git a/src/components-examples/material/datepicker/index.ts b/src/components-examples/material/datepicker/index.ts
index 705cbbf5b0dc..0732e6e50f64 100644
--- a/src/components-examples/material/datepicker/index.ts
+++ b/src/components-examples/material/datepicker/index.ts
@@ -3,7 +3,7 @@ import {NgModule} from '@angular/core';
 import {FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {MatButtonModule} from '@angular/material/button';
 import {MatCardModule} from '@angular/material/card';
-import {MatNativeDateModule} from '@angular/material/core';
+import {MatNativeDateModule, MAT_DATE_LOCALE} from '@angular/material/core';
 import {MatDatepickerModule} from '@angular/material/datepicker';
 import {MatIconModule} from '@angular/material/icon';
 import {MatInputModule} from '@angular/material/input';
@@ -106,5 +106,11 @@ const EXAMPLES = [
   ],
   declarations: EXAMPLES,
   exports: EXAMPLES,
+  providers: [
+    // Except in specific examples, use 'en-US' locale in datepicker examples. This ensures that
+    // the hardcoded date format strings displayed in `<mat-hint>` will match the format used by
+    // `NativeDateModule`.
+    {provide: MAT_DATE_LOCALE, useValue: 'en-US'},
+  ],
 })
 export class DatepickerExamplesModule {}
diff --git a/src/material/datepicker/datepicker.md b/src/material/datepicker/datepicker.md
index 19c8bbc3d801..3811f1f978fd 100644
--- a/src/material/datepicker/datepicker.md
+++ b/src/material/datepicker/datepicker.md
@@ -588,6 +588,9 @@ attribute to the native input and button elements, respectively.
 the datepicker text input a meaningful label via `<mat-label>`, `aria-label`, `aria-labelledby` or
 `MatDatepickerIntl`.
 
+Always communicate the date format (e.g. 'MM/DD/YYYY'). This can be accomplished using `<mat-hint>`
+or by providing an additional label adjacent to the form field.
+
 `MatDatepickerInput` 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 `PageDown` key event. Because of this behavior, you should always include an