• Overview
@angular/forms/signals

ReadonlyFieldState

interface
experimentalsince v21.3

A readonly view of a FieldTree's state.

API

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

fieldTree

ReadonlyFieldTree<unknown, TKey>

The FieldTree associated with this field state.

value

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

Signal<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.

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