FormControl

Tracks the value and validation status of an individual form control.

See more...

class FormControl extends AbstractControl {
  constructor(formState: any = null, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])
  setValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void
  patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void
  reset(formState: any = null, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  _updateValue()
  _anyControls(condition: Function): boolean
  _allControlsDisabled(): boolean
  registerOnChange(fn: Function): void
  registerOnDisabledChange(fn: (isDisabled: boolean) => void): void
  _forEachChild(cb: Function): void
  _syncPendingControls(): boolean

  // inherited from forms/AbstractControl
  constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])
  value: any
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  parent: FormGroup | FormArray | null
  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(validators: ValidatorFn | ValidatorFn[]): void
  setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  addValidators(validators: ValidatorFn | ValidatorFn[]): void
  addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  removeValidators(validators: ValidatorFn | ValidatorFn[]): void
  removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  hasValidator(validator: ValidatorFn): boolean
  hasAsyncValidator(validator: AsyncValidatorFn): boolean
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: { onlySelf?: boolean; } = {}): void
  markAllAsTouched(): 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

• AbstractControl

• Reactive Forms Guide

• Usage Notes

Description

This is one of the three fundamental building blocks of Angular forms, along with FormGroup and FormArray. It extends the AbstractControl class that implements most of the base functionality for accessing the value, validation status, user interactions and events. See usage examples below.

Further information is available in the Usage Notes...

Constructor

Creates a new FormControl instance. This class is "final" and should not be extended. See the public API notes.

constructor(formState: any = null, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]) Parameters formState any Initializes the control with an initial value, or an object that defines the initial value and disabled state. Optional. Default is null. validatorOrOpts ValidatorFn | AbstractControlOptions | ValidatorFn[] A synchronous validator function, or an array of such functions, or an AbstractControlOptions object that contains validation functions and a validation trigger. Optional. Default is undefined. asyncValidator AsyncValidatorFn | AsyncValidatorFn[] A single async validator or array of async validator functions Optional. Default is undefined.

Methods

setValue()
setValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void Parameters value any options object Optional. Default is {}. Returns void

patchValue()
patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void Parameters value any options object Optional. Default is {}. Returns void

reset()
reset(formState: any = null, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void Parameters formState any Optional. Default is null. options object Optional. Default is {}. Returns void

_updateValue()
_updateValue() Parameters There are no parameters.

_anyControls()
_anyControls(condition: Function): boolean Parameters condition Function Returns boolean

_allControlsDisabled()
_allControlsDisabled(): boolean Parameters There are no parameters. Returns boolean

registerOnChange()
Register a listener for change events.
registerOnChange(fn: Function): void Parameters fn Function The method that is called when the value changes Returns void

registerOnDisabledChange()
Register a listener for disabled events.
registerOnDisabledChange(fn: (isDisabled: boolean) => void): void Parameters fn (isDisabled: boolean) => void The method that is called when the disabled status changes. Returns void

_forEachChild()
_forEachChild(cb: Function): void Parameters cb Function Returns void

_syncPendingControls()
_syncPendingControls(): boolean Parameters There are no parameters. Returns boolean

Usage notes

Initializing Form Controls

Instantiate a FormControl, with an initial value.

const control = new FormControl('some value');
console.log(control.value);     // 'some value'

The following example initializes the control with a form state object. The value and disabled keys are required in this case.

const control = new FormControl({ value: 'n/a', disabled: true });
console.log(control.value);     // 'n/a'
console.log(control.status);    // 'DISABLED'

The following example initializes the control with a synchronous validator.

const control = new FormControl('', Validators.required);
console.log(control.value);      // ''
console.log(control.status);     // 'INVALID'

The following example initializes the control using an options object.

const control = new FormControl('', {
   validators: Validators.required,
   asyncValidators: myAsyncValidator
});

Configure the control to update on a blur event

Set the updateOn option to 'blur' to update on the blur event.

const control = new FormControl('', { updateOn: 'blur' });

Configure the control to update on a submit event

Set the updateOn option to 'submit' to update on a submit event.

const control = new FormControl('', { updateOn: 'submit' });

Reset the control back to an initial value

You reset to a specific form state by passing through a standalone value or a form state object that contains both a value and a disabled state (these are the only two properties that cannot be calculated).

const control = new FormControl('Nancy');

console.log(control.value); // 'Nancy'

control.reset('Drew');

console.log(control.value); // 'Drew'

Reset the control back to an initial value and disabled

const control = new FormControl('Nancy');

console.log(control.value); // 'Nancy'
console.log(control.status); // 'VALID'

control.reset({ value: 'Drew', disabled: true });

console.log(control.value); // 'Drew'
console.log(control.status); // 'DISABLED'