FormControl
class
Tracks the value and validation status of an individual form control.
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 registerOnChange(fn: Function): void registerOnDisabledChange(fn: (isDisabled: boolean) => void): void // inherited from forms/AbstractControl constructor(validator: ValidatorFn, asyncValidator: AsyncValidatorFn) 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[]): 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; 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
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.
Constructor
Creates a new | |||||||||
|
formState | any | Initializes the control with an initial value, or an object that defines the initial value and disabled state. Optional. Default is |
validatorOrOpts | ValidatorFn | AbstractControlOptions | ValidatorFn[] | A synchronous validator function, or an array of such functions, or an Optional. Default is |
asyncValidator | AsyncValidatorFn | AsyncValidatorFn[] | A single async validator or array of async validator functions Optional. Default is |
Methods
setValue() | ||||||
---|---|---|---|---|---|---|
Sets a new value for the form control. | ||||||
|
value | any | The new value for the control. |
options | object | Configuration options that determine how the control propagates changes and emits events when the value changes. The configuration options are passed to the updateValueAndValidity method.
Optional. Default is |
Returns
void
patchValue() | ||||||
---|---|---|---|---|---|---|
Patches the value of a control. See also:
| ||||||
|
value | any | |
options | object | Optional. Default is |
Returns
void
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() | ||||||
---|---|---|---|---|---|---|
Resets the form control, marking it | ||||||
|
formState | any | Resets the control with an initial value, or an object that defines the initial value and disabled state. Optional. Default is |
options | object | Configuration options that determine how the control propagates changes and emits events after the value changes.
Optional. Default is |
Returns
void
registerOnChange() | |||
---|---|---|---|
Register a listener for change events. | |||
|
fn | Function | The method that is called when the value changes |
Returns
void
registerOnDisabledChange() | |||
---|---|---|---|
Register a listener for disabled events. | |||
|
fn | (isDisabled: boolean) => void | The method that is called when the disabled status changes. |
Returns
void
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 sync 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'
© 2010–2019 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v7.angular.io/api/forms/FormControl