API for form-field

API reference for Angular Material form-field

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

The floating label for a mat-form-field.

Selector: mat-label

Single error message to be shown underneath the form-field.

Selector: mat-error [matError]

Properties
Name Description
@Input()

id: string

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.

Prefix to be placed in front of the form field.

Selector: [matPrefix] [matIconPrefix] [matTextPrefix]

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

Selector: [matSuffix] [matIconSuffix] [matTextSuffix]

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 of the form field. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.io/components/form-field/styling.

For information on applying color variants in M3, see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants

@Input()

floatLabel: FloatLabelType

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

@Input()

hideRequiredMarker: boolean

Whether the required marker should be hidden.

@Input()

hintLabel: string

Text for the form field hint.

@Input()

subscriptSizing: SubscriptSizing

Whether the form field should reserve space for one line of hint/error text (default) or to have the spacing grow from 0px as needed based on the size of the hint/error content. Note that when using dynamic sizing, layout shifts will occur when hint/error text changes.

getLabelId: computed(() => (this._hasFloatingLabel() ? this._labelId : null))

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

Methods
getConnectedOverlayOrigin

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

Returns
ElementRef

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.

disableAutomaticLabeling: boolean

Whether to automatically assign the ID of the form field as the for attribute on the <label> inside the form field. Set this to true to prevent the form field from associating the label with non-native elements.

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 | AbstractControlDirective | null

Gets the AbstractControlDirective 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

Default form field appearance style.

color: ThemePalette

Default theme color of the form field. This API is supported in M2 themes only, it has no effect in M3 themes. For color customization in M3, see https://material.angular.io/components/form-field/styling.

For information on applying color variants in M3, see https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants

floatLabel: FloatLabelType

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

hideRequiredMarker: boolean

Whether the required marker should be hidden by default.

subscriptSizing: SubscriptSizing

Whether the form field should reserve space for one line by default.

Type for the available floatLabel values.

type FloatLabelType = 'always' | 'auto';

Possible appearance styles for the form field.

type MatFormFieldAppearance = 'fill' | 'outline';

Behaviors for how the subscript height is set.

type SubscriptSizing = 'fixed' | 'dynamic';

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 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>;

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 configure the default options for all form field within an app.

const MAT_FORM_FIELD_DEFAULT_OPTIONS: InjectionToken<MatFormFieldDefaultOptions>;

API reference for Angular Material form-field-testing

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

Properties
Name Description

static hostSelector: '.mat-mdc-form-field'

Methods
async
getAppearance

Gets the appearance of the form-field.

Returns
Promise<'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
getErrors

Gets all of the error harnesses in the form field.

Parameters

filter

ErrorHarnessFilters = {}

Returns
Promise<MatErrorHarness[]>

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>

static
with

Gets a HarnessPredicate that can be used to search for a form field with specific attributes.

Parameters

options

FormFieldHarnessFilters = {}

Options for filtering which form field instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

Harness for interacting with a mat-error in tests.

Properties
Name Description

static hostSelector: '.mat-mdc-form-field-error'

Methods
async
getText

Gets a promise for the error's label text.

Returns
Promise<string>

async
host

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

Returns
Promise<TestElement>

static
with

Gets a HarnessPredicate that can be used to search for an error with specific attributes.

Parameters

options

ErrorHarnessFilters = {}

Options for filtering which error instances are considered a match.

Returns
HarnessPredicate<T>

a HarnessPredicate configured with the given options.

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.

isValid: boolean

Filters based on whether the form field value is valid.

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

Properties
Name Description

text: string | RegExp

Only find instances whose text matches the given value.

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

type FormFieldControlHarness = MatInputHarness | MatSelectHarness | MatDatepickerInputHarness | MatDateRangeInputHarness;
Azure & Blue theme selected.