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, validator?: ValidatorFn|ValidatorFn[]|null, asyncValidator?: AsyncValidatorFn|AsyncValidatorFn[]|null)
  setValue(value: any, options: {...}): void
  patchValue(value: any, options: {...}): void
  reset(formState: any = null, options: {onlySelf?: boolean, emitEvent?: boolean} = {}): void
  registerOnChange(fn: Function): void
  registerOnDisabledChange(fn: (isDisabled: boolean) => void): void
  // inherited from forms/AbstractControl
  validator: ValidatorFn|null
  asyncValidator: AsyncValidatorFn|null
  get value: any
  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>
  setValidators(newValidator: ValidatorFn|ValidatorFn[]|null): 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} = {}): void
  disable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void
  enable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): 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: {onlySelf?: boolean, emitEvent?: boolean} = {}): void
  setErrors(errors: ValidationErrors|null, opts: {emitEvent?: boolean} = {}): 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'

To include a sync validator (or an array of sync validators) with the control, pass it in as the second argument. Async validators are also supported, but have to be passed in separately as the third arg.

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

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 FormControl at this level. It exists for symmetry with FormGroup 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.