Overview for input
matInput
is a directive that allows native <input>
and <textarea>
elements to work with
<mat-form-field>
.
<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 can
be used with matNativeControl
:
- color
- date
- datetime-local
- 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.
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).
Changing when error messages are shown
The <mat-form-field>
allows you to
associate 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.)
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.
@NgModule({
providers: [
{provide: ErrorStateMatcher, useClass: ShowOnDirtyErrorStateMatcher}
]
})
Auto-resizing <textarea>
elements
<textarea>
elements can be made to automatically resize by using the
cdkTextareaAutosize
directive
available in the CDK.
Responding to changes in the autofill state of an <input>
The CDK provides utilities 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
for it.