From 95a530006186ee82b7084c4194aadd6054541d60 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Wed, 27 Sep 2017 17:16:09 -0700
Subject: [PATCH 1/8] Add form field docs & examples

---
 src/lib/form-field/README.md                  |   1 +
 src/lib/form-field/form-field.md              | 128 ++++++++++++++++++
 .../form-field-error-example.css              |   8 ++
 .../form-field-error-example.html             |   6 +
 .../form-field-error-example.ts               |  18 +++
 .../form-field-hint-example.css               |   8 ++
 .../form-field-hint-example.html              |  13 ++
 .../form-field-hint-example.ts                |   9 ++
 .../form-field-overview-example.css           |   8 ++
 .../form-field-overview-example.html          |  15 ++
 .../form-field-overview-example.ts            |   9 ++
 .../form-field-placehodler-example.css        |  20 +++
 .../form-field-placeholder-example.html       |  29 ++++
 .../form-field-placeholder-example.ts         |  19 +++
 .../form-field-prefix-suffix-example.css      |  17 +++
 .../form-field-prefix-suffix-example.html     |  12 ++
 .../form-field-prefix-suffix-example.ts       |  11 ++
 .../form-field-theming-example.css            |   8 ++
 .../form-field-theming-example.html           |  14 ++
 .../form-field-theming-example.ts             |  23 ++++
 20 files changed, 376 insertions(+)
 create mode 100644 src/lib/form-field/README.md
 create mode 100644 src/lib/form-field/form-field.md
 create mode 100644 src/material-examples/form-field-error/form-field-error-example.css
 create mode 100644 src/material-examples/form-field-error/form-field-error-example.html
 create mode 100644 src/material-examples/form-field-error/form-field-error-example.ts
 create mode 100644 src/material-examples/form-field-hint/form-field-hint-example.css
 create mode 100644 src/material-examples/form-field-hint/form-field-hint-example.html
 create mode 100644 src/material-examples/form-field-hint/form-field-hint-example.ts
 create mode 100644 src/material-examples/form-field-overview/form-field-overview-example.css
 create mode 100644 src/material-examples/form-field-overview/form-field-overview-example.html
 create mode 100644 src/material-examples/form-field-overview/form-field-overview-example.ts
 create mode 100644 src/material-examples/form-field-placeholder/form-field-placehodler-example.css
 create mode 100644 src/material-examples/form-field-placeholder/form-field-placeholder-example.html
 create mode 100644 src/material-examples/form-field-placeholder/form-field-placeholder-example.ts
 create mode 100644 src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.css
 create mode 100644 src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html
 create mode 100644 src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.ts
 create mode 100644 src/material-examples/form-field-theming/form-field-theming-example.css
 create mode 100644 src/material-examples/form-field-theming/form-field-theming-example.html
 create mode 100644 src/material-examples/form-field-theming/form-field-theming-example.ts

