Interface AbstractControl<T>

interface AbstractControl<T = any> {
    controlId?: string;
    errors: null | ValidationErrors;
    events: Observable<ControlEvent<any>>;
    fullControlPath?: string;
    readonly?: boolean;
    rxapFormDefinition?: FormDefinition<any, any, any>;
    stateChanges?: Subject<any>;
    statusChanges: Observable<FormControlStatus>;
    value: T;
    valueChanges: Observable<any>;
    get asyncValidator(): null | AsyncValidatorFn;
    set asyncValidator(asyncValidatorFn: null | AsyncValidatorFn): void;
    get dirty(): boolean;
    get disabled(): boolean;
    get enabled(): boolean;
    get invalid(): boolean;
    get parent(): null | FormGroup<any> | FormArray<any>;
    get pending(): boolean;
    get pristine(): boolean;
    set pristine(value: boolean): void;
    get root(): AbstractControl;
    get status(): FormControlStatus;
    set status(value: FormControlStatus): void;
    get touched(): boolean;
    set touched(value: boolean): void;
    get untouched(): boolean;
    get updateOn(): FormHooks;
    get valid(): boolean;
    get validator(): null | ValidatorFn;
    set validator(validatorFn: null | ValidatorFn): void;
    addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void;
    addValidators(validators: ValidatorFn | ValidatorFn[]): void;
    clearAsyncValidators(): void;
    clearValidators(): void;
    disable(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    enable(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    get<P extends string | readonly (string | number)[]>(
        path: P,
    ): null | AbstractControl<ɵGetProperty<any, P>, ɵGetProperty<any, P>>;
    get<P extends string | (string | number)[]>(
        path: P,
    ): null | AbstractControl<ɵGetProperty<any, P>, ɵGetProperty<any, P>>;
    getError(errorCode: string, path?: string | (string | number)[]): any;
    getRawValue(): any;
    hasAsyncValidator(validator: AsyncValidatorFn): boolean;
    hasError(errorCode: string, path?: string | (string | number)[]): boolean;
    hasValidator(validator: ValidatorFn): boolean;
    markAllAsTouched(opts?: { emitEvent?: boolean }): void;
    markAsDirty(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    markAsPending(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    markAsPristine(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    markAsTouched(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    markAsUntouched(opts?: { emitEvent?: boolean; onlySelf?: boolean }): void;
    patchValue(value: any, options?: Object): void;
    removeAsyncValidators(
        validators: AsyncValidatorFn | AsyncValidatorFn[],
    ): void;
    removeValidators(validators: ValidatorFn | ValidatorFn[]): void;
    reset(value?: any, options?: Object): void;
    setAsyncValidators(
        validators: null | AsyncValidatorFn | AsyncValidatorFn[],
    ): void;
    setErrors(
        errors: null | ValidationErrors,
        opts?: { emitEvent?: boolean },
    ): void;
    setParent(parent: null | FormGroup<any> | FormArray<any>): void;
    setValidators(validators: null | ValidatorFn | ValidatorFn[]): void;
    setValue(value: any, options?: Object): void;
    updateValueAndValidity(
        opts?: { emitEvent?: boolean; onlySelf?: boolean },
    ): void;
}

Type Parameters

  • T = any

Hierarchy

  • AbstractControl
    • AbstractControl

Implemented by

Properties

controlId?: string
errors: null | ValidationErrors

An object containing any errors generated by failing validation, or null if there are no errors.

events: Observable<ControlEvent<any>>

A multicasting observable that emits an event every time the state of the control changes. It emits for value, status, pristine or touched changes.

Note: On value change, the emit happens right after a value of this control is updated. The value of a parent control (for example if this FormControl is a part of a FormGroup) is updated later, so accessing a value of a parent control (using the value property) from the callback of this event might result in getting a value that has not been updated yet. Subscribe to the events of the parent control instead. For other event types, the events are emitted after the parent control has been updated.

fullControlPath?: string
readonly?: boolean
rxapFormDefinition?: FormDefinition<any, any, any>
stateChanges?: Subject<any>
statusChanges: Observable<FormControlStatus>

A multicasting observable that emits an event every time the validation status of the control recalculates.

value: T

The current value of the control.

  • For a FormControl, the current value.
  • For an enabled FormGroup, the values of enabled controls as an object with a key-value pair for each member of the group.
  • For a disabled FormGroup, the values of all controls as an object with a key-value pair for each member of the group.
  • For a FormArray, the values of enabled controls as an array.
valueChanges: Observable<any>

A multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically. It also emits an event each time you call enable() or disable() without passing along {emitEvent: false} as a function argument.

Note: the emit happens right after a value of this control is updated. The value of a parent control (for example if this FormControl is a part of a FormGroup) is updated later, so accessing a value of a parent control (using the value property) from the callback of this event might result in getting a value that has not been updated yet. Subscribe to the valueChanges event of the parent control instead.

Accessors

  • get asyncValidator(): null | AsyncValidatorFn

    Returns the function that is used to determine the validity of this control asynchronously. If multiple validators have been added, this will be a single composed function. See Validators.compose() for additional information.

    Returns null | AsyncValidatorFn

  • set asyncValidator(asyncValidatorFn: null | AsyncValidatorFn): void

    Parameters

    • asyncValidatorFn: null | AsyncValidatorFn

    Returns void

  • get dirty(): boolean

    A control is dirty if the user has changed the value in the UI.

    Returns boolean

    True if the user has changed the value of this control in the UI; compare pristine. Programmatic changes to a control's value do not mark it dirty.

  • get disabled(): boolean

    A control is disabled when its status is DISABLED.

    Disabled controls are exempt from validation checks and are not included in the aggregate value of their ancestor controls.

    Returns boolean

    True if the control is disabled, false otherwise.

  • get enabled(): boolean

    A control is enabled as long as its status is not DISABLED.

    Returns boolean

    True if the control has any status other than 'DISABLED', false if the status is 'DISABLED'.

  • get invalid(): boolean

    A control is invalid when its status is INVALID.

    Returns boolean

    True if this control has failed one or more of its validation checks, false otherwise.

  • get parent(): null | FormGroup<any> | FormArray<any>

    The parent control.

    Returns null | FormGroup<any> | FormArray<any>

  • get pending(): boolean

    A control is pending when its status is PENDING.

    Returns boolean

    True if this control is in the process of conducting a validation check, false otherwise.

  • get pristine(): boolean

    A control is pristine if the user has not yet changed the value in the UI.

    Returns boolean

    True if the user has not yet changed the value in the UI; compare dirty. Programmatic changes to a control's value do not mark it dirty.

  • set pristine(value: boolean): void

    Parameters

    • value: boolean

    Returns void

  • get root(): AbstractControl

    Retrieves the top-level ancestor of this control.

    Returns AbstractControl

  • get status(): FormControlStatus

    The validation status of the control.

    Returns FormControlStatus

    FormControlStatus

    These status values are mutually exclusive, so a control cannot be both valid AND invalid or invalid AND disabled.

  • set status(value: FormControlStatus): void

    Parameters

    • value: FormControlStatus

    Returns void

  • get touched(): boolean

    True if the control is marked as touched.

    A control is marked touched once the user has triggered a blur event on it.

    Returns boolean

  • set touched(value: boolean): void

    Parameters

    • value: boolean

    Returns void

  • get untouched(): boolean

    True if the control has not been marked as touched

    A control is untouched if the user has not yet triggered a blur event on it.

    Returns boolean

  • get updateOn(): FormHooks

    Reports the update strategy of the AbstractControl (meaning the event on which the control updates itself). Possible values: 'change' | 'blur' | 'submit' Default value: 'change'

    Returns FormHooks

  • get valid(): boolean

    A control is valid when its status is VALID.

    Returns boolean

    True if the control has passed all of its validation tests, false otherwise.

  • get validator(): null | ValidatorFn

    Returns the function that is used to determine the validity of this control synchronously. If multiple validators have been added, this will be a single composed function. See Validators.compose() for additional information.

    Returns null | ValidatorFn

  • set validator(validatorFn: null | ValidatorFn): void

    Parameters

    • validatorFn: null | ValidatorFn

    Returns void

Methods

  • Add an asynchronous validator or validators to this control, without affecting other validators.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    Adding a validator that already exists will have no effect.

    Parameters

    • validators: AsyncValidatorFn | AsyncValidatorFn[]

      The new asynchronous validator function or functions to add to this control.

    Returns void

  • Add a synchronous validator or validators to this control, without affecting other validators.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    Adding a validator that already exists will have no effect. If duplicate validator functions are present in the validators array, only the first instance would be added to a form control.

    Parameters

    • validators: ValidatorFn | ValidatorFn[]

      The new validator function or functions to add to this control.

    Returns void

  • Empties out the async validator list.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    Returns void

  • Empties out the synchronous validator list.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    Returns void

  • Disables the control. This means the control is exempt from validation checks and excluded from the aggregate value of any parent. Its status is DISABLED.

    If the control has children, all children are also disabled.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options that determine how the control propagates changes and emits events after the control is disabled.

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the statusChanges, valueChanges and events observables emit events with the latest status and value when the control is disabled. When false, no events are emitted.

    Returns void

  • Enables the control. This means the control is included in validation checks and the aggregate value of its parent. Its status recalculates based on its value and its validators.

    By default, if the control has children, all children are enabled.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configure options that control how the control propagates changes and emits events when marked as untouched

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the statusChanges, valueChanges and events observables emit events with the latest status and value when the control is enabled. When false, no events are emitted.

    Returns void

  • Retrieves a child control given the control's name or path.

    This signature for get supports strings and const arrays (.get(['foo', 'bar'] as const)).

    Type Parameters

    • P extends string | readonly (string | number)[]

    Parameters

    • path: P

    Returns null | AbstractControl<ɵGetProperty<any, P>, ɵGetProperty<any, P>>

  • Retrieves a child control given the control's name or path.

    This signature for get supports non-const (mutable) arrays. Inferred type information will not be as robust, so prefer to pass a readonly array if possible.

    Type Parameters

    • P extends string | (string | number)[]

    Parameters

    • path: P

    Returns null | AbstractControl<ɵGetProperty<any, P>, ɵGetProperty<any, P>>

  • Parameters

    • errorCode: string

      The code of the error to check

    • Optionalpath: string | (string | number)[]

      A list of control names that designates how to move from the current control to the control that should be queried for errors.

    Returns any

    error data for that particular error. If the control or error is not present, null is returned.

    Reports error data for the control with the given path.

    For example, for the following FormGroup:

    form = new FormGroup({
    address: new FormGroup({ street: new FormControl() })
    });

    The path to the 'street' control from the root form would be 'address' -> 'street'.

    It can be provided to this method in one of two formats:

    1. An array of string control names, e.g. ['address', 'street']
    2. A period-delimited list of control names in one string, e.g. 'address.street'
  • The raw value of this control. For most control implementations, the raw value will include disabled children.

    Returns any

  • Check whether an asynchronous validator function is present on this control. The provided validator must be a reference to the exact same function that was provided.

    Parameters

    • validator: AsyncValidatorFn

      The asynchronous validator to check for presence. Compared by function reference.

    Returns boolean

    Whether the provided asynchronous validator was found on this control.

  • Parameters

    • errorCode: string

      The code of the error to check

    • Optionalpath: string | (string | number)[]

      A list of control names that designates how to move from the current control to the control that should be queried for errors.

    Returns boolean

    whether the given error is present in the control at the given path.

    If the control is not present, false is returned.

    Reports whether the control with the given path has the error specified.

    For example, for the following FormGroup:

    form = new FormGroup({
    address: new FormGroup({ street: new FormControl() })
    });

    The path to the 'street' control from the root form would be 'address' -> 'street'.

    It can be provided to this method in one of two formats:

    1. An array of string control names, e.g. ['address', 'street']
    2. A period-delimited list of control names in one string, e.g. 'address.street'

    If no path is given, this method checks for the error on the current control.

  • Check whether a synchronous validator function is present on this control. The provided validator must be a reference to the exact same function that was provided.

    Parameters

    • validator: ValidatorFn

      The validator to check for presence. Compared by function reference.

    Returns boolean

    Whether the provided validator was found on this control.

    // Reference to the RequiredValidator
    const ctrl = new FormControl<number | null>(0, Validators.required);
    expect(ctrl.hasValidator(Validators.required)).toEqual(true)

    // Reference to anonymous function inside MinValidator
    const minValidator = Validators.min(3);
    const ctrl = new FormControl<number | null>(0, minValidator);
    expect(ctrl.hasValidator(minValidator)).toEqual(true)
    expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)
  • Marks the control and all its descendant controls as touched.

    Parameters

    • Optionalopts: { emitEvent?: boolean }

      Configuration options that determine how the control propagates changes and emits events after marking is applied.

      • emitEvent: When true or not supplied (the default), the events observable emits a TouchedChangeEvent with the touched property being true. When false, no events are emitted.

    Returns void

    ()

  • Marks the control as dirty. A control becomes dirty when the control's value is changed through the UI; compare markAsTouched.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options that determine how the control propagates changes and emits events after marking is applied.

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the events observable emits a PristineChangeEvent with the pristine property being false. When false, no events are emitted.

    Returns void

  • Marks the control as pending.

    A control is pending while the control performs async validation.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options that determine how the control propagates changes and emits events after marking is applied.

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the statusChanges observable emits an event with the latest status the control is marked pending and the events observable emits a StatusChangeEvent with the status property being PENDING When false, no events are emitted.

    Returns void

  • Marks the control as pristine.

    If the control has any children, marks all children as pristine, and recalculates the pristine status of all parent controls.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options that determine how the control emits events after marking is applied.

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the events observable emits a PristineChangeEvent with the pristine property being true. When false, no events are emitted.

    Returns void

  • Marks the control as touched. A control is touched by focus and blur events that do not change the value.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options that determine how the control propagates changes and emits events after marking is applied.

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the events observable emits a TouchedChangeEvent with the touched property being true. When false, no events are emitted.

    Returns void

  • Marks the control as untouched.

    If the control has any children, also marks all children as untouched and recalculates the touched status of all parent controls.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options that determine how the control propagates changes and emits events after the marking is applied.

      • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the events observable emits a TouchedChangeEvent with the touched property being false. When false, no events are emitted.

    Returns void

  • Patches the value of the control. Abstract method (implemented in sub-classes).

    Parameters

    • value: any
    • Optionaloptions: Object

    Returns void

  • Remove an asynchronous validator from this control, without affecting other validators. Validators are compared by function reference; you must pass a reference to the exact same validator function as the one that was originally set. If a provided validator is not found, it is ignored.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    Parameters

    • validators: AsyncValidatorFn | AsyncValidatorFn[]

      The asynchronous validator or validators to remove.

    Returns void

  • Remove a synchronous validator from this control, without affecting other validators. Validators are compared by function reference; you must pass a reference to the exact same validator function as the one that was originally set. If a provided validator is not found, it is ignored.

    Parameters

    • validators: ValidatorFn | ValidatorFn[]

      The validator or validators to remove.

    Returns void

    // Reference to the RequiredValidator
    const ctrl = new FormControl<string | null>('', Validators.required);
    ctrl.removeValidators(Validators.required);

    // Reference to anonymous function inside MinValidator
    const minValidator = Validators.min(3);
    const ctrl = new FormControl<string | null>('', minValidator);
    expect(ctrl.hasValidator(minValidator)).toEqual(true)
    expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)

    ctrl.removeValidators(minValidator);

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

  • Resets the control. Abstract method (implemented in sub-classes).

    Parameters

    • Optionalvalue: any
    • Optionaloptions: Object

    Returns void

  • Sets the asynchronous validators that are active on this control. Calling this overwrites any existing asynchronous validators.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    If you want to add a new validator without affecting existing ones, consider using addAsyncValidators() method instead.

    Parameters

    • validators: null | AsyncValidatorFn | AsyncValidatorFn[]

    Returns void

  • Sets errors on a form control when running validations manually, rather than automatically.

    Calling setErrors also updates the validity of the parent control.

    Parameters

    • errors: null | ValidationErrors
    • Optionalopts: { emitEvent?: boolean }

      Configuration options that determine how the control propagates changes and emits events after the control errors are set.

      • emitEvent: When true or not supplied (the default), the statusChanges observable emits an event after the errors are set.

    Returns void

    const login = new FormControl('someLogin');
    login.setErrors({
    notUnique: true
    });

    expect(login.valid).toEqual(false);
    expect(login.errors).toEqual({ notUnique: true });

    login.setValue('someOtherLogin');

    expect(login.valid).toEqual(true);
  • Sets the parent of the control

    Parameters

    • parent: null | FormGroup<any> | FormArray<any>

      The new parent.

    Returns void

  • Sets the synchronous validators that are active on this control. Calling this overwrites any existing synchronous validators.

    When you add or remove a validator at run time, you must call updateValueAndValidity() for the new validation to take effect.

    If you want to add a new validator without affecting existing ones, consider using addValidators() method instead.

    Parameters

    • validators: null | ValidatorFn | ValidatorFn[]

    Returns void

  • Sets the value of the control. Abstract method (implemented in sub-classes).

    Parameters

    • value: any
    • Optionaloptions: Object

    Returns void

  • Recalculates the value and validation status of the control.

    By default, it also updates the value and validity of its ancestors.

    Parameters

    • Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }

      Configuration options determine how the control propagates changes and emits events after updates and validity checks are applied.

      • onlySelf: When true, only update this control. When false or not supplied, update all direct ancestors. Default is false.
      • emitEvent: When true or not supplied (the default), the statusChanges, valueChanges and events observables emit events with the latest status and value when the control is updated. When false, no events are emitted.

    Returns void