Form field

API for form-field

API reference for Angular Material form-field

import {MatFormFieldModule} from '@angular/material/form-field';

Single error message to be shown underneath the form field.

Selector: mat-error

Properties
Name Description
@Input()

id: string

Container for form controls that applies Material Design styling and behavior.

Selector: mat-form-field

Exported as: matFormField
Properties
Name Description
@Input()

appearance: MatFormFieldAppearance

The form-field appearance style.

@Input()

color: ThemePalette

Theme color palette for the component.

@Input()

floatLabel: FloatLabelType

Whether the label should always float, never float or float as the user types.

Note: only the legacy appearance supports the never option. never was originally added as a way to make the floating label emulate the behavior of a standard input placeholder. However the form field now supports both floating labels and placeholders. Therefore in the non-legacy appearances the never option has been disabled in favor of just using the placeholder.

@Input()

hideRequiredMarker: boolean

Whether the required marker should be hidden.

@Input()

hintLabel: string

Text for the form field hint.

defaultColor: ThemePalette | undefined

Default color to fall back to if no value is set.

Deprecated

underlineRef: ElementRef

Methods
getConnectedOverlayOrigin

Gets an ElementRef for the element that a overlay attached to the form-field should be positioned relative to.

Returns
ElementRef

getLabelId

Gets the id of the label element. If no label is present, returns null.

Returns
string | null

updateOutlineGap

Updates the width and position of the gap in the outline. Only relevant for the outline appearance.

Hint text to be shown underneath the form field control.

Selector: mat-hint

Properties
Name Description
@Input()

align: 'start' | 'end'

Whether to align the hint label at the start or end of the line.

@Input()

id: string

Unique ID for the hint. Used for the aria-describedby on the form field control.

The placeholder text for an MatFormField.

Selector: mat-placeholder

Deprecated

Prefix to be placed in front of the form field.

Selector: [matPrefix]

Suffix to be placed at the end of the form field.

Selector: [matSuffix]

The floating label for a mat-form-field.

Selector: mat-label

An interface which allows a control to work inside of a MatFormField.

Properties
Name Description

autofilled: boolean

Whether the input is currently in an autofilled state. If property is not present on the control it is assumed to be false.

controlType: string

An optional name for the control type that can be used to distinguish mat-form-field elements based on their control type. The form field will add a class, mat-form-field-type-{{controlType}} to its root element.

disabled: boolean

Whether the control is disabled.

empty: boolean

Whether the control is empty.

errorState: boolean

Whether the control is in an error state.

focused: boolean

Whether the control is focused.

id: string

The element ID for this control.

ngControl: NgControl | null

Gets the NgControl for this control.

placeholder: string

The placeholder for this control.

required: boolean

Whether the control is required.

shouldLabelFloat: boolean

Whether the MatFormField label should try to float.

stateChanges: Observable<void>

Stream that emits whenever the state of the control changes such that the parent MatFormField needs to run change detection.

userAriaDescribedBy: string

Value of aria-describedby that should be merged with the described-by ids which are set by the form-field.

value: T | null

The value of the control.

Methods
onContainerClick

Handles a click on the control's container.

Parameters

event

MouseEvent

setDescribedByIds

Sets the list of element IDs that currently describe this control.

Parameters

ids

string[]

Represents the default options for the form field that can be configured using the MAT_FORM_FIELD_DEFAULT_OPTIONS injection token.

Properties
Name Description

appearance: MatFormFieldAppearance

floatLabel: FloatLabelType

Whether the label for form-fields should by default float always, never, or auto (only when necessary).

hideRequiredMarker: boolean

Possible appearance styles for the form field.

type MatFormFieldAppearance = 'legacy' | 'standard' | 'fill' | 'outline';

Possible values for the "floatLabel" form-field input.

type FloatLabelType = 'always' | 'never' | 'auto';

Injection token that can be used to reference instances of MatError. It serves as alternative token to the actual MatError class which could cause unnecessary retention of the class and its directive metadata.

const MAT_ERROR: InjectionToken<MatError>;

Injection token that can be used to configure the default options for all form field within an app.

