AbstractControl

class

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

      
      abstract class AbstractControl {
  constructor(validator: ValidatorFn | null, asyncValidator: AsyncValidatorFn | null)
  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[] | null): void
  setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[] | null): void
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: {...}): void
  markAsUntouched(opts: {...}): void
  markAsDirty(opts: {...}): void
  markAsPristine(opts: {...}): void
  markAsPending(opts: {...}): void
  disable(opts: {...}): void
  enable(opts: {...}): 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: {...}): void
  setErrors(errors: ValidationErrors | null, opts: {...}): void
  get(path: Array<string | number> | string): AbstractControl | null
  getError(errorCode: string, path?: string[]): any
  hasError(errorCode: string, path?: string[]): boolean
}

Subclasses

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 | null, asyncValidator: AsyncValidatorFn | null)

Parameters

validator	The function that determines the synchronous validity of this control.
asyncValidator	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`	The function that determines the synchronous validity of this control. Declared in constructor.
`asyncValidator: AsyncValidatorFn \| null`	The function that determines the asynchronous validity of this control. Declared in constructor.
`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`.
`invalid: boolean`	Read-only. A control is `invalid` when its `status` is `INVALID`.
`pending: boolean`	Read-only. A control is `pending` when its `status` is `PENDING`.
`disabled: boolean`	Read-only. A control is `disabled` when its `status` is `DISABLED`.
`enabled: boolean`	Read-only. A control is `enabled` as long as its `status` is not `DISABLED`.
`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.
`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

setValidators()

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

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

Parameters

newValidator

Type: ValidatorFn | ValidatorFn[] | null.

Returns

void

setAsyncValidators()

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

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

Parameters

newValidator

Type: AsyncValidatorFn | AsyncValidatorFn[] | null.

Returns

void

clearValidators()
Empties out the sync validator list.
clearValidators(): void `clearValidators(): void` Parameters There are no parameters. Returns `void`

clearValidators()

Empties out the sync validator list.

      
      clearValidators(): void

Parameters

There are no parameters.

Returns

void

clearAsyncValidators()
Empties out the async validator list.
clearAsyncValidators(): void `clearAsyncValidators(): void` Parameters There are no parameters. Returns `void`

clearAsyncValidators()

Empties out the async validator list.

      
      clearAsyncValidators(): void

Parameters

There are no parameters.

Returns

void

markAsTouched()

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

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

Parameters

opts	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

markAsUntouched()

Marks the control as untouched.

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

Parameters

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

markAsDirty()

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

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

Parameters

opts	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

markAsPristine()

Marks the control as pristine.

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

Parameters

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

markAsPending()

Marks the control as pending.

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

Parameters

opts

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.

disable()

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.

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

Parameters

opts

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.

enable()

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.

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

Parameters

opts

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

      
      setParent(parent: FormGroup | FormArray): void

Parameters

parent

Sets the parent of the control

Returns

void

setValue()

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

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

Parameters

value

Type: any.

options

Type: Object.

Optional. Default is undefined.

Returns

void

patchValue()

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

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

Parameters

value

Type: any.

options

Type: Object.

Optional. Default is undefined.

Returns

void

reset()

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

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

Parameters

value

Type: any.

Optional. Default is undefined.

options

Type: Object.

Optional. Default is undefined.

Returns

void

updateValueAndValidity()

Recalculates the value and validation status of the control.

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

Parameters

opts

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.

setErrors()

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

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

Parameters

errors

Type: ValidationErrors | null.

opts

Type: { emitEvent?: boolean; }.

Optional. Default is {}.

Returns

void

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

get()

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

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

Parameters

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

Returns

AbstractControl | null

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

Reports error data for a specific error occurring in this control or in another control.

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

Parameters

errorCode

The error code for which to retrieve data

path

The path to a control to check. If not supplied, checks for the error in this control.

Optional. Default is undefined.

Returns

any: The error data if the control with the given path has the given error, otherwise null or undefined.

hasError()

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

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

Parameters

errorCode

The error code for which to retrieve data

path

The path to a control to check. If not supplied, checks for the error in this control.

Optional. Default is undefined.

Returns

boolean: True when the control with the given path has the error, otherwise false.

Subclasseslink

See alsolink

Descriptionlink

Constructorlink

Parameters

Propertieslink

Methodslink

setValidators() link

Parameters

Returns

setAsyncValidators() link

Parameters

Returns

clearValidators() link

Parameters

Returns

clearAsyncValidators() link

Parameters

Returns

markAsTouched() link

Parameters

Returns

markAsUntouched() link

Parameters

Returns

markAsDirty() link

Parameters

Returns

markAsPristine() link

Parameters

Returns

markAsPending() link

Parameters

Returns

disable() link

Parameters

Returns

enable() link

Parameters

Returns

setParent() link

Parameters

Returns

setValue() link

Parameters

Returns

patchValue() link

Parameters

Returns

reset() link

Parameters

Returns

updateValueAndValidity() link

Parameters

Returns

setErrors() link

Parameters

Returns

Manually set the errors for a controllink

get() link

Parameters

Returns

Retrieve a nested controllink

getError() link

Parameters

Returns

hasError() link

Parameters

Returns

Subclasses

See also

Description

Constructor

Properties

Methods

setValidators()

setAsyncValidators()

clearValidators()

clearAsyncValidators()

markAsTouched()

markAsUntouched()

markAsDirty()

markAsPristine()

markAsPending()

disable()

enable()

setParent()

setValue()

patchValue()

reset()

updateValueAndValidity()

setErrors()

Manually set the errors for a control

get()

Retrieve a nested control

getError()

hasError()