FormControl
Tracks the value and validation status of an individual form control.
class FormControl<TValue = any> extends AbstractControl<TValue> {
new (): FormControl<any>
defaultValue: TValue
setValue(value: TValue, options?: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; }): void
patchValue(value: TValue, options?: { onlySelf?: boolean; emitEvent?: boolean; emitModelToViewChange?: boolean; emitViewToModelChange?: boolean; }): void
reset(formState?: TValue | FormControlState<TValue>, options?: { onlySelf?: boolean; emitEvent?: boolean; }): void
getRawValue(): TValue
registerOnChange(fn: Function): void
registerOnDisabledChange(fn: (isDisabled: boolean) => void): void
// inherited from forms/AbstractControl
constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])
value: TValue
validator: ValidatorFn | null
asyncValidator: AsyncValidatorFn | null
parent: FormGroup | FormArray | null
status: FormControlStatus
valid: boolean
invalid: boolean
pending: boolean
disabled: boolean
enabled: boolean
errors: ValidationErrors | null
pristine: boolean
dirty: boolean
touched: boolean
untouched: boolean
valueChanges: Observable<TValue>
statusChanges: Observable<FormControlStatus>
updateOn: FormHooks
root: AbstractControl
setValidators(validators: ValidatorFn | ValidatorFn[]): void
setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
addValidators(validators: ValidatorFn | ValidatorFn[]): void
addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
removeValidators(validators: ValidatorFn | ValidatorFn[]): void
removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
hasValidator(validator: ValidatorFn): boolean
hasAsyncValidator(validator: AsyncValidatorFn): boolean
clearValidators(): void
clearAsyncValidators(): void
markAsTouched(opts: { onlySelf?: boolean; } = {}): void
markAllAsTouched(): 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<any> | FormArray<any>): void
abstract setValue(value: TRawValue, options?: Object): void
abstract patchValue(value: TValue, options?: Object): void
abstract reset(value?: TValue, options?: Object): void
getRawValue(): any
updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
get<P extends string | ((string | number)[])>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null
get<P extends string | (readonly (string | number)[])>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null
get<P extends string | Array<string | number>>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | 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 four fundamental building blocks of Angular forms, along with
FormGroup
, FormArray
and FormRecord
. It extends the AbstractControl
class that
implements most of the base functionality for accessing the value, validation status,
user interactions and events.
FormControl
takes a single generic argument, which describes the type of its value. This
argument always implicitly includes null
because the control can be reset. To change this
behavior, set nonNullable
or see the usage notes below.
See usage examples below.
Further information is available in the Usage Notes...
Constructor
construct signature | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Construct a FormControl with no initial value or validators. |
||||||||||||||||||||||||||||||
|
value
|
T | FormControlState<T> |
|
opts
|
FormControlOptions & { nonNullable: true; } |
Returns
FormControl<T>
Overload #2
new <T = any>(value: T | FormControlState<T>, opts: FormControlOptions & { initialValueIsDefault: true; }): FormControl<T>
Deprecated Use nonNullable
instead.
Parameters
value
|
T | FormControlState<T> |
|
opts
|
FormControlOptions & { initialValueIsDefault: true; } |
Returns
FormControl<T>
Overload #3
new <T = any>(value: T | FormControlState<T>, opts: FormControlOptions, asyncValidator: AsyncValidatorFn | AsyncValidatorFn[]): FormControl<T | null>
Deprecated When passing an options
argument, the asyncValidator
argument has no effect.
Parameters
value
|
T | FormControlState<T> |
|
opts
|
FormControlOptions |
|
asyncValidator
|
AsyncValidatorFn | AsyncValidatorFn[] |
Returns
FormControl<T | null>
Overload #4
new <T = any>(value: T | FormControlState<T>, validatorOrOpts?: ValidatorFn | FormControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormControl<T | null>
Parameters
value
|
T | FormControlState<T> |
|
validatorOrOpts
|
ValidatorFn | FormControlOptions | ValidatorFn[] |
Optional. Default is |
asyncValidator
|
AsyncValidatorFn | AsyncValidatorFn[] |
Optional. Default is |
Returns
FormControl<T | null>
Properties
Property | Description |
---|---|
defaultValue: TValue
|
Read-Only
The default value of this FormControl, used whenever the control is reset without an explicit
value. See |
Methods
setValue() | ||||||
---|---|---|---|---|---|---|
Sets a new value for the form control. |
||||||
Parameters
Returns
|
patchValue() |
---|
Patches the value of a control. See also:
|
This function is functionally the same as |
reset() | ||||||
---|---|---|---|---|---|---|
Resets the form control, marking it |
||||||
Parameters
Returns
|
||||||
|
getRawValue() |
---|
For a simple FormControl, the raw value is equivalent to the value. |
ParametersThere are no parameters. Returns
|
registerOnChange() |
---|
Register a listener for change events. |
registerOnDisabledChange() |
---|
Register a listener for disabled events. |
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 synchronous 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
});
The single type argument
FormControl
accepts a generic argument, which describes the type of its value.
In most cases, this argument will be inferred.
If you are initializing the control to null
, or you otherwise wish to provide a
wider type, you may specify the argument explicitly:
let fc = new FormControl<string|null>(null);
fc.setValue('foo');
You might notice that null
is always added to the type of the control.
This is because the control will become null
if you call reset
. You can change
this behavior by setting {nonNullable: true}
.
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 a specific 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 to its initial value
If you wish to always reset the control to its initial value (instead of null),
you can pass the nonNullable
option:
const control = new FormControl('Nancy', {nonNullable: true});
console.log(control.value); // 'Nancy'
control.reset();
console.log(control.value); // 'Nancy'
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'