const MAT_FORM_FIELD_DEFAULT_OPTIONS: InjectionToken<MatFormFieldDefaultOptions>;

Injection token that can be used to inject an instances of MatFormField. It serves as alternative token to the actual MatFormField class which would cause unnecessary retention of the MatFormField class and its component metadata.

const MAT_FORM_FIELD: InjectionToken<MatFormField>;

Injection token that can be used to reference instances of MatPrefix. It serves as alternative token to the actual MatPrefix class which could cause unnecessary retention of the class and its directive metadata.

const MAT_PREFIX: InjectionToken<MatPrefix>;

Injection token that can be used to reference instances of MatSuffix. It serves as alternative token to the actual MatSuffix class which could cause unnecessary retention of the class and its directive metadata.

const MAT_SUFFIX: InjectionToken<MatSuffix>;

API reference for Angular Material form-field-testing

import {MatFormFieldHarness} from '@angular/material/form-field/testing';

Harness for interacting with a standard Material form-field's in tests.

Methods
async
getAppearance

Gets the appearance of the form-field.

Returns
Promise<'legacy' | 'standard' | 'fill' | 'outline'>

async
getControl

Gets the harness of the control that is bound to the form-field. Only default controls such as "MatInputHarness" and "MatSelectHarness" are supported.

Returns
Promise<FormFieldControlHarness | null>

async
getControl

Gets the harness of the control that is bound to the form-field. Searches for a control that matches the specified harness type.

Parameters

type

ComponentHarnessConstructor<X>

Returns
Promise<X | null>

async
getControl

Gets the harness of the control that is bound to the form-field. Searches for a control that matches the specified harness predicate.

Parameters

type

HarnessPredicate<X>

Returns
Promise<X | null>

async
getLabel

Gets the label of the form-field.

Returns
Promise<string | null>

async
getPrefixText

Gets the text inside the prefix element.

Returns
Promise<string>

async
getSuffixText

Gets the text inside the suffix element.

Returns
Promise<string>

async
getTextErrors

Gets error messages which are currently displayed in the form-field.

Returns
Promise<string[]>

async
getTextHints

Gets hint messages which are currently displayed in the form-field.

Returns
Promise<string[]>

async
getThemeColor

Gets the theme color of the form-field.

Returns
Promise<'primary' | 'accent' | 'warn'>

async
hasErrors

Whether the form-field has errors.

Returns
Promise<boolean>

async
hasLabel

Whether the form-field has a label.

Returns
Promise<boolean>

async
host

Gets a Promise for the TestElement representing the host element of the component.

Returns
Promise<TestElement>

async
isAutofilled

Whether the form-field is currently autofilled.

Returns
Promise<boolean>

async
isControlDirty

Whether the form control is dirty. Returns "null" if no form control is set up.

Returns
Promise<boolean | null>

async
isControlPending

Whether the form control is pending validation. Returns "null" if no form control is set up.

Returns
Promise<boolean | null>

async
isControlTouched

Whether the form control has been touched. Returns "null" if no form control is set up.

Returns
Promise<boolean | null>

async
isControlValid

Whether the form control is valid. Returns "null" if no form control is set up.

Returns
Promise<boolean | null>

async
isDisabled

Whether the form-field is disabled.

Returns
Promise<boolean>

async
isLabelFloating

Whether the label is currently floating.

Returns
Promise<boolean>

Deprecated
async
getHarnessLoaderForPrefix

Gets a reference to the container element which contains all projected prefixes of the form-field.

Returns
Promise<TestElement | null>

Deprecated
async
getHarnessLoaderForSuffix

Gets a reference to the container element which contains all projected suffixes of the form-field.

Returns
Promise<TestElement | null>

A set of criteria that can be used to filter a list of MatFormFieldHarness instances.

Properties
Name Description

floatingLabelText: string | RegExp

Filters based on the text of the form field's floating label.

hasErrors: boolean

Filters based on whether the form field has error messages.

Possible harnesses of controls which can be bound to a form-field.

type FormFieldControlHarness = MatInputHarness | MatSelectHarness;