• Overview
@angular/forms/signals

FieldState

interface
experimentalsince v21.0

A writable view of a FieldTree's state.

API

    
      interface FieldState<TValue, TKey extends string | number = string | number> extends ReadonlyFieldState<TValue, TKey> {  readonly fieldTree: FieldTree<unknown, TKey, "writable">;  readonly value: WritableSignal<TValue>;  readonly controlValue: WritableSignal<TValue>;  markAsDirty(): void;  markAsTouched(options?: MarkAsTouchedOptions | undefined): void;  reset(value?: TValue | undefined): void;  readonly override disabled: Signal<boolean>;  readonly override max?: Signal<number | undefined> | undefined;  readonly override maxLength?: Signal<number | undefined> | undefined;  readonly override min?: Signal<number | undefined> | undefined;  readonly override minLength?: Signal<number | undefined> | undefined;  readonly override name: Signal<string>;  readonly override pattern: Signal<readonly RegExp[]>;  readonly override readonly: Signal<boolean>;  readonly override required: Signal<boolean>;  readonly override touched: Signal<boolean>;  readonly override dirty: Signal<boolean>;  readonly override hidden: Signal<boolean>;  readonly override disabledReasons: Signal<readonly DisabledReason[]>;  readonly override errors: Signal<WithFieldTree[]>;  readonly override errorSummary: Signal<WithFieldTree[]>;  readonly override valid: Signal<boolean>;  readonly override invalid: Signal<boolean>;  readonly override pending: Signal<boolean>;  readonly override submitting: Signal<boolean>;  readonly override keyInParent: Signal<TKey>;  readonly override formFieldBindings: Signal<readonly FormFieldBinding[]>;  override metadata<M>(key: MetadataKey<M, any, any>): M | undefined;  override hasMetadata(key: MetadataKey<any, any, any>): boolean;  override focusBoundControl(options?: FocusOptions | undefined): void;}

fieldTree

FieldTree<unknown, TKey, "writable">

The FieldTree associated with this field state.

value

WritableSignal<TValue>

A writable signal containing the value for this field.

Updating this signal will update the data model that the field is bound to.

While updates from the UI control are eventually reflected here, they may be delayed if debounced.

controlValue

WritableSignal<TValue>

A signal containing the value of the control to which this field is bound.

This differs from value in that it's not subject to debouncing, and thus is used to buffer debounced updates from the control to the field. This will also not take into account the controlValue of children.

markAsDirty

void

Sets the dirty status of the field to true.

@returnsvoid

markAsTouched

void

Sets the touched status of the field and its descendants to true.

@paramoptionsMarkAsTouchedOptions | undefined

Options for marking the field as touched.

@returnsvoid

reset

void

Resets the touched and dirty state of the field and its descendants.

Note this does not change the data model, which can be reset directly if desired.

@paramvalueTValue | undefined

Optional value to set to the form. If not passed, the value will not be changed.

@returnsvoid

disabled

Signal<boolean>

A signal indicating whether the field is currently disabled.

max

Signal<number | undefined> | undefined

A signal indicating the field's maximum value, if applicable.

Applies to <input> with a numeric or date type attribute and custom controls.

maxLength

Signal<number | undefined> | undefined

A signal indicating the field's maximum string length, if applicable.

Applies to <input>, <textarea>, and custom controls.

min

Signal<number | undefined> | undefined

A signal indicating the field's minimum value, if applicable.

Applies to <input> with a numeric or date type attribute and custom controls.

minLength

Signal<number | undefined> | undefined

A signal indicating the field's minimum string length, if applicable.

Applies to <input>, <textarea>, and custom controls.

name

Signal<string>

A signal of a unique name for the field, by default based on the name of its parent field.

pattern

Signal<readonly RegExp[]>

A signal indicating the patterns the field must match.

readonly

Signal<boolean>

A signal indicating whether the field is currently readonly.

required

Signal<boolean>

A signal indicating whether the field is required.

touched

Signal<boolean>

A signal indicating whether the field has been touched by the user.

dirty

Signal<boolean>

A signal indicating whether field value has been changed by user.

hidden

Signal<boolean>

A signal indicating whether a field is hidden.

When a field is hidden it is ignored when determining the valid, touched, and dirty states.

Note: This doesn't hide the field in the template, that must be done manually.

@if (!field.hidden()) {  ...}

disabledReasons

Signal<readonly DisabledReason[]>

errorSummary

Signal<WithFieldTree[]>

A signal containing the errors of the field and its descendants.

valid

Signal<boolean>

A signal indicating whether the field's value is currently valid.

Note: valid() is not the same as !invalid().

  • valid() is true when there are no validation errors and no pending validators.
  • invalid() is true when there are validation errors, regardless of pending validators.

Ex: consider the situation where a field has 3 validators, 2 of which have no errors and 1 of which is still pending. In this case valid() is false because of the pending validator. However invalid() is also false because there are no errors.

invalid

Signal<boolean>

A signal indicating whether the field's value is currently invalid.

Note: invalid() is not the same as !valid().

  • invalid() is true when there are validation errors, regardless of pending validators.
  • valid() is true when there are no validation errors and no pending validators.

Ex: consider the situation where a field has 3 validators, 2 of which have no errors and 1 of which is still pending. In this case invalid() is false because there are no errors. However valid() is also false because of the pending validator.

pending

Signal<boolean>

Whether there are any validators still pending for this field.

submitting

Signal<boolean>

A signal indicating whether the field is currently in the process of being submitted.

keyInParent

Signal<TKey>

The property key in the parent field under which this field is stored. If the parent field is array-valued, for example, this is the index of this field in that array.

formFieldBindings

Signal<readonly FormFieldBinding[]>

The FormField directives that bind this field to a UI control.

metadata

M | undefined

Reads a metadata value from the field.

@paramkeyMetadataKey<M, any, any>

The metadata key to read.

@returnsM | undefined

hasMetadata

boolean

Checks whether a metadata value exists on the field.

@paramkeyMetadataKey<any, any, any>

The metadata key to check.

@returnsboolean

focusBoundControl

void

Focuses the first UI control in the DOM that is bound to this field state. If no UI control is bound, does nothing.

@paramoptionsFocusOptions | undefined

Optional focus options to pass to the native focus() method.

@returnsvoid
Jump to details