FormControl

class

npm Package	@angular/forms
Module	import { FormControl } from '@angular/forms';
Source	forms/src/model.ts

Overview

class FormControl extends AbstractControl {
  constructor(formState: any = null, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null)
  setValue(value: any, options: {...}): void
  patchValue(value: any, options: {...}): void
  reset(formState: any = null, options: {...}): void
  registerOnChange(fn: Function): void
  registerOnDisabledChange(fn: (isDisabled: boolean) => void): void
  // inherited from forms/AbstractControl
  get value: any
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  get parent: FormGroup | FormArray
  get status: string
  get valid: boolean
  get invalid: boolean
  get pending: boolean
  get disabled: boolean
  get enabled: boolean
  get errors: ValidationErrors | null
  get pristine: boolean
  get dirty: boolean
  get touched: boolean
  get untouched: boolean
  get valueChanges: Observable<any>
  get statusChanges: Observable<any>
  get updateOn: FormHooks
  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
  setValue(value: any, options?: Object): void
  patchValue(value: any, options?: Object): void
  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
  get root: AbstractControl
}

How To Use

When instantiating a FormControl, you can pass in an initial value as the first argument. Example:

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

You can also initialize the control with a form state object on instantiation, which includes both the value and whether or not the control is disabled. You can't use the value key without the disabled key; both are required to use this way of initialization.

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

The second FormControl argument can accept one of three things:

• a sync validator function
• an array of sync validator functions
• an options object containing validator and/or async validator functions

Example of a single sync validator function:

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

Example using options object:

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

The options object can also be used to define when the control should update. By default, the value and validity of a control updates whenever the value changes. You can configure it to update on the blur event instead by setting the updateOn option to 'blur'.

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

You can also set updateOn to 'submit', which will delay value and validity updates until the parent form of the control fires a submit event.

See its superclass, AbstractControl, for more properties and methods.

• npm package: @angular/forms

Constructor

Members

setValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void

Set the value of the form control to value.

If onlySelf is true, this change will only affect the validation of this FormControl and not its parent component. This defaults to false.

If emitEvent is true, this change will cause a valueChanges event on the FormControl to be emitted. This defaults to true (as it falls through to updateValueAndValidity).

If emitModelToViewChange is true, the view will be notified about the new value via an onChange event. This is the default behavior if emitModelToViewChange is not specified.

If emitViewToModelChange is true, an ngModelChange event will be fired to update the model. This is the default behavior if emitViewToModelChange is not specified.

patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void

Patches the value of a control.

This function is functionally the same as setValue at this level. It exists for symmetry with patchValue on FormGroups and FormArrays, where it does behave differently.

reset(formState: any = null, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void

Resets the form control. This means by default:

• it is marked as pristine
• it is marked as untouched
• value is set to null

You can also 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).

Ex:

this.control.reset('Nancy');

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

OR

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

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

registerOnChange(fn: Function): void

Register a listener for change events.

registerOnDisabledChange(fn: (isDisabled: boolean) => void): void

Register a listener for disabled events.