AbstractControl

This is the base class for FormControl, FormGroup, and FormArray.

It provides some of the shared behavior that all controls and groups of controls have, like running validators, calculating status, and resetting state. It also defines the properties that are shared between all sub-classes, like value, valid, and dirty. It shouldn't be instantiated directly.

Interface

clearAsyncValidators#

clearAsyncValidators(): 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.

clearValidators#

clearValidators(): void

Empties out the sync validator list.

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

dirty#

get dirty(): boolean

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

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

disable#

disable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): 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.

disabled#

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 True if the control is disabled, false otherwise.

enable#

enable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): 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.

enabled#

get enabled(): boolean

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

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

errors#

errors: ValidationErrors | null

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

get#

get(path: Array<string|number>|string): AbstractControl|null

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

Retrieve a nested control

For example, to get a name control nested within a person sub-group:

  • this.form.get('person.name');

-OR-

  • this.form.get(['person', 'name']);

getError#

getError(errorCode: string, path?: Array<string|number>|string): any

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'

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

hasError#

hasError(errorCode: string, path?: Array<string|number>|string): boolean

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.

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

If the control is not present, false is returned.

invalid#

get invalid(): boolean

A control is invalid when its status is INVALID.

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

markAllAsTouched#

markAllAsTouched(): void

Marks the control and all its descendant controls as touched.

markAsDirty#

markAsDirty(opts: {onlySelf?: boolean} = {}): void

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

markAsPending#

markAsPending(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void

Marks the control as pending.

A control is pending while the control performs async validation.

markAsPristine#

markAsPristine(opts: {onlySelf?: boolean} = {}): 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.

markAsTouched#

markAsTouched(opts: {onlySelf?: boolean} = {}): void

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

markAsUntouched#

markAsUntouched(opts: {onlySelf?: boolean} = {}): 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.

parent#

get parent(): FormGroup|FormArray

The parent control.

patchValue#

patchValue(value: any, options?: Object): void

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

pending#

get pending(): boolean

A control is pending when its status is PENDING.

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

pristine#

pristine: boolean

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

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

reset#

reset(value?: any, options?: Object): void

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

root#

get root(): AbstractControl

Retrieves the top-level ancestor of this control.

setAsyncValidators#

setAsyncValidators(newValidator: AsyncValidatorFn|AsyncValidatorFn[]|null): void

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

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

setErrors#

setErrors(errors: ValidationErrors|null, opts: {emitEvent?: boolean} = {}): void

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

Calling setErrors also updates the validity of the parent control.

Manually set the errors for a control

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

setParent#

setParent(parent: FormGroup|FormArray): void

setValidators#

setValidators(newValidator: ValidatorFn|ValidatorFn[]|null): void

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

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

setValue#

setValue(value: any, options?: Object): void

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

status#

status: string

The validation status of the control. There are four possible validation status values:

  • VALID: This control has passed all validation checks.
  • INVALID: This control has failed at least one validation check.
  • PENDING: This control is in the midst of conducting a validation check.
  • DISABLED: This control is exempt from validation checks.

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

statusChanges#

statusChanges: Observable<any>

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

touched#

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.

untouched#

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.

updateOn#

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'

updateValueAndValidity#

updateValueAndValidity(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void

Recalculates the value and validation status of the control.

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

valid#

get valid(): boolean

A control is valid when its status is VALID.

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

value#

value: any

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#

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.