Form Field • Angular Material

API reference for Angular Material form-field

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

Components

`MatFormField`

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.dev/components/form-field/styling. For information on applying color variants in M3, see https://material.angular.dev/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 (): `ElementRef`
Gets an ElementRef for the element that a overlay attached to the form field should be positioned relative to.
Returns
`ElementRef`

Classes

`MatFormFieldControl`

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

Properties

Name	Description
`autofilled: boolean \| Signal<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.
`describedByIds: string[]`	Gets the list of element IDs that currently describe this control.
`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 \| Signal<boolean>`	Whether the control is disabled.
`empty: boolean \| Signal<boolean>`	Whether the control is empty.
`errorState: boolean \| Signal<boolean>`	Whether the control is in an error state.
`focused: boolean \| Signal<boolean>`	Whether the control is focused.
`id: string`	The element ID for this control.
`ngControl: NgControl \| AbstractControlDirective \| null`	Form control if the directive only supports Reactive or Template-driven forms. Can be skipped if your directive already sets `ngField`.
`ngField: Field<T> \| null`	Control if the directive supports signal forms.
`required: boolean \| Signal<boolean>`	Whether the control is required.
`shouldLabelFloat: boolean \| Signal<boolean>`	Whether the `MatFormField` label should try to float.
`stateChanges: Observable<void> \| null`	Stream that emits whenever the state of the control changes such that the parent `MatFormField` needs to run change detection. Not necessary if the control is signal-based.
`userAriaDescribedBy: string \| Signal<string>`	Value of `aria-describedby` that should be merged with the described-by ids which are set by the form-field.
`value: any`	Value of the form control. Left in for backwards compatibility.

Methods

onContainerClick (event: `MouseEvent`): `void`
Handles a click on the control's container.
Parameters
event `MouseEvent`

setDescribedByIds (ids: `string[]`): `void`
Sets the list of element IDs that currently describe this control.
Parameters
ids `string[]`

Interfaces

`MatFormFieldDefaultOptions`

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.dev/components/form-field/styling. For information on applying color variants in M3, see https://material.angular.dev/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 aliases

`FloatLabelType`

Type for the available floatLabel values.

type FloatLabelType = 'always' | 'auto';

`MatFormFieldAppearance`

Possible appearance styles for the form field.

type MatFormFieldAppearance = 'fill' | 'outline';

`SubscriptSizing`

Behaviors for how the subscript height is set.

type SubscriptSizing = 'fixed' | 'dynamic';

Constants

`MAT_FORM_FIELD`

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;

`MAT_FORM_FIELD_DEFAULT_OPTIONS`

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;

API reference for Angular Material form-field-testing

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

Classes

`MatFormFieldHarness` extends ComponentHarness

Properties

Name	Description
`static hostSelector: '.mat-mdc-form-field'`

Methods

async getAppearance (): `Promise<'fill' \| 'outline'>`
Gets the appearance of the form-field.
Returns
`Promise<'fill' \| 'outline'>`

async getControl (): `Promise<FormFieldControlHarness \| null>`
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 (type: `ComponentHarnessConstructor<X>`): `Promise<X \| null>`
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 (type: `HarnessPredicate<X>`): `Promise<X \| null>`
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 (filter: `ErrorHarnessFilters = {}`): `Promise<MatErrorHarness[]>`
Gets all of the error harnesses in the form field.
Parameters
filter `ErrorHarnessFilters = {}`
Returns
`Promise<MatErrorHarness[]>`

async getLabel (): `Promise<string \| null>`
Gets the label of the form-field.
Returns
`Promise<string \| null>`

async getPrefixText (): `Promise<string>`
Gets the text inside the prefix element.
Returns
`Promise<string>`

async getSuffixText (): `Promise<string>`
Gets the text inside the suffix element.
Returns
`Promise<string>`

async getTextErrors (): `Promise<string[]>`
Gets error messages which are currently displayed in the form-field.
Returns
`Promise<string[]>`

async getTextHints (): `Promise<string[]>`
Gets hint messages which are currently displayed in the form-field.
Returns
`Promise<string[]>`

async getThemeColor (): `Promise<'primary' \| 'accent' \| 'warn'>`
Gets the theme color of the form-field.
Returns
`Promise<'primary' \| 'accent' \| 'warn'>`

async hasErrors (): `Promise<boolean>`
Whether the form-field has errors.
Returns
`Promise<boolean>`

async hasLabel (): `Promise<boolean>`
Whether the form-field has a label.
Returns
`Promise<boolean>`

async host (): `Promise<TestElement>`
Gets a `Promise` for the `TestElement` representing the host element of the component.
Returns
`Promise<TestElement>`

async isAutofilled (): `Promise<boolean>`
Whether the form-field is currently autofilled.
Returns
`Promise<boolean>`

async isControlDirty (): `Promise<boolean \| null>`
Whether the form control is dirty. Returns "null" if no form control is set up.
Returns
`Promise<boolean \| null>`

async isControlPending (): `Promise<boolean \| null>`
Whether the form control is pending validation. Returns "null" if no form control is set up.
Returns
`Promise<boolean \| null>`

async isControlTouched (): `Promise<boolean \| null>`
Whether the form control has been touched. Returns "null" if no form control is set up.
Returns
`Promise<boolean \| null>`

async isControlValid (): `Promise<boolean \| null>`
Whether the form control is valid. Returns "null" if no form control is set up.
Returns
`Promise<boolean \| null>`

async isDisabled (): `Promise<boolean>`
Whether the form-field is disabled.
Returns
`Promise<boolean>`

async isLabelFloating (): `Promise<boolean>`
Whether the label is currently floating.
Returns
`Promise<boolean>`

static with (options: `FormFieldHarnessFilters = {}`): `HarnessPredicate<T>`
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.

`MatErrorHarness` extends ComponentHarness

Harness for interacting with a mat-error in tests.

Properties

Name	Description
`static hostSelector: '.mat-mdc-form-field-error'`

Methods

async getText (): `Promise<string>`
Gets a promise for the error's label text.
Returns
`Promise<string>`

async host (): `Promise<TestElement>`
Gets a `Promise` for the `TestElement` representing the host element of the component.
Returns
`Promise<TestElement>`

static with (options: `ErrorHarnessFilters = {}`): `HarnessPredicate<T>`
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.

Interfaces

`FormFieldHarnessFilters`

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.

`ErrorHarnessFilters`

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.

Type aliases

`FormFieldControlHarness`

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

type FormFieldControlHarness = MatInputHarness | MatSelectHarness | MatDatepickerInputHarness | MatDateRangeInputHarness;

Form Field

API reference for Angular Material form-field

Components link

MatFormField link

Properties

Methods

Classes link

MatFormFieldControl link

Properties

Methods

Interfaces link

MatFormFieldDefaultOptions link

Properties

Type aliases link

FloatLabelType link

MatFormFieldAppearance link

SubscriptSizing link

Constants link

MAT_FORM_FIELD link

MAT_FORM_FIELD_DEFAULT_OPTIONS link

API reference for Angular Material form-field-testing

Classes link

MatFormFieldHarness extends ComponentHarness link

Properties

Methods

MatErrorHarness extends ComponentHarness link

Properties

Methods

Interfaces link

FormFieldHarnessFilters link

Properties

ErrorHarnessFilters link

Properties

Type aliases link

FormFieldControlHarness link

Components

`MatFormField`

Classes

`MatFormFieldControl`

Interfaces

`MatFormFieldDefaultOptions`

Type aliases

`FloatLabelType`

`MatFormFieldAppearance`

`SubscriptSizing`

Constants

`MAT_FORM_FIELD`

`MAT_FORM_FIELD_DEFAULT_OPTIONS`

Classes

`MatFormFieldHarness` extends ComponentHarness

`MatErrorHarness` extends ComponentHarness

Interfaces

`FormFieldHarnessFilters`

`ErrorHarnessFilters`

Type aliases

`FormFieldControlHarness`