Overview
<mat-form-field> is a component used to wrap several Angular Material components and apply common text field styles such as the underline, floating label, and hint messages.
Basic Usage
<mat-form-field>
<mat-label>Enter your name</mat-label>
<input matInput>
</mat-form-field>
API Reference
Selector: mat-form-field
Exported as: matFormField
appearance
'fill' | 'outline'
default:"'fill'"
The form field appearance style.
color
ThemePalette
default:"'primary'"
Theme color of the form field. This API is supported in M2 themes only.
floatLabel
'always' | 'auto'
default:"'auto'"
Whether the label should always float or float as the user types.
Whether the required marker should be hidden.
subscriptSizing
'fixed' | 'dynamic'
default:"'fixed'"
Whether the form field should reserve space for one line of hint/error text (fixed) or have the spacing grow from 0px as needed (dynamic).
Supported Controls
The following Angular Material components can be used within a <mat-form-field>:
<input matInput><textarea matInput><select matNativeControl><mat-select><mat-chip-grid>
Use <mat-label> to provide a label for the form control:
<mat-form-field>
<mat-label>Email</mat-label>
<input matInput type="email">
</mat-form-field>
<mat-form-field>
<mat-label>Enter your password</mat-label>
<input matInput type="password">
<mat-hint>At least 8 characters</mat-hint>
</mat-form-field>
Error Messages
Display error messages using <mat-error>:
<mat-form-field>
<mat-label>Email</mat-label>
<input matInput [formControl]="emailControl">
<mat-error *ngIf="emailControl.hasError('required')">
Email is required
</mat-error>
<mat-error *ngIf="emailControl.hasError('email')">
Please enter a valid email
</mat-error>
</mat-form-field>
Prefix and Suffix
Add content before or after the form control:
<mat-form-field>
<mat-label>Phone</mat-label>
<mat-icon matPrefix>phone</mat-icon>
<input matInput>
</mat-form-field>
<mat-form-field>
<mat-label>Amount</mat-label>
<input matInput type="number">
<span matSuffix>.00</span>
</mat-form-field>
Appearance Variants
<mat-form-field appearance="fill">
<mat-label>Fill appearance</mat-label>
<input matInput>
</mat-form-field>
<mat-form-field appearance="outline">
<mat-label>Outline appearance</mat-label>
<input matInput>
</mat-form-field>
Accessibility
- The form field automatically manages ARIA attributes for the form control
- Labels are properly associated with their controls
- Error messages are announced to screen readers
- Hint text is associated with the control via
aria-describedby
- Required fields are indicated with
aria-required
- Invalid fields are marked with
aria-invalid
Advanced Usage
Float Label Behavior
Control when the label floats:
<!-- Label always floats -->
<mat-form-field floatLabel="always">
<mat-label>Always floating</mat-label>
<input matInput>
</mat-form-field>
<!-- Label floats only when focused or has value -->
<mat-form-field floatLabel="auto">
<mat-label>Auto floating</mat-label>
<input matInput>
</mat-form-field>
Subscript Sizing
Control the space reserved for hints and errors:
<!-- Fixed: Always reserves space for one line -->
<mat-form-field subscriptSizing="fixed">
<mat-label>Fixed subscript</mat-label>
<input matInput>
<mat-hint>Hint text</mat-hint>
</mat-form-field>
<!-- Dynamic: Space grows as needed -->
<mat-form-field subscriptSizing="dynamic">
<mat-label>Dynamic subscript</mat-label>
<input matInput>
<mat-hint>Hint text</mat-hint>
</mat-form-field>
Global Default Options
import { MAT_FORM_FIELD_DEFAULT_OPTIONS } from '@angular/material/form-field';
@NgModule({
providers: [
{
provide: MAT_FORM_FIELD_DEFAULT_OPTIONS,
useValue: {
appearance: 'outline',
floatLabel: 'always',
subscriptSizing: 'dynamic'
}
}
]
})
export class AppModule {}