{ "id": "api/forms/FormControl", "title": "FormControl", "contents": "\n\n
\n
\n
\n \n API > @angular/forms\n
\n \n
\n \n
\n

FormControllink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

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

\n\n

See more...

\n
\n \n \n \n
\n\nclass FormControl extends AbstractControl {\n constructor(formState: any = null, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])\n setValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void\n patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void\n reset(formState: any = null, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n registerOnChange(fn: Function): void\n registerOnDisabledChange(fn: (isDisabled: boolean) => void): void\n\n // inherited from forms/AbstractControl\n constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])\n value: any\n validator: ValidatorFn | null\n asyncValidator: AsyncValidatorFn | null\n parent: FormGroup | FormArray | null\n status: string\n valid: boolean\n invalid: boolean\n pending: boolean\n disabled: boolean\n enabled: boolean\n errors: ValidationErrors | null\n pristine: boolean\n dirty: boolean\n touched: boolean\n untouched: boolean\n valueChanges: Observable<any>\n statusChanges: Observable<any>\n updateOn: FormHooks\n root: AbstractControl\n setValidators(newValidator: ValidatorFn | ValidatorFn[]): void\n setAsyncValidators(newValidator: AsyncValidatorFn | AsyncValidatorFn[]): void\n clearValidators(): void\n clearAsyncValidators(): void\n markAsTouched(opts: { onlySelf?: boolean; } = {}): void\n markAllAsTouched(): void\n markAsUntouched(opts: { onlySelf?: boolean; } = {}): void\n markAsDirty(opts: { onlySelf?: boolean; } = {}): void\n markAsPristine(opts: { onlySelf?: boolean; } = {}): void\n markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n setParent(parent: FormGroup | FormArray): void\n abstract setValue(value: any, options?: Object): void\n abstract patchValue(value: any, options?: Object): void\n abstract reset(value?: any, options?: Object): void\n updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void\n get(path: string | (string | number)[]): AbstractControl | null\n getError(errorCode: string, path?: string | (string | number)[]): any\n hasError(errorCode: string, path?: string | (string | number)[]): boolean\n}\n\n\n \n \n\n
\n\n\n \n
\n

See alsolink

\n \n
\n\n\n \n \n
\n

Descriptionlink

\n

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

\n\n

Further information available in the Usage Notes...

\n
\n\n \n\n\n\n\n\n\n

Constructorlink

\n\n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n

Creates a new FormControl instance.

\n\n
\n
\n \n\n constructor(formState: any = null, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n formState\n any\n

Initializes the control with an initial value,\nor an object that defines the initial value and disabled state.

\n

Optional. Default is null.

\n\n
\n \n validatorOrOpts\n ValidatorFn | AbstractControlOptions | ValidatorFn[]\n

A synchronous validator function, or an array of\nsuch functions, or an AbstractControlOptions object that contains validation functions\nand a validation trigger.

\n

Optional. Default is undefined.

\n\n
\n \n asyncValidator\n AsyncValidatorFn | AsyncValidatorFn[]\n

A single async validator or array of async validator functions

\n

Optional. Default is undefined.

\n\n
\n\n \n\n\n \n\n \n
\n
\n\n\n\n\n\n\n\n\n
\n

Methodslink

\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n setValue()\n \n link

\n \n
\n
\n

Sets a new value for the form control.

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

The new value for the control.

\n\n
\n \n options\n object\n

Configuration options that determine how the control propagates changes\nand emits events when the value changes.\nThe configuration options are passed to the updateValueAndValidity method.

\n
    \n
  • onlySelf: When true, each change only affects this control, and not its parent. Default is\nfalse.
  • \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges\nobservables emit events with the latest status and value when the control value is updated.\nWhen false, no events are emitted.
  • \n
  • emitModelToViewChange: When true or not supplied (the default), each change triggers an\nonChange event to\nupdate the view.
  • \n
  • emitViewToModelChange: When true or not supplied (the default), each change triggers an\nngModelChange\nevent to update the model.\n
  • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n\n \n \n
\n
\n

\n patchValue()\n \n link

\n \n
\n
\n

Patches the value of a control.

\n\n

See also:

\n
    \n \n
  • setValue for options

    \n
  • \n
\n \n
\n
\n \n\n patchValue(value: any, options: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; } = {}): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n value\n any\n \n \n
\n \n options\n object\n

Optional. Default is {}.

\n \n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n

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

\n\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n reset()\n \n link

\n \n
\n
\n

Resets the form control, marking it pristine and untouched, and setting\nthe value to null.

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

Resets the control with an initial value,\nor an object that defines the initial value and disabled state.

\n

Optional. Default is null.

\n\n
\n \n options\n object\n

Configuration options that determine how the control propagates changes\nand emits events after the value changes.

\n
    \n
  • onlySelf: When true, each change only affects this control, and not its parent. Default is\nfalse.
  • \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges\nobservables emit events with the latest status and value when the control is reset.\nWhen false, no events are emitted.\n
  • \n
\n

Optional. Default is {}.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n registerOnChange()\n \n link

\n \n
\n
\n

Register a listener for change events.

\n\n
\n
\n \n\n registerOnChange(fn: Function): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n fn\n Function\n

The method that is called when the value changes

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n registerOnDisabledChange()\n \n link

\n \n
\n
\n

Register a listener for disabled events.

\n\n
\n
\n \n\n registerOnDisabledChange(fn: (isDisabled: boolean) => void): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n fn\n (isDisabled: boolean) => void\n

The method that is called when the disabled status changes.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n
\n\n\n\n \n
\n

Usage noteslink

\n

Initializing Form Controlslink

\n

Instantiate a FormControl, with an initial value.

\n\nconst control = new FormControl('some value');\nconsole.log(control.value); // 'some value'\n\n

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

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

The following example initializes the control with a sync validator.

\n\nconst control = new FormControl('', Validators.required);\nconsole.log(control.value); // ''\nconsole.log(control.status); // 'INVALID'\n\n

The following example initializes the control using an options object.

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

Configure the control to update on a blur eventlink

\n

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

\n\nconst control = new FormControl('', { updateOn: 'blur' });\n\n

Configure the control to update on a submit eventlink

\n

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

\n\nconst control = new FormControl('', { updateOn: 'submit' });\n\n

Reset the control back to an initial valuelink

\n

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

\n\nconst control = new FormControl('Nancy');\n\nconsole.log(control.value); // 'Nancy'\n\ncontrol.reset('Drew');\n\nconsole.log(control.value); // 'Drew'\n\n

Reset the control back to an initial value and disabledlink

\n\nconst control = new FormControl('Nancy');\n\nconsole.log(control.value); // 'Nancy'\nconsole.log(control.status); // 'VALID'\n\ncontrol.reset({ value: 'Drew', disabled: true });\n\nconsole.log(control.value); // 'Drew'\nconsole.log(control.status); // 'DISABLED'\n\n\n
\n\n\n\n
\n
\n\n\n" }