diff --git a/src/lib/form-field/README.md b/src/lib/form-field/README.md
new file mode 100644
index 000000000000..7a1234123cc2
--- /dev/null
+++ b/src/lib/form-field/README.md
@@ -0,0 +1 @@
+Please see the official documentation at https://material.angular.io/components/component/form-field
diff --git a/src/lib/form-field/form-field.md b/src/lib/form-field/form-field.md
new file mode 100644
index 000000000000..1a911c5c89e6
--- /dev/null
+++ b/src/lib/form-field/form-field.md
@@ -0,0 +1,128 @@
+`<mat-form-field>` is a component used to wrap several Angular Material components and apply common
+[Text field](https://material.io/guidelines/components/text-fields.html) styles such as the
+underline, floating label, and hint messages.
+
+In this document "form field" refers to the wrapper component `<mat-form-field>` and
+"form field control" refers to the component that the `<mat-form-field>` is wrapping
+(e.g. the input, textarea, select, etc.)
+
+The following Angular Material components are designed to work inside a `<mat-form-field>`:
+* [&lt;input matInput&gt; &amp; &lt;textarea matInput&gt;](https://material.angular.io/components/input/overview)
+* [&lt;mat-select&gt;](https://material.angular.io/components/select/overview)
+* [&lt;mat-chip-list&gt;](https://material.angular.io/components/chips/overview)
+
+<!-- example(form-field-overview) -->
+
+### Floating placeholder
+The floating placeholder is an indicative text label displayed on top of the form field control when
+the control does not contain any text. By default, when text is present the floating placeholder
+floats above the form field control.
+
+The placeholder text can be specified using the `placeholder` property on the form field control, or
+by adding a `<mat-placeholder>` element inside the form field. Only one of these options should be
+used, specifying both will raise an error.
+
+If the form field control is marked with a `required` attribute, an asterisk will be appended to the
+placeholder to indicate the fact that it is a required field. If unwanted, this can be disabled by
+setting the `hideRequiredMarker` property on `<mat-form-field>`
+
+The `floatPlaceholder` property of `<mat-form-field>` can be used to change this default floating
+behavior. It can set to `never` to hide the placeholder instead of float it when text is present in
+the form field control. It can be set to `always` to float the placeholder even when no text is
+present in the form field control. It can also be set to `auto` to restore the default behavior.
+
+<!-- example(form-field-placeholder) -->
+
+Global default placeholder options can be specified by setting providing a value for
+`MAT_PLACEHOLDER_GLOBAL_OPTIONS` in your application's root module. Like the property, the global
+setting can be either `always`, `never`, or `auto`.
+
+```ts
+@NgModule({
+  providers: [
+    {provide: MAT_PLACEHOLDER_GLOBAL_OPTIONS, useValue: {float: 'always'}}
+  ]
+})
+```
+
+### Hint labels
+Hint labels are additional descriptive text that appears below the form field's underline. A
+`<mat-form-field>` can have up to two hint labels; one start-aligned (left in an LTR language, right
+in RTL), and one end-aligned.
+
+Hint labels are specified in one of two ways: either by using the `hintLabel` property of
+`<mat-form-field>`, or by adding a `<mat-hint>` element inside the form field. When adding a hint
+via the `hintLabel` property it will be treated as the start hint. Hints added via the
+`<mat-hint>` hint element can be added to either side by setting the `align` property on
+`<mat-hint>` to either `start` or `end`. Attempting to add multiple hints to the same side will
+raise an error.
+
+<!-- example(form-field-hint) -->
+
+### Error messages
+Error messages can be shown under the form field underline by adding `mat-error` elements inside the
+form field. Errors are hidden initially and will be displayed on invalid form fields after the user
+has interacted with the element or the parent form has been submitted. Since the errors occupy the
+same space as the hints, the hints are hidden when the errors are shown.
+
+If an form field can have more than one error state, it is up to the consumer to toggle which
+messages should be displayed. This can be done with CSS, `ngIf` or `ngSwitch`. Multiple error
+messages can be shown at the same time if desired, but the `<mat-form-field>` only reserves enough
+space to display one error message at a time. Ensuring that enough space is available to display
+multiple errors is up to the user.
+
+<!-- example(form-field-error) -->
+
+### Prefix & suffix
+HTML can be included before and after the input tag, as a prefix or suffix. It will be underlined
+as per the Material specification.
+
+Adding the `matPrefix` directive to an element inside the `<mat-form-field>` will designate it as
+the prefix. Similarly, adding `matSuffix` will designate it as the suffix.
+
+<!-- example(form-field-prefix-suffix) -->
+
+### Custom form field controls
+In addition to the form field controls that Angular Material provides, it is possible to create
+custom form field controls that work with `<mat-form-field>` in the same way. For additional
+information on this see the guide on [Creating Custom mat-form-field Controls](TODO).
+
+### Theming
+`<mat-form-field>` has a `color` property which can be set to `primary`, `accent`, or `warn`. This
+will set the color ofr the form field underline and floating placeholder based on the theme colors
+of your app.
+
+`<mat-form-field>` inherits its `font-size` from its parent element. This can be overridden to an
+explicit size using CSS. We recommend a specificity of at least 1 element + 1 class.
+
+```css
+mat-form-field.mat-form-field {
+  font-size: 16px;
+}
+```
+
+<!-- example(form-field-theming) -->
+
+### Accessibility
+If a floating placeholder is specified it will be automatically used as the label for the form field
+control. If no floating placeholder is specified the user should label the form field control
+themselves using `aria-label`, `aria-labelledby` or `<label for=...>`.
+
+Any errors and hints added to the form field are automatically added to the form field control's
+`aria-describedby` set.
+
+### Troubleshooting
+#### Error: Placeholder attribute and child element were both specified
+This error occurs when you have specified two conflicting placeholders. Make sure that you haven't
+included both a `placeholder` property on your form field control and a `<mat-placeholder>`
+element.
+
+#### Error: A hint was already declared for align="..."
+This error occurs you have added multiple hints for the same side. Keep in mind that the `hintLabel`
+property adds a hint to the start side.
+
+#### Error: md-form-field must contain a MdFormFieldControl
+This error occurs when you have not added a form field control to your form field. If your form
+field contains a native `<input>` or `<textarea>` element, make sure you've added the `matInput`
+directive to it. Other components that can act as a form field control include `<mat-select>`,
+`<mat-chip-list>`, and any custom form field controls you've created.
diff --git a/src/material-examples/form-field-error/form-field-error-example.css b/src/material-examples/form-field-error/form-field-error-example.css
new file mode 100644
index 000000000000..cfd4505c7c7a
--- /dev/null
+++ b/src/material-examples/form-field-error/form-field-error-example.css
@@ -0,0 +1,8 @@
+.example-container {
+  display: flex;
+  flex-direction: column;
+}
+
+.example-container > * {
+  width: 100%;
+}
diff --git a/src/material-examples/form-field-error/form-field-error-example.html b/src/material-examples/form-field-error/form-field-error-example.html
new file mode 100644
index 000000000000..82eab33a3eb0
--- /dev/null
+++ b/src/material-examples/form-field-error/form-field-error-example.html
@@ -0,0 +1,6 @@
+<div class="example-container">
+  <md-form-field>
+    <input mdInput placeholder="Enter your email" [formControl]="email" required>
+    <md-error *ngIf="!email.valid">{{getErrorMessage()}}</md-error>
+  </md-form-field>
+</div>
diff --git a/src/material-examples/form-field-error/form-field-error-example.ts b/src/material-examples/form-field-error/form-field-error-example.ts
new file mode 100644
index 000000000000..ac867e7157f0
--- /dev/null
+++ b/src/material-examples/form-field-error/form-field-error-example.ts
@@ -0,0 +1,18 @@
+import {Component} from '@angular/core';
+import {FormControl, Validators} from '@angular/forms';
+
+/** @title Form field with error messages */
+@Component({
+  selector: 'form-field-error-example',
+  templateUrl: 'form-field-error-example.html',
+  styleUrls: ['form-field-error-example.css']
+})
+export class FormFieldErrorExample {
+  email = new FormControl('', [Validators.required, Validators.email]);
+
+  getErrorMessage() {
+    return this.email.hasError('required') ? 'You must enter a value' :
+        this.email.hasError('email') ? 'Not a valid email' :
+            '';
+  }
+}
diff --git a/src/material-examples/form-field-hint/form-field-hint-example.css b/src/material-examples/form-field-hint/form-field-hint-example.css
new file mode 100644
index 000000000000..cfd4505c7c7a
--- /dev/null
+++ b/src/material-examples/form-field-hint/form-field-hint-example.css
@@ -0,0 +1,8 @@
+.example-container {
+  display: flex;
+  flex-direction: column;
+}
+
+.example-container > * {
+  width: 100%;
+}
diff --git a/src/material-examples/form-field-hint/form-field-hint-example.html b/src/material-examples/form-field-hint/form-field-hint-example.html
new file mode 100644
index 000000000000..c9993ada4207
--- /dev/null
+++ b/src/material-examples/form-field-hint/form-field-hint-example.html
@@ -0,0 +1,13 @@
+<div class="example-container">
+  <md-form-field hintLabel="Max 10 characters">
+    <input mdInput #input maxlength="10" placeholder="Enter some input">
+    <md-hint align="end">{{input.value?.length || 0}}/10</md-hint>
+  </md-form-field>
+
+  <md-form-field>
+    <md-select placeholder="Select me">
+      <md-option value="option">Option</md-option>
+    </md-select>
+    <md-hint align="end">Here's the dropdown arrow ^</md-hint>
+  </md-form-field>
+</div>
diff --git a/src/material-examples/form-field-hint/form-field-hint-example.ts b/src/material-examples/form-field-hint/form-field-hint-example.ts
new file mode 100644
index 000000000000..1ae1b159368e
--- /dev/null
+++ b/src/material-examples/form-field-hint/form-field-hint-example.ts
@@ -0,0 +1,9 @@
+import {Component} from '@angular/core';
+
+/** @title Form field with hints */
+@Component({
+  selector: 'form-field-hint-example',
+  templateUrl: 'form-field-hint-example.html',
+  styleUrls: ['form-field-hint-example.css']
+})
+export class FormFieldHintExample {}
diff --git a/src/material-examples/form-field-overview/form-field-overview-example.css b/src/material-examples/form-field-overview/form-field-overview-example.css
new file mode 100644
index 000000000000..cfd4505c7c7a
--- /dev/null
+++ b/src/material-examples/form-field-overview/form-field-overview-example.css
@@ -0,0 +1,8 @@
+.example-container {
+  display: flex;
+  flex-direction: column;
+}
+
+.example-container > * {
+  width: 100%;
+}
diff --git a/src/material-examples/form-field-overview/form-field-overview-example.html b/src/material-examples/form-field-overview/form-field-overview-example.html
new file mode 100644
index 000000000000..7c8183878852
--- /dev/null
+++ b/src/material-examples/form-field-overview/form-field-overview-example.html
@@ -0,0 +1,15 @@
+<div class="example-container">
+  <md-form-field>
+    <input mdInput placeholder="Input">
+  </md-form-field>
+
+  <md-form-field>
+    <textarea mdInput placeholder="Textarea"></textarea>
+  </md-form-field>
+
+  <md-form-field>
+    <md-select placeholder="Select">
+      <md-option value="option">Option</md-option>
+    </md-select>
+  </md-form-field>
+</div>
diff --git a/src/material-examples/form-field-overview/form-field-overview-example.ts b/src/material-examples/form-field-overview/form-field-overview-example.ts
new file mode 100644
index 000000000000..252002097827
--- /dev/null
+++ b/src/material-examples/form-field-overview/form-field-overview-example.ts
@@ -0,0 +1,9 @@
+import {Component} from '@angular/core';
+
+/** @title Simple form field */
+@Component({
+  selector: 'form-field-overview-example',
+  templateUrl: 'form-field-overview-example.html',
+  styleUrls: ['form-field-overview-example.css']
+})
+export class FormFieldOverviewExample {}
diff --git a/src/material-examples/form-field-placeholder/form-field-placehodler-example.css b/src/material-examples/form-field-placeholder/form-field-placehodler-example.css
new file mode 100644
index 000000000000..333087a490e5
--- /dev/null
+++ b/src/material-examples/form-field-placeholder/form-field-placehodler-example.css
@@ -0,0 +1,20 @@
+.example-container {
+  display: flex;
+  flex-direction: column;
+}
+
+.example-container > * {
+  width: 100%;
+}
+
+.example-container form {
+  margin-bottom: 20px;
+}
+
+.example-container form > * {
+  margin: 5px 0;
+}
+
+.example-container .mat-radio-button {
+  margin: 0 5px;
+}
diff --git a/src/material-examples/form-field-placeholder/form-field-placeholder-example.html b/src/material-examples/form-field-placeholder/form-field-placeholder-example.html
new file mode 100644
index 000000000000..73c5456022a6
--- /dev/null
+++ b/src/material-examples/form-field-placeholder/form-field-placeholder-example.html
@@ -0,0 +1,29 @@
+<div class="example-container">
+  <form class="example-container" [formGroup]="options">
+    <md-checkbox formControlName="hideRequired">Hide required marker</md-checkbox>
+    <div>
+      <label>Float placeholder: </label>
+      <md-radio-group formControlName="floatPlaceholder">
+        <md-radio-button value="auto">Auto</md-radio-button>
+        <md-radio-button value="always">Always</md-radio-button>
+        <md-radio-button value="never">Never</md-radio-button>
+      </md-radio-group>
+    </div>
+  </form>
+
+  <md-form-field
+      [hideRequiredMarker]="options.value.hideRequired"
+      [floatPlaceholder]="options.value.floatPlaceholder">
+    <input mdInput placeholder="Simple placeholder" required>
+  </md-form-field>
+
+  <md-form-field
+      [hideRequiredMarker]="options.value.hideRequired"
+      [floatPlaceholder]="options.value.floatPlaceholder">
+    <md-select required>
+      <md-option>-- None --</md-option>
+      <md-option value="option">Option</md-option>
+    </md-select>
+    <md-placeholder><md-icon>favorite</md-icon> <b> Fancy</b> <i> placeholder</i></md-placeholder>
+  </md-form-field>
+</div>
diff --git a/src/material-examples/form-field-placeholder/form-field-placeholder-example.ts b/src/material-examples/form-field-placeholder/form-field-placeholder-example.ts
new file mode 100644
index 000000000000..8d21f1ebb244
--- /dev/null
+++ b/src/material-examples/form-field-placeholder/form-field-placeholder-example.ts
@@ -0,0 +1,19 @@
+import {Component} from '@angular/core';
+import {FormBuilder, FormGroup} from '@angular/forms';
+
+/** @title Form field with placeholder */
+@Component({
+  selector: 'form-field-placeholder-example',
+  templateUrl: 'form-field-placeholder-example.html',
+  styleUrls: ['form-field-placeholder-example.css']
+})
+export class FormFieldPlaceholderExample {
+  options: FormGroup;
+
+  constructor(fb: FormBuilder) {
+    this.options = fb.group({
+      hideRequired: false,
+      floatPlaceholder: 'auto',
+    });
+  }
+}
diff --git a/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.css b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.css
new file mode 100644
index 000000000000..0a7a621eff5e
--- /dev/null
+++ b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.css
@@ -0,0 +1,17 @@
+.example-container {
+  display: flex;
+  flex-direction: column;
+}
+
+.example-container > * {
+  width: 100%;
+}
+
+.example-right-align {
+  text-align: right;
+}
+
+input.example-right-align::-webkit-outer-spin-button,
+input.example-right-align::-webkit-inner-spin-button {
+  display: none;
+}
diff --git a/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html
new file mode 100644
index 000000000000..3eef5b2a4d8b
--- /dev/null
+++ b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html
@@ -0,0 +1,12 @@
+<div class="example-container">
+  <md-form-field>
+    <input mdInput placeholder="Enter your password" [type]="hide ? 'password' : 'text'">
+    <md-icon mdSuffix (click)="hide = !hide">{{hide ? 'visibility' : 'visibility_off'}}</md-icon>
+  </md-form-field>
+
+  <md-form-field>
+    <input mdInput placeholder="Amount" type="number" class="example-right-align">
+    <span mdPrefix>$&nbsp;</span>
+    <span mdSuffix>.00</span>
+  </md-form-field>
+</div>
diff --git a/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.ts b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.ts
new file mode 100644
index 000000000000..16b24e7b45ec
--- /dev/null
+++ b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.ts
@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/** @title Form field with prefix & suffix */
+@Component({
+  selector: 'form-field-prefix-suffix-example',
+  templateUrl: 'form-field-prefix-suffix-example.html',
+  styleUrls: ['form-field-prefix-suffix-example.css']
+})
+export class FormFieldPrefixSuffixExample {
+  hide = true;
+}
diff --git a/src/material-examples/form-field-theming/form-field-theming-example.css b/src/material-examples/form-field-theming/form-field-theming-example.css
new file mode 100644
index 000000000000..cfd4505c7c7a
--- /dev/null
+++ b/src/material-examples/form-field-theming/form-field-theming-example.css
@@ -0,0 +1,8 @@
+.example-container {
+  display: flex;
+  flex-direction: column;
+}
+
+.example-container > * {
+  width: 100%;
+}
diff --git a/src/material-examples/form-field-theming/form-field-theming-example.html b/src/material-examples/form-field-theming/form-field-theming-example.html
new file mode 100644
index 000000000000..14621e56ff71
--- /dev/null
+++ b/src/material-examples/form-field-theming/form-field-theming-example.html
@@ -0,0 +1,14 @@
+<form class="example-container" [formGroup]="options" [style.fontSize.px]="getFontSize()">
+  <md-form-field [color]="options.value.color">
+    <md-select placeholder="Color" formControlName="color">
+      <md-option value="primary">Primary</md-option>
+      <md-option value="accent">Accent</md-option>
+      <md-option value="warn">Warn</md-option>
+    </md-select>
+  </md-form-field>
+
+  <md-form-field [color]="options.value.color">
+    <input mdInput type="number" placeholder="Font size (px)" formControlName="fontSize" min="10">
+    <md-error *ngIf="!options.get('fontSize').valid">Min size: 10px</md-error>
+  </md-form-field>
+</form>
diff --git a/src/material-examples/form-field-theming/form-field-theming-example.ts b/src/material-examples/form-field-theming/form-field-theming-example.ts
new file mode 100644
index 000000000000..1e27dbc40b29
--- /dev/null
+++ b/src/material-examples/form-field-theming/form-field-theming-example.ts
@@ -0,0 +1,23 @@
+import {Component} from '@angular/core';
+import {FormBuilder, FormGroup, Validators} from '@angular/forms';
+
+/** @title Form field theming */
+@Component({
+  selector: 'form-field-theming-example',
+  templateUrl: 'form-field-theming-example.html',
+  styleUrls: ['form-field-theming-example.css']
+})
+export class FormFieldThemingExample {
+  options: FormGroup;
+
+  constructor(fb: FormBuilder) {
+    this.options = fb.group({
+      'color': 'primary',
+      'fontSize': [16, Validators.min(10)],
+    });
+  }
+
+  getFontSize() {
+    return Math.max(10, this.options.value.fontSize);
+  }
+}

From a7c49aa4df0653d4e7455a4938f4f0ceb2b87b8b Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Thu, 28 Sep 2017 18:02:49 -0700
Subject: [PATCH 2/8] Add form field guide

---
 .../creating-a-custom-form-field-control.md   | 334 ++++++++++++++++++
 .../autocomplete/autocomplete-demo.html       |  79 +----
 .../autocomplete/autocomplete-demo.scss       |  20 --
 .../autocomplete/autocomplete-demo.ts         | 245 +++++++------
 src/demo-app/demo-app/demo-module.ts          |   3 +-
 src/lib/form-field/form-field-control.ts      |   2 +-
 6 files changed, 487 insertions(+), 196 deletions(-)
 create mode 100644 guides/creating-a-custom-form-field-control.md

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
new file mode 100644
index 000000000000..e5c478a38e92
--- /dev/null
+++ b/guides/creating-a-custom-form-field-control.md
@@ -0,0 +1,334 @@
+It is possible to create custom form field controls that can be used inside `<mat-form-field>`. This
+can be useful if you need to create a components that shares a lot of common behavior with a form
+field, but adds some additional logic.
+
+In order to learn how to build custom form field controls, lets start with a simple input component
+that we want to work inside the form field. For example, a phone number input that segments the
+parts of the number into their own inputs. (Note: this is not intended to be a robust component,
+just a starting point for us to learn.)
+
+<!-- TODO(mmalerba): Link to plunker/stackblitz with complete example code -->
+
+```ts
+class MyTel {
+  constructor(public area: string, public exchange: string, public subscriber: string) {}
+}
+
+@Component({
+  selector: 'my-tel-input',
+  template: `
+    <style>
+      div {
+        display: flex;
+      }
+      input {
+        border: none;
+        background: none;
+        padding: 0;
+        outline: none;
+        font: inherit;
+        text-align: center;
+      }
+    </style>
+    
+    <div [formGroup]="parts">
+      <input class="area" formControlName="area" size="3">
+      <span>&ndash;</span>
+      <input class="exchange" formControlName="exchange" size="3">
+      <span>&ndash;</span>
+      <input class="subscriber" formControlName="subscriber" size="4">
+    </div>
+  `,
+})
+class MyTelInput {
+  parts: FormGroup;
+
+  @Input()
+  get value(): MyTel | null {
+    let n = this.parts.value;
+    if (n.area.length == 3 && n.exchange.length == 3 && n.subscriber.length == 4) {
+      return new MyTel(n.area, n.exchange, n.subscriber);
+    }
+    return null;
+  }
+  set value(tel: MyTel | null) {
+    tel = tel || new MyTel('', '', '');
+    this.parts.setValue({area: tel.area, exchange: tel.exchange, subscriber: tel.subscriber});
+  }
+  
+  constructor(fb: FormBuilder) {
+    this.parts =  fb.group({
+      'area': '',
+      'exchange': '',
+      'subscriber': '',
+    });
+  }
+}
+```
+
+### Providing our component as an MdFormFieldControl
+The first step is to provide our new component as an implementation of the `MdFormFieldControl`
+interface that the `<md-form-field>` knows how to work with. To do this we will have our class
+implement `MdFormFieldControl`, since this is a generic interface we'll need to include a type
+parameter indicating the type of data our control will work with, in this case `MyTel`. We then add
+a provider to our component so that when the form field will be able to inject it as a
+`MdFormFieldControl`.
+
+```ts
+@Component({
+  ...
+  providers: [{provide: MdFormFieldControl, useExisting: MyTelInput}],
+})
+class MyTelInput implements MdFormFieldControl<MyTel> {
+  ...
+}
+```
+
+This sets up our component so it can work with `<md-form-field>`, but now we need to implement the
+various methods and properties declared by the interface we just implemented. To learn more about
+the `MdFormFieldControl` interface, see its
+[definition](https://github.com/angular/material2/blob/master/src/lib/form-field/form-field-control.ts).
+(Unfortunately generated API docs are not available yet, but we'll go through the methods and
+properties in this guide.) 
+
+### Implementing the methods and properties of MdFormFieldControl
+#### `value`
+This property allows someone to set or get the value of our control. Its type should be the same
+type we used for the type parameter when we implemented `MdFormFieldControl`. Since our component 
+already has a value property we don't need to do anything for this one.
+
+#### `stateChanges`
+Because the `<mat-form-field>` used the `OnPush` change detection strategy, we need to let it know
+when something happens in the form field control that may require the form field to run change
+detection. We do this via the `stateChanges` property. So far the only thing the form field needs to
+know about is when the value changes. We'll need to emit on the stateChanges stream when that
+happens, and as we continue flushing out these properties we'll likely find more places we need to
+emit. We should also make sure to complete `stateChanges` when our component is destroyed
+
+```ts
+stateChanges = new Subject<void>();
+
+set value(tel: MyTel | null) {
+  ...
+  stateChanges.next();
+}
+
+ngOnDestory() {
+  stateChanges.destroy();
+}
+```
+
+#### `id`
+This property should return the ID of an element in the component's template that we want the
+`<mat-form-field>` to associate all of its labels and hints with. In this case we'll use the host
+element and just generate a unique ID for it.
+
+```ts
+static nextId = 0;
+
+@HostBinding() id = `my-tel-input-${MyTelInput.nextId++}`;
+```
+
+#### `placeholder`
+This property allows us to tell the `<mat-form-field>` what to use as a placeholder. In this
+example, we'll do the same thing as `matInput` and `<mat-select>` and allow the user to specify it
+via an `@Input()`. Since the value of the placeholder may change over time, we need to make sure to
+trigger change detection in the parent form field by emitting on the `stateChanges` stream when the
+placeholder changes.
+
+```ts
+@Input()
+get placeholder() {
+  return this._placeholder;
+}
+set placeholder(plh) {
+  this._placeholder = plh;
+  this.stateChanges.next();
+}
+private _placeholder: string;
+```
+
+#### `ngControl`
+This property allows the form field control to specify the `@angular/forms` control that is bound to
+this component. Since we haven't set up our component to act as a `ControlValueAccessor` we'll just
+set this to `null` in our component. In any real component you would probably want to implement
+`ControlValueAccessor` so that your component can work with `formControl` and `ngModel`.
+
+```ts
+ngControl = null;
+```
+
+If you did implement `ControlValueAccessor`, you could simply inject the `NgControl` and make it
+publicly available. (For additional information about `ControlValueAccessor` see the
+[API docs](https://angular.io/api/forms/ControlValueAccessor).)
+
+```ts
+constructor(..., @Optional() @Self() public ngControl: NgControl) { ... }
+```
+
+#### `focused`
+This property indicates whether or not the form field control should be considered to be in a
+focused state. When it is in a focused state the form field is displayed with a solid color
+underline. For the purposes of our component, we want to consider it focused if any of the part
+inputs are focused. We can use the `FocusMonitor` from `@angular/cdk` to easily check this. We also
+need to remember to emit on the `stateChanges` stream so change detection can happen.
+
+```ts
+focused = false;
+
+constructor(fb: FormBuilder, private fm: FocusMonitor, private elRef: ElementRef,
+            renderer: Renderer2) {
+  ...
+  fm.monitor(elRef.nativeElement, renderer, true).subscribe(origin => {
+    this.focused = !!origin;
+    this.stateChanges.next();
+  });
+}
+
+ngOnDestroy() {
+  ...
+  this.fm.stopMonitoring(this.elRef.nativeElement);
+}
+```
+
+#### `empty`
+This property indicates whether the form field control is empty. For our control we'll consider it
+empty if all of the parts are empty.
+
+```ts
+get empty() {
+  let n = this.parts.value;
+  return !n.area && !n.exchange && !n.subscriber;
+}
+```
+
+#### `shouldPlaceholderFloat`
+This property is used to indicate whether the placeholder should be in the floating position. We'll
+use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
+Since the placeholder will be overlapping our control when when its not floating, we should hide the
+`–` characters when its not floating.
+
+```ts
+@HostBinding('class.floating')
+get shouldPlaceholderFloat() {
+  return this.focused || !this.empty;
+}
+```
+```css
+span {
+  opacity: 0;
+  transition: opacity 200ms;
+}
+:host.floating span {
+  opacity: 1;
+}
+```
+
+#### `required`
+This property is used to indicate whether the input is required. `<mat-form-field>` uses this
+information to add a required indicator to the placeholder. Again, we'll want to make sure we run
+change detection if the required state changes.
+
+```ts
+@Input()
+get required() {
+  return this._required;
+}
+set required(req) {
+  this._required = coerceBooleanProperty(req);
+  this.stateChanges.next();
+}
+private _required = false;
+```
+
+#### `disabled`
+This property tells the form field when it should be in the disabled state. In addition to reporting
+the right state to the form field, we need to set the disabled state on the individual inputs that
+make up our component.
+
+```ts
+@Input()
+get disabled() {
+  return this._disabled;
+}
+set disabled(dis) {
+  this._disabled = coerceBooleanProperty(dis);
+  this.stateChanges.next();
+}
+private _disabled = false;
+```
+```html
+<input class="area" formControlName="area" size="3" [disabled]="disabled">
+<span>&ndash;</span>
+<input class="exchange" formControlName="exchange" size="3" [disabled]="disabled">
+<span>&ndash;</span>
+<input class="subscriber" formControlName="subscriber" size="4" [disabled]="disabled">
+```
+
+#### `errorState`
+This property indicates whether the associated `NgControl` is in an error state. Since we're not
+using an `NgControl` in this example we don't need to do anything other than just set it to `false`.
+
+```ts
+errorState = false;
+```
+
+#### `controlType`
+This property allows us to specify a unique string for the type of control in form field. The
+`<mat-form-field>` will add an additional class based on this type that can be used to easily apply
+special styles to a `<mat-form-field>` that contains a specific type of control. In this example
+we'll use `my-tel-input` as our control type which will result in the form field adding the class
+`mat-form-field-my-tel-input`.
+
+```ts
+controlType = 'my-tel-input';
+```
+
+#### `setAriaDescribedByIds`
+This method is used by the `<mat-form-field>` to specify the IDs that should be used for the
+`aria-describedby` attribute of your component. The method has one parameter, the list of IDs, we
+just need to apply the given IDs to our host element.
+
+```ts
+@HostBinding('attr.aria-describedby') describedBy = '';
+  
+setDescribedByIds(ids: string[]) {
+  this.describedBy = ids.join(' ');
+}
+```
+
+#### `onContainerClick`
+This method will be called when the form field is clicked on. It allows your component to hook in
+and handle that click however it wants. The method has one parameter, the `MouseEvent` for the
+click. In our case we'll just focus the first `<input>` if the user isn't about to click an
+`<input>` anyways.
+
+```ts
+onContainerClick(event: MouseEvent) {
+  if ((event.target as Element).tagName.toLowerCase() != 'input') {
+    this.elRef.nativeElement.querySelector('input').focus();
+  }
+}
+```
+
+### Trying it out
+Now that we've fully implemented the interface, we're ready to try our component out! All we need to
+do is place it inside of a `<mat-form-filed>`
+
+```html
+<mat-form-field>
+  <my-tel-input></my-tel-input>
+</mat-form-field>
+```
+
+We also get all of the features that come with `<mat-form-field>` such as floating placeholder,
+prefix, suffix, hints, and errors (if we've given the form field an `NgControl` and correctly report
+the error state).
+
+```html
+<mat-form-field>
+  <my-tel-input placeholder="Phone number" required></my-tel-input>
+  <md-icon mdPrefix>phone</md-icon>
+  <md-hint>Include area code</md-hint>
+</mat-form-field>
+```
diff --git a/src/demo-app/autocomplete/autocomplete-demo.html b/src/demo-app/autocomplete/autocomplete-demo.html
index 3a844aa81a8a..15336e19ba47 100644
--- a/src/demo-app/autocomplete/autocomplete-demo.html
+++ b/src/demo-app/autocomplete/autocomplete-demo.html
@@ -1,74 +1,5 @@
-Space above cards: <input type="number" [formControl]="topHeightCtrl">
-<div [style.height.px]="topHeightCtrl.value"></div>
-<div class="demo-autocomplete">
-  <mat-card>
-    Reactive length: {{ reactiveStates.length }}
-    <div>Reactive value: {{ stateCtrl.value | json }}</div>
-    <div>Reactive dirty: {{ stateCtrl.dirty }}</div>
-
-    <mat-form-field floatPlaceholder="never">
-      <input matInput placeholder="State" [matAutocomplete]="reactiveAuto" [formControl]="stateCtrl">
-      <mat-autocomplete #reactiveAuto="matAutocomplete" [displayWith]="displayFn">
-        <mat-option *ngFor="let state of reactiveStates | async" [value]="state">
-          <span>{{ state.name }}</span>
-          <span class="demo-secondary-text"> ({{state.code}}) </span>
-        </mat-option>
-      </mat-autocomplete>
-    </mat-form-field>
-
-    <mat-card-actions>
-      <button mat-button (click)="stateCtrl.reset()">RESET</button>
-      <button mat-button (click)="stateCtrl.setValue(states[10])">SET VALUE</button>
-      <button mat-button (click)="stateCtrl.enabled ? stateCtrl.disable() : stateCtrl.enable()">
-        TOGGLE DISABLED
-      </button>
-    </mat-card-actions>
-
-  </mat-card>
-
-  <mat-card>
-
-    <div>Template-driven value (currentState): {{ currentState }}</div>
-    <div>Template-driven dirty: {{ modelDir ? modelDir.dirty : false }}</div>
-
-    <!-- Added an ngIf below to test that autocomplete works with ngIf -->
-    <mat-form-field *ngIf="true">
-      <input matInput placeholder="State" [matAutocomplete]="tdAuto" [(ngModel)]="currentState"
-        (ngModelChange)="tdStates = filterStates(currentState)" [disabled]="tdDisabled">
-      <mat-autocomplete #tdAuto="matAutocomplete">
-        <mat-option *ngFor="let state of tdStates" [value]="state.name">
-          <span>{{ state.name }}</span>
-        </mat-option>
-      </mat-autocomplete>
-    </mat-form-field>
-
-    <mat-card-actions>
-      <button mat-button (click)="modelDir.reset()">RESET</button>
-      <button mat-button (click)="currentState='California'">SET VALUE</button>
-      <button mat-button (click)="tdDisabled=!tdDisabled">
-        TOGGLE DISABLED
-      </button>
-    </mat-card-actions>
-
-  </mat-card>
-
-  <mat-card>
-    <div>Option groups (currentGroupedState): {{ currentGroupedState }}</div>
-
-    <mat-input-container>
-      <input
-        matInput
-        placeholder="State"
-        [matAutocomplete]="groupedAuto"
-        [(ngModel)]="currentGroupedState"
-        (ngModelChange)="filteredGroupedStates = filterStateGroups(currentGroupedState)">
-    </mat-input-container>
-  </mat-card>
-</div>
-
-<mat-autocomplete #groupedAuto="matAutocomplete">
-  <mat-optgroup *ngFor="let group of filteredGroupedStates"
-    [label]="'States starting with ' + group.letter">
-    <mat-option *ngFor="let state of group.states" [value]="state.name">{{ state.name }}</mat-option>
-  </mat-optgroup>
-</mat-autocomplete>
+<md-form-field>
+  <my-tel-input placeholder="Phone number" required></my-tel-input>
+  <md-icon mdSuffix>phone</md-icon>
+  <md-hint>Include area code</md-hint>
+</md-form-field>
diff --git a/src/demo-app/autocomplete/autocomplete-demo.scss b/src/demo-app/autocomplete/autocomplete-demo.scss
index a74ecd15128f..e69de29bb2d1 100644
--- a/src/demo-app/autocomplete/autocomplete-demo.scss
+++ b/src/demo-app/autocomplete/autocomplete-demo.scss
@@ -1,20 +0,0 @@
-.demo-autocomplete {
-  display: flex;
-  flex-flow: row wrap;
-
-  .mat-card {
-    width: 400px;
-    margin: 24px;
-  }
-
-  .mat-form-field {
-    margin-top: 16px;
-    min-width: 200px;
-    max-width: 100%;
-  }
-}
-
-.demo-secondary-text {
-  color: rgba(0, 0, 0, 0.54);
-  margin-left: 8px;
-}
diff --git a/src/demo-app/autocomplete/autocomplete-demo.ts b/src/demo-app/autocomplete/autocomplete-demo.ts
index dc5a486e80f7..68dbf7f65ea6 100644
--- a/src/demo-app/autocomplete/autocomplete-demo.ts
+++ b/src/demo-app/autocomplete/autocomplete-demo.ts
@@ -1,7 +1,20 @@
-import {Component, ViewChild, ViewEncapsulation} from '@angular/core';
-import {FormControl, NgModel} from '@angular/forms';
-import 'rxjs/add/operator/startWith';
+import {FocusMonitor} from '@angular/cdk/a11y';
+import {
+  Component, ElementRef,
+  HostBinding,
+  Input,
+  OnChanges,
+  OnDestroy,
+  Renderer2,
+  SimpleChanges,
+  ViewEncapsulation
+} from '@angular/core';
+import {FormBuilder, FormGroup} from '@angular/forms';
+import {MdFormFieldControl} from '@angular/material';
 import 'rxjs/add/operator/map';
+import 'rxjs/add/operator/startWith';
+import {Subject} from 'rxjs/Subject';
+import {coerceBooleanProperty} from '@angular/cdk/coercion';
 
 export interface State {
   code: string;
@@ -22,115 +35,147 @@ export interface StateGroup {
   preserveWhitespaces: false,
 })
 export class AutocompleteDemo {
-  stateCtrl: FormControl;
-  currentState = '';
-  currentGroupedState = '';
-  topHeightCtrl = new FormControl(0);
-
-  reactiveStates: any;
-  tdStates: any[];
-
-  tdDisabled = false;
-
-  @ViewChild(NgModel) modelDir: NgModel;
-
-  groupedStates: StateGroup[];
-  filteredGroupedStates: StateGroup[];
-  states: State[] = [
-    {code: 'AL', name: 'Alabama'},
-    {code: 'AK', name: 'Alaska'},
-    {code: 'AZ', name: 'Arizona'},
-    {code: 'AR', name: 'Arkansas'},
-    {code: 'CA', name: 'California'},
-    {code: 'CO', name: 'Colorado'},
-    {code: 'CT', name: 'Connecticut'},
-    {code: 'DE', name: 'Delaware'},
-    {code: 'FL', name: 'Florida'},
-    {code: 'GA', name: 'Georgia'},
-    {code: 'HI', name: 'Hawaii'},
-    {code: 'ID', name: 'Idaho'},
-    {code: 'IL', name: 'Illinois'},
-    {code: 'IN', name: 'Indiana'},
-    {code: 'IA', name: 'Iowa'},
-    {code: 'KS', name: 'Kansas'},
-    {code: 'KY', name: 'Kentucky'},
-    {code: 'LA', name: 'Louisiana'},
-    {code: 'ME', name: 'Maine'},
-    {code: 'MD', name: 'Maryland'},
-    {code: 'MA', name: 'Massachusetts'},
-    {code: 'MI', name: 'Michigan'},
-    {code: 'MN', name: 'Minnesota'},
-    {code: 'MS', name: 'Mississippi'},
-    {code: 'MO', name: 'Missouri'},
-    {code: 'MT', name: 'Montana'},
-    {code: 'NE', name: 'Nebraska'},
-    {code: 'NV', name: 'Nevada'},
-    {code: 'NH', name: 'New Hampshire'},
-    {code: 'NJ', name: 'New Jersey'},
-    {code: 'NM', name: 'New Mexico'},
-    {code: 'NY', name: 'New York'},
-    {code: 'NC', name: 'North Carolina'},
-    {code: 'ND', name: 'North Dakota'},
-    {code: 'OH', name: 'Ohio'},
-    {code: 'OK', name: 'Oklahoma'},
-    {code: 'OR', name: 'Oregon'},
-    {code: 'PA', name: 'Pennsylvania'},
-    {code: 'RI', name: 'Rhode Island'},
-    {code: 'SC', name: 'South Carolina'},
-    {code: 'SD', name: 'South Dakota'},
-    {code: 'TN', name: 'Tennessee'},
-    {code: 'TX', name: 'Texas'},
-    {code: 'UT', name: 'Utah'},
-    {code: 'VT', name: 'Vermont'},
-    {code: 'VA', name: 'Virginia'},
-    {code: 'WA', name: 'Washington'},
-    {code: 'WV', name: 'West Virginia'},
-    {code: 'WI', name: 'Wisconsin'},
-    {code: 'WY', name: 'Wyoming'},
-  ];
-
-  constructor() {
-    this.tdStates = this.states;
-    this.stateCtrl = new FormControl({code: 'CA', name: 'California'});
-    this.reactiveStates = this.stateCtrl.valueChanges
-        .startWith(this.stateCtrl.value)
-        .map(val => this.displayFn(val))
-        .map(name => this.filterStates(name));
-
-    this.filteredGroupedStates = this.groupedStates = this.states.reduce((groups, state) => {
-      let group = groups.find(g => g.letter === state.name[0]);
-
-      if (!group) {
-        group = { letter: state.name[0], states: [] };
-        groups.push(group);
+
+}
+
+export class MyTel {
+  constructor(public area: string, public exchange: string, public subscriber: string) {}
+}
+
+@Component({
+  moduleId: module.id,
+  selector: 'my-tel-input',
+  template: `
+    <style>
+      div {
+        display: flex;
       }
+      input {
+        border: none;
+        background: none;
+        padding: 0;
+        outline: none;
+        font: inherit;
+        text-align: center;
+      }
+      span {
+        opacity: 0;
+        transition: opacity 200ms;
+      }
+      :host.floating span {
+        opacity: 1;
+      }
+    </style>
+    
+    <div [formGroup]="parts">
+      <input class="area" formControlName="area" size="3" [disabled]="disabled">
+      <span>&ndash;</span>
+      <input class="exchange" formControlName="exchange" size="3" [disabled]="disabled">
+      <span>&ndash;</span>
+      <input class="subscriber" formControlName="subscriber" size="4" [disabled]="disabled">
+    </div>
+  `,
+  providers: [{provide: MdFormFieldControl, useExisting: MyTelInput}],
+})
+export class MyTelInput implements MdFormFieldControl<MyTel>, OnDestroy {
+  static nextId = 0;
+
+  parts: FormGroup;
+
+  stateChanges = new Subject<void>();
+
+  focused = false;
+
+  ngControl = null;
 
-      group.states.push({ code: state.code, name: state.name });
+  errorState = false;
 
-      return groups;
-    }, [] as StateGroup[]);
+  controlType = 'my-tel-input';
+
+  get empty() {
+    let n = this.parts.value;
+    return !n.area && !n.exchange && !n.subscriber;
   }
 
-  displayFn(value: any): string {
-    return value && typeof value === 'object' ? value.name : value;
+  @HostBinding('class.floating')
+  get shouldPlaceholderFloat() {
+    return this.focused || !this.empty;
   }
 
-  filterStates(val: string) {
-    return val ? this._filter(this.states, val) : this.states;
+  @HostBinding() id = `my-tel-input-${MyTelInput.nextId++}`;
+
+  @HostBinding('attr.aria-describedby') describedBy = '';
+
+  @Input()
+  get placeholder() {
+    return this._placeholder;
   }
+  set placeholder(plh) {
+    this._placeholder = plh;
+    this.stateChanges.next();
+  }
+  private _placeholder: string;
 
-  filterStateGroups(val: string) {
-    if (val) {
-      return this.groupedStates
-        .map(group => ({ letter: group.letter, states: this._filter(group.states, val) }))
-        .filter(group => group.states.length > 0);
+  @Input()
+  get required() {
+    return this._required;
+  }
+  set required(req) {
+    this._required = coerceBooleanProperty(req);
+    this.stateChanges.next();
+  }
+  private _required = false;
+
+  @Input()
+  get disabled() {
+    return this._disabled;
+  }
+  set disabled(dis) {
+    this._disabled = coerceBooleanProperty(dis);
+    this.stateChanges.next();
+  }
+  private _disabled = false;
+
+  @Input()
+  get value(): MyTel | null {
+    let n = this.parts.value;
+    if (n.area.length == 3 && n.exchange.length == 3 && n.subscriber.length == 4) {
+      return new MyTel(n.area, n.exchange, n.subscriber);
     }
+    return null;
+  }
+  set value(tel: MyTel | null) {
+    tel = tel || new MyTel('', '', '');
+    this.parts.setValue({area: tel.area, exchange: tel.exchange, subscriber: tel.subscriber});
+    this.stateChanges.next();
+  }
+
+  constructor(fb: FormBuilder, private fm: FocusMonitor, private elRef: ElementRef,
+              renderer: Renderer2) {
+    this.parts =  fb.group({
+      'area': '',
+      'exchange': '',
+      'subscriber': '',
+    });
+
+    fm.monitor(elRef.nativeElement, renderer, true).subscribe((origin) => {
+      this.focused = !!origin;
+      this.stateChanges.next();
+    });
+  }
+
+  ngOnDestroy() {
+    this.stateChanges.complete();
+    this.fm.stopMonitoring(this.elRef.nativeElement);
+  }
 
-    return this.groupedStates;
+  setDescribedByIds(ids: string[]) {
+    this.describedBy = ids.join(' ');
   }
 
-  private _filter(states: State[], val: string) {
-    const filterValue = val.toLowerCase();
-    return states.filter(state => state.name.toLowerCase().startsWith(filterValue));
+  onContainerClick(event: MouseEvent) {
+    if ((event.target as Element).tagName.toLowerCase() != 'input') {
+      this.elRef.nativeElement.querySelector('input').focus();
+    }
   }
 }
diff --git a/src/demo-app/demo-app/demo-module.ts b/src/demo-app/demo-app/demo-module.ts
index ed2841168317..14dd7e1dccf0 100644
--- a/src/demo-app/demo-app/demo-module.ts
+++ b/src/demo-app/demo-app/demo-module.ts
@@ -3,7 +3,7 @@ import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
 import {FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {RouterModule} from '@angular/router';
-import {AutocompleteDemo} from '../autocomplete/autocomplete-demo';
+import {AutocompleteDemo, MyTelInput} from '../autocomplete/autocomplete-demo';
 import {BaselineDemo} from '../baseline/baseline-demo';
 import {ButtonToggleDemo} from '../button-toggle/button-toggle-demo';
 import {ButtonDemo} from '../button/button-demo';
@@ -109,6 +109,7 @@ import {DEMO_APP_ROUTES} from './routes';
     ToolbarDemo,
     TooltipDemo,
     TypographyDemo,
+    MyTelInput,
   ],
   providers: [
     {provide: OverlayContainer, useClass: FullscreenOverlayContainer},
diff --git a/src/lib/form-field/form-field-control.ts b/src/lib/form-field/form-field-control.ts
index f2f006421a44..c8d02dd6e97c 100644
--- a/src/lib/form-field/form-field-control.ts
+++ b/src/lib/form-field/form-field-control.ts
@@ -13,7 +13,7 @@ import {NgControl} from '@angular/forms';
 /** An interface which allows a control to work inside of a `MatFormField`. */
 export abstract class MatFormFieldControl<T> {
   /** The value of the control. */
-  value: T;
+  value: T | null;
 
   /**
    * Stream that emits whenever the state of the control changes such that the parent `MatFormField`

From cd94716a85e34f2529df6005d1185982b0083eed Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Fri, 29 Sep 2017 14:14:41 -0700
Subject: [PATCH 3/8] update md --> mat

---
 .../creating-a-custom-form-field-control.md   |  35 +--
 .../autocomplete/autocomplete-demo.html       |  79 +++++-
 .../autocomplete/autocomplete-demo.scss       |  20 ++
 .../autocomplete/autocomplete-demo.ts         | 245 +++++++-----------
 src/demo-app/demo-app/demo-module.ts          |   3 +-
 src/lib/form-field/form-field.md              |   5 +-
 .../form-field-error-example.html             |   8 +-
 .../form-field-hint-example.html              |  20 +-
 .../form-field-overview-example.html          |  22 +-
 .../form-field-placeholder-example.html       |  32 +--
 .../form-field-prefix-suffix-example.html     |  18 +-
 .../form-field-theming-example.html           |  22 +-
 12 files changed, 278 insertions(+), 231 deletions(-)

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
index e5c478a38e92..3f91ea7a8a59 100644
--- a/guides/creating-a-custom-form-field-control.md
+++ b/guides/creating-a-custom-form-field-control.md
@@ -7,7 +7,10 @@ that we want to work inside the form field. For example, a phone number input th
 parts of the number into their own inputs. (Note: this is not intended to be a robust component,
 just a starting point for us to learn.)
 
-<!-- TODO(mmalerba): Link to plunker/stackblitz with complete example code -->
+<!--
+  TODO(mmalerba): Link to Plunker/StackBlitz with complete example code after beta 12.
+  (Beta 11 is missing some of the features used in the example).
+-->
 
 ```ts
 class MyTel {
@@ -66,35 +69,35 @@ class MyTelInput {
 }
 ```
 
-### Providing our component as an MdFormFieldControl
-The first step is to provide our new component as an implementation of the `MdFormFieldControl`
-interface that the `<md-form-field>` knows how to work with. To do this we will have our class
-implement `MdFormFieldControl`, since this is a generic interface we'll need to include a type
+### Providing our component as an MatFormFieldControl
+The first step is to provide our new component as an implementation of the `MatFormFieldControl`
+interface that the `<mat-form-field>` knows how to work with. To do this we will have our class
+implement `MatFormFieldControl`, since this is a generic interface we'll need to include a type
 parameter indicating the type of data our control will work with, in this case `MyTel`. We then add
 a provider to our component so that when the form field will be able to inject it as a
-`MdFormFieldControl`.
+`MatFormFieldControl`.
 
 ```ts
 @Component({
   ...
-  providers: [{provide: MdFormFieldControl, useExisting: MyTelInput}],
+  providers: [{provide: MatFormFieldControl, useExisting: MyTelInput}],
 })
-class MyTelInput implements MdFormFieldControl<MyTel> {
+class MyTelInput implements MatFormFieldControl<MyTel> {
   ...
 }
 ```
 
-This sets up our component so it can work with `<md-form-field>`, but now we need to implement the
+This sets up our component so it can work with `<mat-form-field>`, but now we need to implement the
 various methods and properties declared by the interface we just implemented. To learn more about
-the `MdFormFieldControl` interface, see its
+the `MatFormFieldControl` interface, see its
 [definition](https://github.com/angular/material2/blob/master/src/lib/form-field/form-field-control.ts).
 (Unfortunately generated API docs are not available yet, but we'll go through the methods and
 properties in this guide.) 
 
-### Implementing the methods and properties of MdFormFieldControl
+### Implementing the methods and properties of MatFormFieldControl
 #### `value`
 This property allows someone to set or get the value of our control. Its type should be the same
-type we used for the type parameter when we implemented `MdFormFieldControl`. Since our component 
+type we used for the type parameter when we implemented `MatFormFieldControl`. Since our component 
 already has a value property we don't need to do anything for this one.
 
 #### `stateChanges`
@@ -284,7 +287,7 @@ we'll use `my-tel-input` as our control type which will result in the form field
 controlType = 'my-tel-input';
 ```
 
-#### `setAriaDescribedByIds`
+#### `setAriaDescribedByIds(ids: string[])`
 This method is used by the `<mat-form-field>` to specify the IDs that should be used for the
 `aria-describedby` attribute of your component. The method has one parameter, the list of IDs, we
 just need to apply the given IDs to our host element.
@@ -297,7 +300,7 @@ setDescribedByIds(ids: string[]) {
 }
 ```
 
-#### `onContainerClick`
+#### `onContainerClick(event: MouseEvent)`
 This method will be called when the form field is clicked on. It allows your component to hook in
 and handle that click however it wants. The method has one parameter, the `MouseEvent` for the
 click. In our case we'll just focus the first `<input>` if the user isn't about to click an
@@ -328,7 +331,7 @@ the error state).
 ```html
 <mat-form-field>
   <my-tel-input placeholder="Phone number" required></my-tel-input>
-  <md-icon mdPrefix>phone</md-icon>
-  <md-hint>Include area code</md-hint>
+  <mat-icon matPrefix>phone</mat-icon>
+  <mat-hint>Include area code</mat-hint>
 </mat-form-field>
 ```
diff --git a/src/demo-app/autocomplete/autocomplete-demo.html b/src/demo-app/autocomplete/autocomplete-demo.html
index 15336e19ba47..3a844aa81a8a 100644
--- a/src/demo-app/autocomplete/autocomplete-demo.html
+++ b/src/demo-app/autocomplete/autocomplete-demo.html
@@ -1,5 +1,74 @@
-<md-form-field>
-  <my-tel-input placeholder="Phone number" required></my-tel-input>
-  <md-icon mdSuffix>phone</md-icon>
-  <md-hint>Include area code</md-hint>
-</md-form-field>
+Space above cards: <input type="number" [formControl]="topHeightCtrl">
+<div [style.height.px]="topHeightCtrl.value"></div>
+<div class="demo-autocomplete">
+  <mat-card>
+    Reactive length: {{ reactiveStates.length }}
+    <div>Reactive value: {{ stateCtrl.value | json }}</div>
+    <div>Reactive dirty: {{ stateCtrl.dirty }}</div>
+
+    <mat-form-field floatPlaceholder="never">
+      <input matInput placeholder="State" [matAutocomplete]="reactiveAuto" [formControl]="stateCtrl">
+      <mat-autocomplete #reactiveAuto="matAutocomplete" [displayWith]="displayFn">
+        <mat-option *ngFor="let state of reactiveStates | async" [value]="state">
+          <span>{{ state.name }}</span>
+          <span class="demo-secondary-text"> ({{state.code}}) </span>
+        </mat-option>
+      </mat-autocomplete>
+    </mat-form-field>
+
+    <mat-card-actions>
+      <button mat-button (click)="stateCtrl.reset()">RESET</button>
+      <button mat-button (click)="stateCtrl.setValue(states[10])">SET VALUE</button>
+      <button mat-button (click)="stateCtrl.enabled ? stateCtrl.disable() : stateCtrl.enable()">
+        TOGGLE DISABLED
+      </button>
+    </mat-card-actions>
+
+  </mat-card>
+
+  <mat-card>
+
+    <div>Template-driven value (currentState): {{ currentState }}</div>
+    <div>Template-driven dirty: {{ modelDir ? modelDir.dirty : false }}</div>
+
+    <!-- Added an ngIf below to test that autocomplete works with ngIf -->
+    <mat-form-field *ngIf="true">
+      <input matInput placeholder="State" [matAutocomplete]="tdAuto" [(ngModel)]="currentState"
+        (ngModelChange)="tdStates = filterStates(currentState)" [disabled]="tdDisabled">
+      <mat-autocomplete #tdAuto="matAutocomplete">
+        <mat-option *ngFor="let state of tdStates" [value]="state.name">
+          <span>{{ state.name }}</span>
+        </mat-option>
+      </mat-autocomplete>
+    </mat-form-field>
+
+    <mat-card-actions>
+      <button mat-button (click)="modelDir.reset()">RESET</button>
+      <button mat-button (click)="currentState='California'">SET VALUE</button>
+      <button mat-button (click)="tdDisabled=!tdDisabled">
+        TOGGLE DISABLED
+      </button>
+    </mat-card-actions>
+
+  </mat-card>
+
+  <mat-card>
+    <div>Option groups (currentGroupedState): {{ currentGroupedState }}</div>
+
+    <mat-input-container>
+      <input
+        matInput
+        placeholder="State"
+        [matAutocomplete]="groupedAuto"
+        [(ngModel)]="currentGroupedState"
+        (ngModelChange)="filteredGroupedStates = filterStateGroups(currentGroupedState)">
+    </mat-input-container>
+  </mat-card>
+</div>
+
+<mat-autocomplete #groupedAuto="matAutocomplete">
+  <mat-optgroup *ngFor="let group of filteredGroupedStates"
+    [label]="'States starting with ' + group.letter">
+    <mat-option *ngFor="let state of group.states" [value]="state.name">{{ state.name }}</mat-option>
+  </mat-optgroup>
+</mat-autocomplete>
diff --git a/src/demo-app/autocomplete/autocomplete-demo.scss b/src/demo-app/autocomplete/autocomplete-demo.scss
index e69de29bb2d1..a74ecd15128f 100644
--- a/src/demo-app/autocomplete/autocomplete-demo.scss
+++ b/src/demo-app/autocomplete/autocomplete-demo.scss
@@ -0,0 +1,20 @@
+.demo-autocomplete {
+  display: flex;
+  flex-flow: row wrap;
+
+  .mat-card {
+    width: 400px;
+    margin: 24px;
+  }
+
+  .mat-form-field {
+    margin-top: 16px;
+    min-width: 200px;
+    max-width: 100%;
+  }
+}
+
+.demo-secondary-text {
+  color: rgba(0, 0, 0, 0.54);
+  margin-left: 8px;
+}
diff --git a/src/demo-app/autocomplete/autocomplete-demo.ts b/src/demo-app/autocomplete/autocomplete-demo.ts
index 68dbf7f65ea6..dc5a486e80f7 100644
--- a/src/demo-app/autocomplete/autocomplete-demo.ts
+++ b/src/demo-app/autocomplete/autocomplete-demo.ts
@@ -1,20 +1,7 @@
-import {FocusMonitor} from '@angular/cdk/a11y';
-import {
-  Component, ElementRef,
-  HostBinding,
-  Input,
-  OnChanges,
-  OnDestroy,
-  Renderer2,
-  SimpleChanges,
-  ViewEncapsulation
-} from '@angular/core';
-import {FormBuilder, FormGroup} from '@angular/forms';
-import {MdFormFieldControl} from '@angular/material';
-import 'rxjs/add/operator/map';
+import {Component, ViewChild, ViewEncapsulation} from '@angular/core';
+import {FormControl, NgModel} from '@angular/forms';
 import 'rxjs/add/operator/startWith';
-import {Subject} from 'rxjs/Subject';
-import {coerceBooleanProperty} from '@angular/cdk/coercion';
+import 'rxjs/add/operator/map';
 
 export interface State {
   code: string;
@@ -35,147 +22,115 @@ export interface StateGroup {
   preserveWhitespaces: false,
 })
 export class AutocompleteDemo {
-
-}
-
-export class MyTel {
-  constructor(public area: string, public exchange: string, public subscriber: string) {}
-}
-
-@Component({
-  moduleId: module.id,
-  selector: 'my-tel-input',
-  template: `
-    <style>
-      div {
-        display: flex;
+  stateCtrl: FormControl;
+  currentState = '';
+  currentGroupedState = '';
+  topHeightCtrl = new FormControl(0);
+
+  reactiveStates: any;
+  tdStates: any[];
+
+  tdDisabled = false;
+
+  @ViewChild(NgModel) modelDir: NgModel;
+
+  groupedStates: StateGroup[];
+  filteredGroupedStates: StateGroup[];
+  states: State[] = [
+    {code: 'AL', name: 'Alabama'},
+    {code: 'AK', name: 'Alaska'},
+    {code: 'AZ', name: 'Arizona'},
+    {code: 'AR', name: 'Arkansas'},
+    {code: 'CA', name: 'California'},
+    {code: 'CO', name: 'Colorado'},
+    {code: 'CT', name: 'Connecticut'},
+    {code: 'DE', name: 'Delaware'},
+    {code: 'FL', name: 'Florida'},
+    {code: 'GA', name: 'Georgia'},
+    {code: 'HI', name: 'Hawaii'},
+    {code: 'ID', name: 'Idaho'},
+    {code: 'IL', name: 'Illinois'},
+    {code: 'IN', name: 'Indiana'},
+    {code: 'IA', name: 'Iowa'},
+    {code: 'KS', name: 'Kansas'},
+    {code: 'KY', name: 'Kentucky'},
+    {code: 'LA', name: 'Louisiana'},
+    {code: 'ME', name: 'Maine'},
+    {code: 'MD', name: 'Maryland'},
+    {code: 'MA', name: 'Massachusetts'},
+    {code: 'MI', name: 'Michigan'},
+    {code: 'MN', name: 'Minnesota'},
+    {code: 'MS', name: 'Mississippi'},
+    {code: 'MO', name: 'Missouri'},
+    {code: 'MT', name: 'Montana'},
+    {code: 'NE', name: 'Nebraska'},
+    {code: 'NV', name: 'Nevada'},
+    {code: 'NH', name: 'New Hampshire'},
+    {code: 'NJ', name: 'New Jersey'},
+    {code: 'NM', name: 'New Mexico'},
+    {code: 'NY', name: 'New York'},
+    {code: 'NC', name: 'North Carolina'},
+    {code: 'ND', name: 'North Dakota'},
+    {code: 'OH', name: 'Ohio'},
+    {code: 'OK', name: 'Oklahoma'},
+    {code: 'OR', name: 'Oregon'},
+    {code: 'PA', name: 'Pennsylvania'},
+    {code: 'RI', name: 'Rhode Island'},
+    {code: 'SC', name: 'South Carolina'},
+    {code: 'SD', name: 'South Dakota'},
+    {code: 'TN', name: 'Tennessee'},
+    {code: 'TX', name: 'Texas'},
+    {code: 'UT', name: 'Utah'},
+    {code: 'VT', name: 'Vermont'},
+    {code: 'VA', name: 'Virginia'},
+    {code: 'WA', name: 'Washington'},
+    {code: 'WV', name: 'West Virginia'},
+    {code: 'WI', name: 'Wisconsin'},
+    {code: 'WY', name: 'Wyoming'},
+  ];
+
+  constructor() {
+    this.tdStates = this.states;
+    this.stateCtrl = new FormControl({code: 'CA', name: 'California'});
+    this.reactiveStates = this.stateCtrl.valueChanges
+        .startWith(this.stateCtrl.value)
+        .map(val => this.displayFn(val))
+        .map(name => this.filterStates(name));
+
+    this.filteredGroupedStates = this.groupedStates = this.states.reduce((groups, state) => {
+      let group = groups.find(g => g.letter === state.name[0]);
+
+      if (!group) {
+        group = { letter: state.name[0], states: [] };
+        groups.push(group);
       }
-      input {
-        border: none;
-        background: none;
-        padding: 0;
-        outline: none;
-        font: inherit;
-        text-align: center;
-      }
-      span {
-        opacity: 0;
-        transition: opacity 200ms;
-      }
-      :host.floating span {
-        opacity: 1;
-      }
-    </style>
-    
-    <div [formGroup]="parts">
-      <input class="area" formControlName="area" size="3" [disabled]="disabled">
-      <span>&ndash;</span>
-      <input class="exchange" formControlName="exchange" size="3" [disabled]="disabled">
-      <span>&ndash;</span>
-      <input class="subscriber" formControlName="subscriber" size="4" [disabled]="disabled">
-    </div>
-  `,
-  providers: [{provide: MdFormFieldControl, useExisting: MyTelInput}],
-})
-export class MyTelInput implements MdFormFieldControl<MyTel>, OnDestroy {
-  static nextId = 0;
-
-  parts: FormGroup;
-
-  stateChanges = new Subject<void>();
-
-  focused = false;
-
-  ngControl = null;
 
-  errorState = false;
+      group.states.push({ code: state.code, name: state.name });
 
-  controlType = 'my-tel-input';
-
-  get empty() {
-    let n = this.parts.value;
-    return !n.area && !n.exchange && !n.subscriber;
+      return groups;
+    }, [] as StateGroup[]);
   }
 
-  @HostBinding('class.floating')
-  get shouldPlaceholderFloat() {
-    return this.focused || !this.empty;
+  displayFn(value: any): string {
+    return value && typeof value === 'object' ? value.name : value;
   }
 
-  @HostBinding() id = `my-tel-input-${MyTelInput.nextId++}`;
-
-  @HostBinding('attr.aria-describedby') describedBy = '';
-
-  @Input()
-  get placeholder() {
-    return this._placeholder;
+  filterStates(val: string) {
+    return val ? this._filter(this.states, val) : this.states;
   }
-  set placeholder(plh) {
-    this._placeholder = plh;
-    this.stateChanges.next();
-  }
-  private _placeholder: string;
 
-  @Input()
-  get required() {
-    return this._required;
-  }
-  set required(req) {
-    this._required = coerceBooleanProperty(req);
-    this.stateChanges.next();
-  }
-  private _required = false;
-
-  @Input()
-  get disabled() {
-    return this._disabled;
-  }
-  set disabled(dis) {
-    this._disabled = coerceBooleanProperty(dis);
-    this.stateChanges.next();
-  }
-  private _disabled = false;
-
-  @Input()
-  get value(): MyTel | null {
-    let n = this.parts.value;
-    if (n.area.length == 3 && n.exchange.length == 3 && n.subscriber.length == 4) {
-      return new MyTel(n.area, n.exchange, n.subscriber);
+  filterStateGroups(val: string) {
+    if (val) {
+      return this.groupedStates
+        .map(group => ({ letter: group.letter, states: this._filter(group.states, val) }))
+        .filter(group => group.states.length > 0);
     }
-    return null;
-  }
-  set value(tel: MyTel | null) {
-    tel = tel || new MyTel('', '', '');
-    this.parts.setValue({area: tel.area, exchange: tel.exchange, subscriber: tel.subscriber});
-    this.stateChanges.next();
-  }
-
-  constructor(fb: FormBuilder, private fm: FocusMonitor, private elRef: ElementRef,
-              renderer: Renderer2) {
-    this.parts =  fb.group({
-      'area': '',
-      'exchange': '',
-      'subscriber': '',
-    });
-
-    fm.monitor(elRef.nativeElement, renderer, true).subscribe((origin) => {
-      this.focused = !!origin;
-      this.stateChanges.next();
-    });
-  }
-
-  ngOnDestroy() {
-    this.stateChanges.complete();
-    this.fm.stopMonitoring(this.elRef.nativeElement);
-  }
 
-  setDescribedByIds(ids: string[]) {
-    this.describedBy = ids.join(' ');
+    return this.groupedStates;
   }
 
-  onContainerClick(event: MouseEvent) {
-    if ((event.target as Element).tagName.toLowerCase() != 'input') {
-      this.elRef.nativeElement.querySelector('input').focus();
-    }
+  private _filter(states: State[], val: string) {
+    const filterValue = val.toLowerCase();
+    return states.filter(state => state.name.toLowerCase().startsWith(filterValue));
   }
 }
diff --git a/src/demo-app/demo-app/demo-module.ts b/src/demo-app/demo-app/demo-module.ts
index 14dd7e1dccf0..ed2841168317 100644
--- a/src/demo-app/demo-app/demo-module.ts
+++ b/src/demo-app/demo-app/demo-module.ts
@@ -3,7 +3,7 @@ import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
 import {FormsModule, ReactiveFormsModule} from '@angular/forms';
 import {RouterModule} from '@angular/router';
-import {AutocompleteDemo, MyTelInput} from '../autocomplete/autocomplete-demo';
+import {AutocompleteDemo} from '../autocomplete/autocomplete-demo';
 import {BaselineDemo} from '../baseline/baseline-demo';
 import {ButtonToggleDemo} from '../button-toggle/button-toggle-demo';
 import {ButtonDemo} from '../button/button-demo';
@@ -109,7 +109,6 @@ import {DEMO_APP_ROUTES} from './routes';
     ToolbarDemo,
     TooltipDemo,
     TypographyDemo,
-    MyTelInput,
   ],
   providers: [
     {provide: OverlayContainer, useClass: FullscreenOverlayContainer},
diff --git a/src/lib/form-field/form-field.md b/src/lib/form-field/form-field.md
index 1a911c5c89e6..af7391792a34 100644
--- a/src/lib/form-field/form-field.md
+++ b/src/lib/form-field/form-field.md
@@ -85,7 +85,8 @@ the prefix. Similarly, adding `matSuffix` will designate it as the suffix.
 ### Custom form field controls
 In addition to the form field controls that Angular Material provides, it is possible to create
 custom form field controls that work with `<mat-form-field>` in the same way. For additional
-information on this see the guide on [Creating Custom mat-form-field Controls](TODO).
+information on this see the guide on
+[Creating Custom mat-form-field Controls](https://material.angular.io/guide/creating-a-custom-form-field-control).
 
 ### Theming
 `<mat-form-field>` has a `color` property which can be set to `primary`, `accent`, or `warn`. This
@@ -121,7 +122,7 @@ element.
 This error occurs you have added multiple hints for the same side. Keep in mind that the `hintLabel`
 property adds a hint to the start side.
 
-#### Error: md-form-field must contain a MdFormFieldControl
+#### Error: mat-form-field must contain a MatFormFieldControl
 This error occurs when you have not added a form field control to your form field. If your form
 field contains a native `<input>` or `<textarea>` element, make sure you've added the `matInput`
 directive to it. Other components that can act as a form field control include `<mat-select>`,
diff --git a/src/material-examples/form-field-error/form-field-error-example.html b/src/material-examples/form-field-error/form-field-error-example.html
index 82eab33a3eb0..d6bbe9761dae 100644
--- a/src/material-examples/form-field-error/form-field-error-example.html
+++ b/src/material-examples/form-field-error/form-field-error-example.html
@@ -1,6 +1,6 @@
 <div class="example-container">
-  <md-form-field>
-    <input mdInput placeholder="Enter your email" [formControl]="email" required>
-    <md-error *ngIf="!email.valid">{{getErrorMessage()}}</md-error>
-  </md-form-field>
+  <mat-form-field>
+    <input matInput placeholder="Enter your email" [formControl]="email" required>
+    <mat-error *ngIf="!email.valid">{{getErrorMessage()}}</mat-error>
+  </mat-form-field>
 </div>
diff --git a/src/material-examples/form-field-hint/form-field-hint-example.html b/src/material-examples/form-field-hint/form-field-hint-example.html
index c9993ada4207..a402d988c0fa 100644
--- a/src/material-examples/form-field-hint/form-field-hint-example.html
+++ b/src/material-examples/form-field-hint/form-field-hint-example.html
@@ -1,13 +1,13 @@
 <div class="example-container">
-  <md-form-field hintLabel="Max 10 characters">
-    <input mdInput #input maxlength="10" placeholder="Enter some input">
-    <md-hint align="end">{{input.value?.length || 0}}/10</md-hint>
-  </md-form-field>
+  <mat-form-field hintLabel="Max 10 characters">
+    <input matInput #input maxlength="10" placeholder="Enter some input">
+    <mat-hint align="end">{{input.value?.length || 0}}/10</mat-hint>
+  </mat-form-field>
 
-  <md-form-field>
-    <md-select placeholder="Select me">
-      <md-option value="option">Option</md-option>
-    </md-select>
-    <md-hint align="end">Here's the dropdown arrow ^</md-hint>
-  </md-form-field>
+  <mat-form-field>
+    <mat-select placeholder="Select me">
+      <mat-option value="option">Option</mat-option>
+    </mat-select>
+    <mat-hint align="end">Here's the dropdown arrow ^</mat-hint>
+  </mat-form-field>
 </div>
diff --git a/src/material-examples/form-field-overview/form-field-overview-example.html b/src/material-examples/form-field-overview/form-field-overview-example.html
index 7c8183878852..6427e7df313b 100644
--- a/src/material-examples/form-field-overview/form-field-overview-example.html
+++ b/src/material-examples/form-field-overview/form-field-overview-example.html
@@ -1,15 +1,15 @@
 <div class="example-container">
-  <md-form-field>
-    <input mdInput placeholder="Input">
-  </md-form-field>
+  <mat-form-field>
+    <input matInput placeholder="Input">
+  </mat-form-field>
 
-  <md-form-field>
-    <textarea mdInput placeholder="Textarea"></textarea>
-  </md-form-field>
+  <mat-form-field>
+    <textarea matInput placeholder="Textarea"></textarea>
+  </mat-form-field>
 
-  <md-form-field>
-    <md-select placeholder="Select">
-      <md-option value="option">Option</md-option>
-    </md-select>
-  </md-form-field>
+  <mat-form-field>
+    <mat-select placeholder="Select">
+      <mat-option value="option">Option</mat-option>
+    </mat-select>
+  </mat-form-field>
 </div>
diff --git a/src/material-examples/form-field-placeholder/form-field-placeholder-example.html b/src/material-examples/form-field-placeholder/form-field-placeholder-example.html
index 73c5456022a6..01ef48d34310 100644
--- a/src/material-examples/form-field-placeholder/form-field-placeholder-example.html
+++ b/src/material-examples/form-field-placeholder/form-field-placeholder-example.html
@@ -1,29 +1,29 @@
 <div class="example-container">
   <form class="example-container" [formGroup]="options">
-    <md-checkbox formControlName="hideRequired">Hide required marker</md-checkbox>
+    <mat-checkbox formControlName="hideRequired">Hide required marker</mat-checkbox>
     <div>
       <label>Float placeholder: </label>
-      <md-radio-group formControlName="floatPlaceholder">
-        <md-radio-button value="auto">Auto</md-radio-button>
-        <md-radio-button value="always">Always</md-radio-button>
-        <md-radio-button value="never">Never</md-radio-button>
-      </md-radio-group>
+      <mat-radio-group formControlName="floatPlaceholder">
+        <mat-radio-button value="auto">Auto</mat-radio-button>
+        <mat-radio-button value="always">Always</mat-radio-button>
+        <mat-radio-button value="never">Never</mat-radio-button>
+      </mat-radio-group>
     </div>
   </form>
 
-  <md-form-field
+  <mat-form-field
       [hideRequiredMarker]="options.value.hideRequired"
       [floatPlaceholder]="options.value.floatPlaceholder">
-    <input mdInput placeholder="Simple placeholder" required>
-  </md-form-field>
+    <input matInput placeholder="Simple placeholder" required>
+  </mat-form-field>
 
-  <md-form-field
+  <mat-form-field
       [hideRequiredMarker]="options.value.hideRequired"
       [floatPlaceholder]="options.value.floatPlaceholder">
-    <md-select required>
-      <md-option>-- None --</md-option>
-      <md-option value="option">Option</md-option>
-    </md-select>
-    <md-placeholder><md-icon>favorite</md-icon> <b> Fancy</b> <i> placeholder</i></md-placeholder>
-  </md-form-field>
+    <mat-select required>
+      <mat-option>-- None --</mat-option>
+      <mat-option value="option">Option</mat-option>
+    </mat-select>
+    <mat-placeholder><mat-icon>favorite</mat-icon> <b> Fancy</b> <i> placeholder</i></mat-placeholder>
+  </mat-form-field>
 </div>
diff --git a/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html
index 3eef5b2a4d8b..e3099d906804 100644
--- a/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html
+++ b/src/material-examples/form-field-prefix-suffix/form-field-prefix-suffix-example.html
@@ -1,12 +1,12 @@
 <div class="example-container">
-  <md-form-field>
-    <input mdInput placeholder="Enter your password" [type]="hide ? 'password' : 'text'">
-    <md-icon mdSuffix (click)="hide = !hide">{{hide ? 'visibility' : 'visibility_off'}}</md-icon>
-  </md-form-field>
+  <mat-form-field>
+    <input matInput placeholder="Enter your password" [type]="hide ? 'password' : 'text'">
+    <mat-icon matSuffix (click)="hide = !hide">{{hide ? 'visibility' : 'visibility_off'}}</mat-icon>
+  </mat-form-field>
 
-  <md-form-field>
-    <input mdInput placeholder="Amount" type="number" class="example-right-align">
-    <span mdPrefix>$&nbsp;</span>
-    <span mdSuffix>.00</span>
-  </md-form-field>
+  <mat-form-field>
+    <input matInput placeholder="Amount" type="number" class="example-right-align">
+    <span matPrefix>$&nbsp;</span>
+    <span matSuffix>.00</span>
+  </mat-form-field>
 </div>
diff --git a/src/material-examples/form-field-theming/form-field-theming-example.html b/src/material-examples/form-field-theming/form-field-theming-example.html
index 14621e56ff71..0eb010caa449 100644
--- a/src/material-examples/form-field-theming/form-field-theming-example.html
+++ b/src/material-examples/form-field-theming/form-field-theming-example.html
@@ -1,14 +1,14 @@
 <form class="example-container" [formGroup]="options" [style.fontSize.px]="getFontSize()">
-  <md-form-field [color]="options.value.color">
-    <md-select placeholder="Color" formControlName="color">
-      <md-option value="primary">Primary</md-option>
-      <md-option value="accent">Accent</md-option>
-      <md-option value="warn">Warn</md-option>
-    </md-select>
-  </md-form-field>
+  <mat-form-field [color]="options.value.color">
+    <mat-select placeholder="Color" formControlName="color">
+      <mat-option value="primary">Primary</mat-option>
+      <mat-option value="accent">Accent</mat-option>
+      <mat-option value="warn">Warn</mat-option>
+    </mat-select>
+  </mat-form-field>
 
-  <md-form-field [color]="options.value.color">
-    <input mdInput type="number" placeholder="Font size (px)" formControlName="fontSize" min="10">
-    <md-error *ngIf="!options.get('fontSize').valid">Min size: 10px</md-error>
-  </md-form-field>
+  <mat-form-field [color]="options.value.color">
+    <input matInput type="number" placeholder="Font size (px)" formControlName="fontSize" min="10">
+    <mat-error *ngIf="!options.get('fontSize').valid">Min size: 10px</mat-error>
+  </mat-form-field>
 </form>

From c36812c471532f66caeb2e57590096a6c33d3578 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Mon, 2 Oct 2017 12:08:28 -0700
Subject: [PATCH 4/8] do grammar good

---
 .../creating-a-custom-form-field-control.md   | 34 +++++++++----------
 src/lib/form-field/form-field.md              | 12 +++----
 .../form-field-error-example.html             |  2 +-
 .../form-field-theming-example.html           |  2 +-
 4 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
index 3f91ea7a8a59..9afa91bdd35c 100644
--- a/guides/creating-a-custom-form-field-control.md
+++ b/guides/creating-a-custom-form-field-control.md
@@ -1,8 +1,8 @@
 It is possible to create custom form field controls that can be used inside `<mat-form-field>`. This
-can be useful if you need to create a components that shares a lot of common behavior with a form
+can be useful if you need to create a component that shares a lot of common behavior with a form
 field, but adds some additional logic.
 
-In order to learn how to build custom form field controls, lets start with a simple input component
+In order to learn how to build custom form field controls, let's start with a simple input component
 that we want to work inside the form field. For example, a phone number input that segments the
 parts of the number into their own inputs. (Note: this is not intended to be a robust component,
 just a starting point for us to learn.)
@@ -69,12 +69,12 @@ class MyTelInput {
 }
 ```
 
-### Providing our component as an MatFormFieldControl
+### Providing our component as a MatFormFieldControl
 The first step is to provide our new component as an implementation of the `MatFormFieldControl`
-interface that the `<mat-form-field>` knows how to work with. To do this we will have our class
-implement `MatFormFieldControl`, since this is a generic interface we'll need to include a type
+interface that the `<mat-form-field>` knows how to work with. To do this, we will have our class
+implement `MatFormFieldControl`. Since this is a generic interface, we'll need to include a type
 parameter indicating the type of data our control will work with, in this case `MyTel`. We then add
-a provider to our component so that when the form field will be able to inject it as a
+a provider to our component so that the form field will be able to inject it as a
 `MatFormFieldControl`.
 
 ```ts
@@ -98,7 +98,7 @@ properties in this guide.)
 #### `value`
 This property allows someone to set or get the value of our control. Its type should be the same
 type we used for the type parameter when we implemented `MatFormFieldControl`. Since our component 
-already has a value property we don't need to do anything for this one.
+already has a value property, we don't need to do anything for this one.
 
 #### `stateChanges`
 Because the `<mat-form-field>` used the `OnPush` change detection strategy, we need to let it know
@@ -106,7 +106,7 @@ when something happens in the form field control that may require the form field
 detection. We do this via the `stateChanges` property. So far the only thing the form field needs to
 know about is when the value changes. We'll need to emit on the stateChanges stream when that
 happens, and as we continue flushing out these properties we'll likely find more places we need to
-emit. We should also make sure to complete `stateChanges` when our component is destroyed
+emit. We should also make sure to complete `stateChanges` when our component is destroyed.
 
 ```ts
 stateChanges = new Subject<void>();
@@ -123,7 +123,7 @@ ngOnDestory() {
 
 #### `id`
 This property should return the ID of an element in the component's template that we want the
-`<mat-form-field>` to associate all of its labels and hints with. In this case we'll use the host
+`<mat-form-field>` to associate all of its labels and hints with. In this case, we'll use the host
 element and just generate a unique ID for it.
 
 ```ts
@@ -153,8 +153,8 @@ private _placeholder: string;
 
 #### `ngControl`
 This property allows the form field control to specify the `@angular/forms` control that is bound to
-this component. Since we haven't set up our component to act as a `ControlValueAccessor` we'll just
-set this to `null` in our component. In any real component you would probably want to implement
+this component. Since we haven't set up our component to act as a `ControlValueAccessor`, we'll just
+set this to `null` in our component. In any real component, you would probably want to implement
 `ControlValueAccessor` so that your component can work with `formControl` and `ngModel`.
 
 ```ts
@@ -171,7 +171,7 @@ constructor(..., @Optional() @Self() public ngControl: NgControl) { ... }
 
 #### `focused`
 This property indicates whether or not the form field control should be considered to be in a
-focused state. When it is in a focused state the form field is displayed with a solid color
+focused state. When it is in a focused state, the form field is displayed with a solid color
 underline. For the purposes of our component, we want to consider it focused if any of the part
 inputs are focused. We can use the `FocusMonitor` from `@angular/cdk` to easily check this. We also
 need to remember to emit on the `stateChanges` stream so change detection can happen.
@@ -195,7 +195,7 @@ ngOnDestroy() {
 ```
 
 #### `empty`
-This property indicates whether the form field control is empty. For our control we'll consider it
+This property indicates whether the form field control is empty. For our control, we'll consider it
 empty if all of the parts are empty.
 
 ```ts
@@ -208,8 +208,8 @@ get empty() {
 #### `shouldPlaceholderFloat`
 This property is used to indicate whether the placeholder should be in the floating position. We'll
 use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
-Since the placeholder will be overlapping our control when when its not floating, we should hide the
-`–` characters when its not floating.
+Since the placeholder will be overlapping our control when when it's not floating, we should hide
+the `–` characters when it's not floating.
 
 ```ts
 @HostBinding('class.floating')
@@ -270,7 +270,7 @@ private _disabled = false;
 
 #### `errorState`
 This property indicates whether the associated `NgControl` is in an error state. Since we're not
-using an `NgControl` in this example we don't need to do anything other than just set it to `false`.
+using an `NgControl` in this example, we don't need to do anything other than just set it to `false`.
 
 ```ts
 errorState = false;
@@ -316,7 +316,7 @@ onContainerClick(event: MouseEvent) {
 
 ### Trying it out
 Now that we've fully implemented the interface, we're ready to try our component out! All we need to
-do is place it inside of a `<mat-form-filed>`
+do is place it inside of a `<mat-form-field>`
 
 ```html
 <mat-form-field>
diff --git a/src/lib/form-field/form-field.md b/src/lib/form-field/form-field.md
index af7391792a34..9ea6530cd577 100644
--- a/src/lib/form-field/form-field.md
+++ b/src/lib/form-field/form-field.md
@@ -2,7 +2,7 @@
 [Text field](https://material.io/guidelines/components/text-fields.html) styles such as the
 underline, floating label, and hint messages.
 
-In this document "form field" refers to the wrapper component `<mat-form-field>` and
+In this document, "form field" refers to the wrapper component `<mat-form-field>` and
 "form field control" refers to the component that the `<mat-form-field>` is wrapping
 (e.g. the input, textarea, select, etc.)
 
@@ -52,7 +52,7 @@ in RTL), and one end-aligned.
 
 Hint labels are specified in one of two ways: either by using the `hintLabel` property of
 `<mat-form-field>`, or by adding a `<mat-hint>` element inside the form field. When adding a hint
-via the `hintLabel` property it will be treated as the start hint. Hints added via the
+via the `hintLabel` property, it will be treated as the start hint. Hints added via the
 `<mat-hint>` hint element can be added to either side by setting the `align` property on
 `<mat-hint>` to either `start` or `end`. Attempting to add multiple hints to the same side will
 raise an error.
@@ -105,8 +105,8 @@ mat-form-field.mat-form-field {
 <!-- example(form-field-theming) -->
 
 ### Accessibility
-If a floating placeholder is specified it will be automatically used as the label for the form field
-control. If no floating placeholder is specified the user should label the form field control
+If a floating placeholder is specified, it will be automatically used as the label for the form field
+control. If no floating placeholder is specified, the user should label the form field control
 themselves using `aria-label`, `aria-labelledby` or `<label for=...>`.
 
 Any errors and hints added to the form field are automatically added to the form field control's
@@ -119,8 +119,8 @@ included both a `placeholder` property on your form field control and a `<mat-pl
 element.
 
 #### Error: A hint was already declared for align="..."
-This error occurs you have added multiple hints for the same side. Keep in mind that the `hintLabel`
-property adds a hint to the start side.
+This error occurs if you have added multiple hints for the same side. Keep in mind that the
+`hintLabel` property adds a hint to the start side.
 
 #### Error: mat-form-field must contain a MatFormFieldControl
 This error occurs when you have not added a form field control to your form field. If your form
diff --git a/src/material-examples/form-field-error/form-field-error-example.html b/src/material-examples/form-field-error/form-field-error-example.html
index d6bbe9761dae..4b06c9b07b86 100644
--- a/src/material-examples/form-field-error/form-field-error-example.html
+++ b/src/material-examples/form-field-error/form-field-error-example.html
@@ -1,6 +1,6 @@
 <div class="example-container">
   <mat-form-field>
     <input matInput placeholder="Enter your email" [formControl]="email" required>
-    <mat-error *ngIf="!email.valid">{{getErrorMessage()}}</mat-error>
+    <mat-error *ngIf="email.invalid">{{getErrorMessage()}}</mat-error>
   </mat-form-field>
 </div>
diff --git a/src/material-examples/form-field-theming/form-field-theming-example.html b/src/material-examples/form-field-theming/form-field-theming-example.html
index 0eb010caa449..8545ebefd2a6 100644
--- a/src/material-examples/form-field-theming/form-field-theming-example.html
+++ b/src/material-examples/form-field-theming/form-field-theming-example.html
@@ -9,6 +9,6 @@
 
   <mat-form-field [color]="options.value.color">
     <input matInput type="number" placeholder="Font size (px)" formControlName="fontSize" min="10">
-    <mat-error *ngIf="!options.get('fontSize').valid">Min size: 10px</mat-error>
+    <mat-error *ngIf="options.get('fontSize').invalid">Min size: 10px</mat-error>
   </mat-form-field>
 </form>

From 0d448e4389e623287f01d9382345ed3f2f84fd78 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Tue, 3 Oct 2017 09:04:57 -0700
Subject: [PATCH 5/8] fix some errors in guide code

---
 guides/creating-a-custom-form-field-control.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
index 9afa91bdd35c..fc4cf494f21c 100644
--- a/guides/creating-a-custom-form-field-control.md
+++ b/guides/creating-a-custom-form-field-control.md
@@ -101,7 +101,7 @@ type we used for the type parameter when we implemented `MatFormFieldControl`. S
 already has a value property, we don't need to do anything for this one.
 
 #### `stateChanges`
-Because the `<mat-form-field>` used the `OnPush` change detection strategy, we need to let it know
+Because the `<mat-form-field>` uses the `OnPush` change detection strategy, we need to let it know
 when something happens in the form field control that may require the form field to run change
 detection. We do this via the `stateChanges` property. So far the only thing the form field needs to
 know about is when the value changes. We'll need to emit on the stateChanges stream when that
@@ -113,11 +113,11 @@ stateChanges = new Subject<void>();
 
 set value(tel: MyTel | null) {
   ...
-  stateChanges.next();
+  this.stateChanges.next();
 }
 
-ngOnDestory() {
-  stateChanges.destroy();
+ngOnDestroy() {
+  this.stateChanges.complete();
 }
 ```
 

From 86f025368c5fac5ac03a312f2000ae89463eed0a Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Wed, 4 Oct 2017 10:24:30 -0700
Subject: [PATCH 6/8] minor text fixes

---
 src/lib/form-field/form-field.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/lib/form-field/form-field.md b/src/lib/form-field/form-field.md
index 9ea6530cd577..7872e9c8ba0b 100644
--- a/src/lib/form-field/form-field.md
+++ b/src/lib/form-field/form-field.md
@@ -14,11 +14,11 @@ The following Angular Material components are designed to work inside a `<mat-fo
 <!-- example(form-field-overview) -->
 
 ### Floating placeholder
-The floating placeholder is an indicative text label displayed on top of the form field control when
+The floating placeholder is a text label displayed on top of the form field control when
 the control does not contain any text. By default, when text is present the floating placeholder
 floats above the form field control.
 
-The placeholder text can be specified using the `placeholder` property on the form field control, or
+Placeholder text can be specified using the `placeholder` property on the form field control, or
 by adding a `<mat-placeholder>` element inside the form field. Only one of these options should be
 used, specifying both will raise an error.
 
@@ -65,7 +65,7 @@ form field. Errors are hidden initially and will be displayed on invalid form fi
 has interacted with the element or the parent form has been submitted. Since the errors occupy the
 same space as the hints, the hints are hidden when the errors are shown.
 
-If an form field can have more than one error state, it is up to the consumer to toggle which
+If a form field can have more than one error state, it is up to the consumer to toggle which
 messages should be displayed. This can be done with CSS, `ngIf` or `ngSwitch`. Multiple error
 messages can be shown at the same time if desired, but the `<mat-form-field>` only reserves enough
 space to display one error message at a time. Ensuring that enough space is available to display
@@ -74,8 +74,8 @@ multiple errors is up to the user.
 <!-- example(form-field-error) -->
 
 ### Prefix & suffix
-HTML can be included before and after the input tag, as a prefix or suffix. It will be underlined
-as per the Material specification.
+Custom content can be included before and after the input tag, as a prefix or suffix. It will be
+included within the visual container that wraps the form control as per the Material specification.
 
 Adding the `matPrefix` directive to an element inside the `<mat-form-field>` will designate it as
 the prefix. Similarly, adding `matSuffix` will designate it as the suffix.
@@ -90,7 +90,7 @@ information on this see the guide on
 
 ### Theming
 `<mat-form-field>` has a `color` property which can be set to `primary`, `accent`, or `warn`. This
-will set the color ofr the form field underline and floating placeholder based on the theme colors
+will set the color of the form field underline and floating placeholder based on the theme colors
 of your app.
 
 `<mat-form-field>` inherits its `font-size` from its parent element. This can be overridden to an

From 8d10b0f94d6dc0302b09bda6130df1b49d0ae480 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Wed, 4 Oct 2017 13:24:07 -0700
Subject: [PATCH 7/8] add full example code to guide

---
 .../creating-a-custom-form-field-control.md   |  11 +-
 src/material-examples/example-module.ts       |  56 +++++++
 .../form-field-custom-control-example.css     |  21 +++
 .../form-field-custom-control-example.html    |   7 +
 .../form-field-custom-control-example.ts      | 137 ++++++++++++++++++
 ...css => form-field-placeholder-example.css} |   0
 6 files changed, 227 insertions(+), 5 deletions(-)
 create mode 100644 src/material-examples/form-field-custom-control/form-field-custom-control-example.css
 create mode 100644 src/material-examples/form-field-custom-control/form-field-custom-control-example.html
 create mode 100644 src/material-examples/form-field-custom-control/form-field-custom-control-example.ts
 rename src/material-examples/form-field-placeholder/{form-field-placehodler-example.css => form-field-placeholder-example.css} (100%)

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
index fc4cf494f21c..80ed0d3b271e 100644
--- a/guides/creating-a-custom-form-field-control.md
+++ b/guides/creating-a-custom-form-field-control.md
@@ -2,16 +2,17 @@ It is possible to create custom form field controls that can be used inside `<ma
 can be useful if you need to create a component that shares a lot of common behavior with a form
 field, but adds some additional logic.
 
+For example in this guide we'll learn how to create a custom input for inputting US telephone
+numbers and hook it up to work with `<mat-form-field>`. Here is what we'll build by the end of this
+guide:
+
+<!-- example(form-field-custom-control) -->
+
 In order to learn how to build custom form field controls, let's start with a simple input component
 that we want to work inside the form field. For example, a phone number input that segments the
 parts of the number into their own inputs. (Note: this is not intended to be a robust component,
 just a starting point for us to learn.)
 
-<!--
-  TODO(mmalerba): Link to Plunker/StackBlitz with complete example code after beta 12.
-  (Beta 11 is missing some of the features used in the example).
--->
-
 ```ts
 class MyTel {
   constructor(public area: string, public exchange: string, public subscriber: string) {}
diff --git a/src/material-examples/example-module.ts b/src/material-examples/example-module.ts
index 9a0fa11c6e4c..73dd42caaaa6 100644
--- a/src/material-examples/example-module.ts
+++ b/src/material-examples/example-module.ts
@@ -41,6 +41,13 @@ import {DialogElementsExampleDialog,DialogElementsExample} from './dialog-elemen
 import {DialogOverviewExampleDialog,DialogOverviewExample} from './dialog-overview/dialog-overview-example';
 import {ExpansionOverviewExample} from './expansion-overview/expansion-overview-example';
 import {ExpansionStepsExample} from './expansion-steps/expansion-steps-example';
+import {MyTelInput,FormFieldCustomControlExample} from './form-field-custom-control/form-field-custom-control-example';
+import {FormFieldErrorExample} from './form-field-error/form-field-error-example';
+import {FormFieldHintExample} from './form-field-hint/form-field-hint-example';
+import {FormFieldOverviewExample} from './form-field-overview/form-field-overview-example';
+import {FormFieldPlaceholderExample} from './form-field-placeholder/form-field-placeholder-example';
+import {FormFieldPrefixSuffixExample} from './form-field-prefix-suffix/form-field-prefix-suffix-example';
+import {FormFieldThemingExample} from './form-field-theming/form-field-theming-example';
 import {GridListDynamicExample} from './grid-list-dynamic/grid-list-dynamic-example';
 import {GridListOverviewExample} from './grid-list-overview/grid-list-overview-example';
 import {IconOverviewExample} from './icon-overview/icon-overview-example';
@@ -260,6 +267,48 @@ export const EXAMPLE_COMPONENTS = {
     additionalFiles: null,
     selectorName: null
   },
+  'form-field-custom-control': {
+    title: 'Form field with custom telephone number input control. ',
+    component: FormFieldCustomControlExample,
+    additionalFiles: ["form-field-custom-control-example.html"],
+    selectorName: 'FormFieldCustomControlExample, MyTelInput'
+  },
+  'form-field-error': {
+    title: 'Form field with error messages ',
+    component: FormFieldErrorExample,
+    additionalFiles: null,
+    selectorName: null
+  },
+  'form-field-hint': {
+    title: 'Form field with hints ',
+    component: FormFieldHintExample,
+    additionalFiles: null,
+    selectorName: null
+  },
+  'form-field-overview': {
+    title: 'Simple form field ',
+    component: FormFieldOverviewExample,
+    additionalFiles: null,
+    selectorName: null
+  },
+  'form-field-placeholder': {
+    title: 'Form field with placeholder ',
+    component: FormFieldPlaceholderExample,
+    additionalFiles: null,
+    selectorName: null
+  },
+  'form-field-prefix-suffix': {
+    title: 'Form field with prefix & suffix ',
+    component: FormFieldPrefixSuffixExample,
+    additionalFiles: null,
+    selectorName: null
+  },
+  'form-field-theming': {
+    title: 'Form field theming ',
+    component: FormFieldThemingExample,
+    additionalFiles: null,
+    selectorName: null
+  },
   'grid-list-dynamic': {
     title: 'Dynamic grid-list',
     component: GridListDynamicExample,
@@ -585,6 +634,13 @@ export const EXAMPLE_LIST = [
   DialogOverviewExampleDialog,DialogOverviewExample,
   ExpansionOverviewExample,
   ExpansionStepsExample,
+  MyTelInput,FormFieldCustomControlExample,
+  FormFieldErrorExample,
+  FormFieldHintExample,
+  FormFieldOverviewExample,
+  FormFieldPlaceholderExample,
+  FormFieldPrefixSuffixExample,
+  FormFieldThemingExample,
   GridListDynamicExample,
   GridListOverviewExample,
   IconOverviewExample,
diff --git a/src/material-examples/form-field-custom-control/form-field-custom-control-example.css b/src/material-examples/form-field-custom-control/form-field-custom-control-example.css
new file mode 100644
index 000000000000..b62ee863b52b
--- /dev/null
+++ b/src/material-examples/form-field-custom-control/form-field-custom-control-example.css
@@ -0,0 +1,21 @@
+div {
+  display: flex;
+}
+
+input {
+  border: none;
+  background: none;
+  padding: 0;
+  outline: none;
+  font: inherit;
+  text-align: center;
+}
+
+span {
+  opacity: 0;
+  transition: opacity 200ms;
+}
+
+:host.floating span {
+  opacity: 1;
+}
diff --git a/src/material-examples/form-field-custom-control/form-field-custom-control-example.html b/src/material-examples/form-field-custom-control/form-field-custom-control-example.html
new file mode 100644
index 000000000000..cfa6188f73b1
--- /dev/null
+++ b/src/material-examples/form-field-custom-control/form-field-custom-control-example.html
@@ -0,0 +1,7 @@
+<div [formGroup]="parts">
+  <input class="area" formControlName="area" size="3" [disabled]="disabled">
+  <span>&ndash;</span>
+  <input class="exchange" formControlName="exchange" size="3" [disabled]="disabled">
+  <span>&ndash;</span>
+  <input class="subscriber" formControlName="subscriber" size="4" [disabled]="disabled">
+</div>
diff --git a/src/material-examples/form-field-custom-control/form-field-custom-control-example.ts b/src/material-examples/form-field-custom-control/form-field-custom-control-example.ts
new file mode 100644
index 000000000000..10a52245175a
--- /dev/null
+++ b/src/material-examples/form-field-custom-control/form-field-custom-control-example.ts
@@ -0,0 +1,137 @@
+import {FocusMonitor} from '@angular/cdk/a11y';
+import {coerceBooleanProperty} from '@angular/cdk/coercion';
+import {Component, ElementRef, HostBinding, Input, OnDestroy, Renderer2} from '@angular/core';
+import {FormBuilder, FormGroup} from '@angular/forms';
+import {MatFormFieldControl} from '@angular/material/form-field';
+import {Subject} from 'rxjs/Subject';
+
+
+/** Data structure for holding telephone number. */
+export class MyTel {
+  constructor(public area: string, public exchange: string, public subscriber: string) {}
+}
+
+
+/** Custom `MatFormFieldControl` for telephone number input. */
+@Component({
+  selector: 'my-tel-input',
+  templateUrl: 'form-field-custom-control-example.html',
+  styleUrls: ['form-field-custom-control-example.css'],
+  providers: [{provide: MatFormFieldControl, useExisting: MyTelInput}],
+})
+export class MyTelInput implements MatFormFieldControl<MyTel>, OnDestroy {
+  static nextId = 0;
+
+  parts: FormGroup;
+
+  stateChanges = new Subject<void>();
+
+  focused = false;
+
+  ngControl = null;
+
+  errorState = false;
+
+  controlType = 'my-tel-input';
+
+  get empty() {
+    let n = this.parts.value;
+    return !n.area && !n.exchange && !n.subscriber;
+  }
+
+  @HostBinding('class.floating')
+  get shouldPlaceholderFloat() {
+    return this.focused || !this.empty;
+  }
+
+  @HostBinding() id = `my-tel-input-${MyTelInput.nextId++}`;
+
+  @HostBinding('attr.aria-describedby') describedBy = '';
+
+  @Input()
+  get placeholder() {
+    return this._placeholder;
+  }
+  set placeholder(plh) {
+    this._placeholder = plh;
+    this.stateChanges.next();
+  }
+  private _placeholder: string;
+
+  @Input()
+  get required() {
+    return this._required;
+  }
+  set required(req) {
+    this._required = coerceBooleanProperty(req);
+    this.stateChanges.next();
+  }
+  private _required = false;
+
+  @Input()
+  get disabled() {
+    return this._disabled;
+  }
+  set disabled(dis) {
+    this._disabled = coerceBooleanProperty(dis);
+    this.stateChanges.next();
+  }
+  private _disabled = false;
+
+  @Input()
+  get value(): MyTel | null {
+    let n = this.parts.value;
+    if (n.area.length == 3 && n.exchange.length == 3 && n.subscriber.length == 4) {
+      return new MyTel(n.area, n.exchange, n.subscriber);
+    }
+    return null;
+  }
+  set value(tel: MyTel | null) {
+    tel = tel || new MyTel('', '', '');
+    this.parts.setValue({area: tel.area, exchange: tel.exchange, subscriber: tel.subscriber});
+    this.stateChanges.next();
+  }
+
+  constructor(fb: FormBuilder, private fm: FocusMonitor, private elRef: ElementRef,
+              renderer: Renderer2) {
+    this.parts =  fb.group({
+      'area': '',
+      'exchange': '',
+      'subscriber': '',
+    });
+
+    fm.monitor(elRef.nativeElement, renderer, true).subscribe((origin) => {
+      this.focused = !!origin;
+      this.stateChanges.next();
+    });
+  }
+
+  ngOnDestroy() {
+    this.stateChanges.complete();
+    this.fm.stopMonitoring(this.elRef.nativeElement);
+  }
+
+  setDescribedByIds(ids: string[]) {
+    this.describedBy = ids.join(' ');
+  }
+
+  onContainerClick(event: MouseEvent) {
+    if ((event.target as Element).tagName.toLowerCase() != 'input') {
+      this.elRef.nativeElement.querySelector('input').focus();
+    }
+  }
+}
+
+
+/** @title Form field with custom telephone number input control. */
+@Component({
+  selector: 'form-field-custom-control-example',
+  template: `
+    <mat-form-field>
+      <my-tel-input placeholder="Phone number" required></my-tel-input>
+      <mat-icon matSuffix>phone</mat-icon>
+      <mat-hint>Include area code</mat-hint>
+    </mat-form-field>
+  `
+})
+export class FormFieldCustomControlExample {}
diff --git a/src/material-examples/form-field-placeholder/form-field-placehodler-example.css b/src/material-examples/form-field-placeholder/form-field-placeholder-example.css
similarity index 100%
rename from src/material-examples/form-field-placeholder/form-field-placehodler-example.css
rename to src/material-examples/form-field-placeholder/form-field-placeholder-example.css

From f9429456dd905643bd7993ef5310a71c5fa01ff2 Mon Sep 17 00:00:00 2001
From: Miles Malerba <mmalerba@google.com>
Date: Wed, 4 Oct 2017 15:44:53 -0700
Subject: [PATCH 8/8] move styles out of template

---
 .../creating-a-custom-form-field-control.md   | 27 +++++++++----------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
index 80ed0d3b271e..7cf5bb6bed45 100644
--- a/guides/creating-a-custom-form-field-control.md
+++ b/guides/creating-a-custom-form-field-control.md
@@ -21,20 +21,6 @@ class MyTel {
 @Component({
   selector: 'my-tel-input',
   template: `
-    <style>
-      div {
-        display: flex;
-      }
-      input {
-        border: none;
-        background: none;
-        padding: 0;
-        outline: none;
-        font: inherit;
-        text-align: center;
-      }
-    </style>
-    
     <div [formGroup]="parts">
       <input class="area" formControlName="area" size="3">
       <span>&ndash;</span>
@@ -43,6 +29,19 @@ class MyTel {
       <input class="subscriber" formControlName="subscriber" size="4">
     </div>
   `,
+  styles: [`
+    div {
+      display: flex;
+    }
+    input {
+      border: none;
+      background: none;
+      padding: 0;
+      outline: none;
+      font: inherit;
+      text-align: center;
+    }
+  `],
 })
 class MyTelInput {
   parts: FormGroup;