Help Angular by taking a 1 minute survey!Go to surveyHome

AbstractControl

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

See more...

abstract class AbstractControl { constructor(validator: ValidatorFn, asyncValidator: AsyncValidatorFn) value: any validator: ValidatorFn | null asyncValidator: AsyncValidatorFn | null parent: FormGroup | FormArray status: string valid: boolean invalid: boolean pending: boolean disabled: boolean enabled: boolean errors: ValidationErrors | null pristine: boolean dirty: boolean touched: boolean untouched: boolean valueChanges: Observable<any> statusChanges: Observable<any> updateOn: FormHooks root: AbstractControl setValidators(newValidator: ValidatorFn | ValidatorFn[]): void setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void clearValidators(): void clearAsyncValidators(): void markAsTouched(opts: { onlySelf?: boolean; } = {}): void markAsUntouched(opts: { onlySelf?: boolean; } = {}): void markAsDirty(opts: { onlySelf?: boolean; } = {}): void markAsPristine(opts: { onlySelf?: boolean; } = {}): void markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void setParent(parent: FormGroup | FormArray): void abstract setValue(value: any, options?: Object): void abstract patchValue(value: any, options?: Object): void abstract reset(value?: any, options?: Object): void updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void get(path: string | (string | number)[]): AbstractControl | null getError(errorCode: string, path?: string | (string | number)[]): any hasError(errorCode: string, path?: string | (string | number)[]): boolean }
      
      abstract class AbstractControl {
  constructor(validator: ValidatorFn, asyncValidator: AsyncValidatorFn)
  value: any
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  parent: FormGroup | FormArray
  status: string
  valid: boolean
  invalid: boolean
  pending: boolean
  disabled: boolean
  enabled: boolean
  errors: ValidationErrors | null
  pristine: boolean
  dirty: boolean
  touched: boolean
  untouched: boolean
  valueChanges: Observable<any>
  statusChanges: Observable<any>
  updateOn: FormHooks
  root: AbstractControl
  setValidators(newValidator: ValidatorFn | ValidatorFn[]): void
  setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: { onlySelf?: boolean; } = {}): void
  markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
  markAsDirty(opts: { onlySelf?: boolean; } = {}): void
  markAsPristine(opts: { onlySelf?: boolean; } = {}): void
  markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setParent(parent: FormGroup | FormArray): void
  abstract setValue(value: any, options?: Object): void
  abstract patchValue(value: any, options?: Object): void
  abstract reset(value?: any, options?: Object): void
  updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
  get(path: string | (string | number)[]): AbstractControl | null
  getError(errorCode: string, path?: string | (string | number)[]): any
  hasError(errorCode: string, path?: string | (string | number)[]): boolean
}
    

See also

Description

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.

Constructor

Initialize the AbstractControl instance.

constructor(validator: ValidatorFn, asyncValidator: AsyncValidatorFn)
      
      constructor(validator: ValidatorFn, asyncValidator: AsyncValidatorFn)
    
Parameters
validator ValidatorFn

The function that determines the synchronous validity of this control.

asyncValidator AsyncValidatorFn

The function that determines the asynchronous validity of this control.

Properties

Property Description
value: any Read-only.

The current value of the control.

  • For a FormControl, the current value.
  • For a FormGroup, the values of enabled 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.
validator: ValidatorFn | null Declared in constructor.

The function that determines the synchronous validity of this control.

asyncValidator: AsyncValidatorFn | null Declared in constructor.

The function that determines the asynchronous validity of this control.

parent: FormGroup | FormArray Read-only.

The parent control.

status: string Read-only.

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.

valid: boolean Read-only.

A control is valid when its status is VALID.

See also:

invalid: boolean Read-only.

A control is invalid when its status is INVALID.

See also:

pending: boolean Read-only.

A control is pending when its status is PENDING.

See also:

disabled: boolean Read-only.

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.

See also:

enabled: boolean Read-only.

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

See also:

errors: ValidationErrors | null Read-only.

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

pristine: boolean Read-only.

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

dirty: boolean Read-only.

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

touched: boolean Read-only.

True if the control is marked as touched.

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

untouched: boolean Read-only.

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.

valueChanges: Observable<any> Read-only.

A multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically.

statusChanges: Observable<any> Read-only.

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

See also:

updateOn: FormHooks Read-only.

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

root: AbstractControl Read-only.

Retrieves the top-level ancestor of this control.

Methods

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

setValidators(newValidator: ValidatorFn | ValidatorFn[]): void
      
      setValidators(newValidator: ValidatorFn | ValidatorFn[]): void
    
Parameters
newValidator ValidatorFn | ValidatorFn[]
Returns

void

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

setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void
      
      setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void
    
Parameters
newValidator AsyncValidatorFn | AsyncValidatorFn[]
Returns

void

Empties out the sync validator list.

clearValidators(): void
      
      clearValidators(): void
    
Parameters

There are no parameters.

Returns

void

Empties out the async validator list.

clearAsyncValidators(): void
      
      clearAsyncValidators(): void
    
Parameters

There are no parameters.

Returns

void

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

See also:

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

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

  • onlySelf: When true, mark only this control. When false or not supplied, marks all direct ancestors. Default is false.

Optional. Default is {}.

Returns

void

Marks the control as untouched.

See also:

markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
      
      markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
    
Parameters
opts object

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.

Optional. Default is {}.

Returns

void

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

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

See also:

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

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.

Optional. Default is {}.

Returns

void

Marks the control as pristine.

See also:

markAsPristine(opts: { onlySelf?: boolean; } = {}): void
      
      markAsPristine(opts: { onlySelf?: boolean; } = {}): void
    
Parameters
opts object

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

Optional. Default is {}.

Returns

void

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

Marks the control as pending.

See also:

markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
      
      markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
Parameters
opts object

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. When false, no events are emitted.

Optional. Default is {}.

Returns

void

A control is pending while the control performs async validation.

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.

See also:

disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
      
      disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
Parameters
opts object

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), both the statusChanges and valueChanges observables emit events with the latest status and value when the control is disabled. When false, no events are emitted.

Optional. Default is {}.

Returns

void

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

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.

See also:

enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
      
      enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
Parameters
opts object

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), both the statusChanges and valueChanges observables emit events with the latest status and value when the control is enabled. When false, no events are emitted.

Optional. Default is {}.

Returns

void

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

setParent(parent: FormGroup | FormArray): void
      
      setParent(parent: FormGroup | FormArray): void
    
Parameters
parent FormGroup | FormArray

Sets the parent of the control

Returns

void

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

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

Optional. Default is undefined.

Returns

void

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

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

Optional. Default is undefined.

Returns

void

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

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

Optional. Default is undefined.

options Object

Optional. Default is undefined.

Returns

void

Recalculates the value and validation status of the control.

updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
      
      updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
    
Parameters
opts object

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), both the statusChanges and valueChanges observables emit events with the latest status and value when the control is updated. When false, no events are emitted.

Optional. Default is {}.

Returns

void

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

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

setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
      
      setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
    
Parameters
errors ValidationErrors
opts object

Optional. Default is {}.

Returns

void

Calling setErrors also updates the validity of the parent control.

Usage Notes

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

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

get(path: string | (string | number)[]): AbstractControl | null
      
      get(path: string | (string | number)[]): AbstractControl | null
    
Parameters
path string | (string | number)[]

A dot-delimited string or array of string/number values that define the path to the control.

Returns

AbstractControl | null

Usage Notes

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

Reports error data for the control with the given path.

getError(errorCode: string, path?: string | (string | number)[]): any
      
      getError(errorCode: string, path?: string | (string | number)[]): any
    
Parameters
errorCode string

The code of the error to check

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

Optional. Default is undefined.

Returns

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

Usage Notes

For example, for the following FormGroup:

form = new FormGroup({ address: new FormGroup({ street: new FormControl() }) });
      
      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'

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

hasError(errorCode: string, path?: string | (string | number)[]): boolean
      
      hasError(errorCode: string, path?: string | (string | number)[]): boolean
    
Parameters
errorCode string

The code of the error to check

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

Optional. Default is undefined.

Returns

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

If the control is not present, false is returned.

Usage Notes

For example, for the following FormGroup:

form = new FormGroup({ address: new FormGroup({ street: new FormControl() }) });
      
      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.