`matInput` is a directive that allows native `<input>` and `<textarea>` elements to work with
[`<mat-form-field>`](https://material.angular.io/components/form-field/overview).

<!-- example(input-overview) -->

### `<input>` and `<textarea>` attributes

All of the attributes that can be used with `<input>` and `<textarea>` elements can be used
on elements inside `<mat-form-field>` as well. This includes Angular directives such as `ngModel`
and `formControl`.

The only limitation is that the `type` attribute can only be one of the values supported by
`matNativeControl`.

### Supported `<input>` types

The following [input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) can
be used with `matNativeControl`:
* color
* date
* datetime-local
* email
* month
* number
* password
* search
* tel
* text
* time
* url
* week

### Form field features

There are a number of `<mat-form-field>` features that can be used with any `<input matNativeControl>` or
`<textarea matNativeControl>`. These include error messages, hint text, prefix & suffix, and theming. For
additional information about these features, see the
[form field documentation](https://material.angular.io/components/form-field/overview).

### Placeholder

The placeholder is text shown when the `<mat-form-field>` label is floating but the input is empty.
It is used to give the user an additional hint about what they should type in the input. The
placeholder can be specified by setting the `placeholder` attribute on the `<input>` or `<textarea>`
element. In some cases that `<mat-form-field>` may use the placeholder as the label (see the
[form field label documentation](https://material.angular.io/components/form-field/overview#floating-label)).

### Changing when error messages are shown

The `<mat-form-field>` allows you to
[associate error messages](https://material.angular.io/components/form-field/overview#error-messages)
with your `matNativeControl`. By default, these error messages are shown when the control is invalid and
the user has interacted with (touched) the element or the parent form has been submitted. If
you wish to override this behavior (e.g. to show the error as soon as the invalid control is dirty
or when a parent form group is invalid), you can use the `errorStateMatcher` property of the
`matNativeControl`. The property takes an instance of an `ErrorStateMatcher` object. An `ErrorStateMatcher`
must implement a single method `isErrorState` which takes the `FormControl` for this `matNativeControl` as
well as the parent form and returns a boolean indicating whether errors should be shown. (`true`
indicating that they should be shown, and `false` indicating that they should not.)

<!-- example(input-error-state-matcher) -->

A global error state matcher can be specified by setting the `ErrorStateMatcher` provider. This
applies to all inputs. For convenience, `ShowOnDirtyErrorStateMatcher` is available in order to
globally cause input errors to show when the input is dirty and invalid.

```ts
@NgModule({
  providers: [
    {provide: ErrorStateMatcher, useClass: ShowOnDirtyErrorStateMatcher}
  ]
})
```

### Auto-resizing `<textarea>` elements

`<textarea>` elements can be made to automatically resize by using the
[`cdkTextareaAutosize` directive](https://material.angular.io/cdk/text-field/overview#automatically-resizing-a-textarea)
available in the CDK.

### Responding to changes in the autofill state of an `<input>`

The CDK provides
[utilities](https://material.angular.io/cdk/text-field/overview#monitoring-the-autofill-state-of-an-input)
for detecting when an input becomes autofilled and changing the appearance of the autofilled state.

### Accessibility

The `matNativeControl` directive works with native `<input>` to provide an accessible experience.

#### Aria attributes

If the containing `<mat-form-field>` has a label it will automatically be used as the `aria-label`
for the `<input>`. However, if there's no label specified in the form field, `aria-label`,
`aria-labelledby` or `<label for=...>` should be added.

#### Errors and hints

Any `mat-error` and `mat-hint` are automatically added to the input's `aria-describedby` list, and
`aria-invalid` is automatically updated based on the input's validity state.

When conveying an error, be sure to not rely solely on color. In the message itself, you can use an
icon or text such as "Error:" to indicate the message is an error message.

### Troubleshooting

#### Error: Input type "..." isn't supported by matInput

This error is thrown when you attempt to set an input's `type` property to a value that isn't
supported by the `matInput` directive. If you need to use an unsupported input type with
`<mat-form-field>` consider writing a
[custom form field control](https://material.angular.io/guide/creating-a-custom-form-field-control)
for it.