W3cubDocs

FormControl

Stable Class

What it does

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

It is one of the three fundamental building blocks of Angular forms, along with FormGroup and FormArray.

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

Class Overview

class FormControl extends AbstractControl {
  constructor(formState?: any, validator?: ValidatorFn|ValidatorFn[], asyncValidator?: AsyncValidatorFn|AsyncValidatorFn[])
  
  
  setValue(value: any, {onlySelf, emitEvent, emitModelToViewChange, emitViewToModelChange}?: {?: boolean,?: boolean,?: boolean,?: boolean}) : void
  patchValue(value: any, options?: {?: boolean,?: boolean,?: boolean,?: boolean}) : void
  reset(formState?: any, {onlySelf, emitEvent}?: {onlySelf?: boolean,?: boolean}) : void
  registerOnChange(fn: Function) : void
  registerOnDisabledChange(fn: (isDisabled: boolean) => void) : void
}

Class Description

Constructor

constructor(formState?: any, validator?: ValidatorFn|ValidatorFn[], asyncValidator?: AsyncValidatorFn|AsyncValidatorFn[])

Class Details

setValue(value: any, {onlySelf, emitEvent, emitModelToViewChange, emitViewToModelChange}?: {
    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, {onlySelf, emitEvent}?: {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'

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

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

registerOnChange(fn: Function) : void

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

exported from @angular/forms/index, defined in @angular/forms/src/model.ts

© 2010–2017 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v2.angular.io/docs/ts/latest/api/forms/index/FormControl-class.html