From 28dbbd500cdd9fa39c33d89338e48a8e717ff5cb Mon Sep 17 00:00:00 2001
From: Kristiyan Kostadinov <crisbeto@users.noreply.github.com>
Date: Sat, 3 Feb 2018 01:07:41 +0100
Subject: [PATCH] docs(autocomplete): add docs and example for
 autoActiveFirstOption (#9735)

Adds some documentation and a live example for the `MatAutocomplete.autoActiveFirstOption` property.
---
 src/lib/autocomplete/autocomplete.md          |  9 ++++++
 ...plete-auto-active-first-option-example.css |  9 ++++++
 ...lete-auto-active-first-option-example.html | 10 ++++++
 ...mplete-auto-active-first-option-example.ts | 31 +++++++++++++++++++
 4 files changed, 59 insertions(+)
 create mode 100644 src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.css
 create mode 100644 src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.html
 create mode 100644 src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.ts

diff --git a/src/lib/autocomplete/autocomplete.md b/src/lib/autocomplete/autocomplete.md
index 4de635a85c51..4f8a19ecc072 100644
--- a/src/lib/autocomplete/autocomplete.md
+++ b/src/lib/autocomplete/autocomplete.md
@@ -82,6 +82,15 @@ desired display value. Then bind it to the autocomplete's `displayWith` property
 
 <!-- example(autocomplete-display) -->
 
+### Automatically highlighting the first option
+
+If your use case requires for the first autocomplete option to be highlighted when the user opens
+the panel, you can do so by setting the `autoActiveFirstOption` input on the `mat-autocomplete`
+component. This behavior can be configured globally using the `MAT_AUTOCOMPLETE_DEFAULT_OPTIONS`
+injection token.
+
+<!-- example(autocomplete-auto-active-first-option) -->
+
 ### Keyboard interaction
 - <kbd>DOWN_ARROW</kbd>: Next option becomes active.
 - <kbd>UP_ARROW</kbd>: Previous option becomes active.
diff --git a/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.css b/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.css
new file mode 100644
index 000000000000..08fa67536b1f
--- /dev/null
+++ b/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.css
@@ -0,0 +1,9 @@
+.example-form {
+  min-width: 150px;
+  max-width: 500px;
+  width: 100%;
+}
+
+.example-full-width {
+  width: 100%;
+}
diff --git a/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.html b/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.html
new file mode 100644
index 000000000000..450909469d5d
--- /dev/null
+++ b/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.html
@@ -0,0 +1,10 @@
+<form class="example-form">
+  <mat-form-field class="example-full-width">
+    <input type="text" placeholder="Pick one" aria-label="Number" matInput [formControl]="myControl" [matAutocomplete]="auto">
+    <mat-autocomplete autoActiveFirstOption #auto="matAutocomplete">
+      <mat-option *ngFor="let option of filteredOptions | async" [value]="option">
+        {{ option }}
+      </mat-option>
+    </mat-autocomplete>
+  </mat-form-field>
+</form>
diff --git a/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.ts b/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.ts
new file mode 100644
index 000000000000..64868772d576
--- /dev/null
+++ b/src/material-examples/autocomplete-auto-active-first-option/autocomplete-auto-active-first-option-example.ts
@@ -0,0 +1,31 @@
+import {Component} from '@angular/core';
+import {FormControl} from '@angular/forms';
+import {Observable} from 'rxjs/Observable';
+import {startWith} from 'rxjs/operators/startWith';
+import {map} from 'rxjs/operators/map';
+
+/**
+ * @title Highlight the first autocomplete option
+ */
+@Component({
+  selector: 'autocomplete-auto-active-first-option-example',
+  templateUrl: 'autocomplete-auto-active-first-option-example.html',
+  styleUrls: ['autocomplete-auto-active-first-option-example.css']
+})
+export class AutocompleteAutoActiveFirstOptionExample {
+  myControl: FormControl = new FormControl();
+  options = ['One', 'Two', 'Three'];
+  filteredOptions: Observable<string[]>;
+
+  ngOnInit() {
+    this.filteredOptions = this.myControl.valueChanges.pipe(
+      startWith(''),
+      map(val => this.filter(val))
+    );
+  }
+
+  filter(val: string): string[] {
+    return this.options.filter(option => option.toLowerCase().indexOf(val.toLowerCase()) === 0);
+  }
+
+}