ReadonlycontrolReadonlydirty$Readonlydisabled$Readonlyenabled$ReadonlyerrorsReadonlyerrors$ReadonlyeventsA multicasting observable that emits an event every time the state of the control changes. It emits for value, status, pristine or touched changes.
Note: On value change, the emit happens right after a value of this control is updated. The
value of a parent control (for example if this FormControl is a part of a FormGroup) is updated
later, so accessing a value of a parent control (using the value property) from the callback
of this event might result in getting a value that has not been updated yet. Subscribe to the
events of the parent control instead.
For other event types, the events are emitted after the parent control has been updated.
ReadonlystatusThe validation status of the control.
Readonlystatus$ReadonlystatusA multicasting observable that emits an event every time the validation status of the control
recalculates.
Readonlytouch$ReadonlyvalueThe current value of the control.
FormControl, the current value.FormGroup, the values of enabled controls as an object
with a key-value pair for each member of the group.FormGroup, the values of all controls as an object
with a key-value pair for each member of the group.FormArray, the values of enabled controls as an array.Readonlyvalue$ReadonlyvalueA multicasting observable that emits an event every time the value of the control changes, in the UI or programmatically. It also emits an event each time you call enable() or disable() without passing along {emitEvent: false} as a function argument.
Note: the emit happens right after a value of this control is updated. The value of a
parent control (for example if this FormControl is a part of a FormGroup) is updated later, so
accessing a value of a parent control (using the value property) from the callback of this
event might result in getting a value that has not been updated yet. Subscribe to the
valueChanges event of the parent control instead.
Returns the function that is used to determine the validity of this control asynchronously.
If multiple validators have been added, this will be a single composed function.
See Validators.compose() for additional information.
A control is dirty if the user has changed the value
in the UI.
True if the user has changed the value of this control in the UI; compare pristine.
Programmatic changes to a control's value do not mark it dirty.
A control is disabled when its status is DISABLED.
Disabled controls are exempt from validation checks and are not included in the aggregate value of their ancestor controls.
True if the control is disabled, false otherwise.
A control is enabled as long as its status is not DISABLED.
True if the control has any status other than 'DISABLED', false if the status is 'DISABLED'.
A control is invalid when its status is INVALID.
True if this control has failed one or more of its validation checks, false otherwise.
Length of the control array.
The parent control.
A control is pending when its status is PENDING.
True if this control is in the process of conducting a validation check, false otherwise.
A control is pristine if the user has not yet changed
the value in the UI.
True if the user has not yet changed the value in the UI; compare dirty.
Programmatic changes to a control's value do not mark it dirty.
Retrieves the top-level ancestor of this control.
InternalTrue if the control is marked as touched.
A control is marked touched once the user has triggered
a blur event on it.
True if the control has not been marked as touched
A control is untouched if the user has not yet triggered
a blur event on it.
Reports the update strategy of the AbstractControl (meaning
the event on which the control updates itself).
Possible values: 'change' | 'blur' | 'submit'
Default value: 'change'
A control is valid when its status is VALID.
True if the control has passed all of its validation tests, false otherwise.
Returns the function that is used to determine the validity of this control synchronously.
If multiple validators have been added, this will be a single composed function.
See Validators.compose() for additional information.
Add an asynchronous validator or validators to this control, without affecting other validators.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
Adding a validator that already exists will have no effect.
The new asynchronous validator function or functions to add to this control.
Add a synchronous validator or validators to this control, without affecting other validators.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
Adding a validator that already exists will have no effect. If duplicate validator functions
are present in the validators array, only the first instance would be added to a form
control.
The new validator function or functions to add to this control.
Get the AbstractControl at the given index in the array.
Index in the array to retrieve the control. If index is negative, it will wrap
around from the back, and if index is greatly negative (less than -length), the result is
undefined. This behavior is the same as Array.at(index).
Remove all controls in the FormArray.
Optionaloptions: { emitEvent?: boolean }Specifies whether this FormArray instance should emit events after all controls are removed.
emitEvent: When true or not supplied (the default), both the statusChanges and
valueChanges observables emit events with the latest status and value when all controls
in this FormArray instance are removed. When false, no events are emitted.const arr = new FormArray([
new FormControl(),
new FormControl()
]);
console.log(arr.length); // 2
arr.clear();
console.log(arr.length); // 0
It's a simpler and more efficient alternative to removing all elements one by one:
const arr = new FormArray([
new FormControl(),
new FormControl()
]);
while (arr.length) {
arr.removeAt(0);
}
Empties out the async validator list.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
Empties out the synchronous validator list.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
Disables the control. This means the control is exempt from validation checks and
excluded from the aggregate value of any parent. Its status is DISABLED.
If the control has children, all children are also disabled.
Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }Configuration options that determine how the control propagates changes and emits events after the control is disabled.
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the statusChanges,
valueChanges and events
observables emit events with the latest status and value when the control is disabled.
When false, no events are emitted.Optionaloptions: ControlOptionsEnables the control. This means the control is included in validation checks and the aggregate value of its parent. Its status recalculates based on its value and its validators.
By default, if the control has children, all children are enabled.
Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }Configure options that control how the control propagates changes and emits events when marked as untouched
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the statusChanges,
valueChanges and events
observables emit events with the latest status and value when the control is enabled.
When false, no events are emitted.Optionaloptions: ControlOptionsRetrieves a child control given the control's name or path.
This signature for get supports non-const (mutable) arrays. Inferred type
information will not be as robust, so prefer to pass a readonly array if possible.
The code of the error to check
Optionalpath: ControlPathA list of control names that designates how to move from the current control to the control that should be queried for errors.
error data for that particular error. If the control or error is not present, null is returned.
For example, for the following FormGroup:
form = new FormGroup({
address: new FormGroup({ street: new FormControl() })
});
The path to the 'street' control from the root form would be 'address' -> 'street'.
It can be provided to this method in one of two formats:
['address', 'street']'address.street'The aggregate value of the array, including any disabled controls.
Reports all values regardless of disabled status.
Check whether an asynchronous validator function is present on this control. The provided validator must be a reference to the exact same function that was provided.
The asynchronous validator to check for presence. Compared by function reference.
Whether the provided asynchronous validator was found on this control.
The code of the error to check
Optionalpath: ControlPathA list of control names that designates how to move from the current control to the control that should be queried for errors.
whether the given error is present in the control at the given path.
If the control is not present, false is returned.
For example, for the following FormGroup:
form = new FormGroup({
address: new FormGroup({ street: new FormControl() })
});
The path to the 'street' control from the root form would be 'address' -> 'street'.
It can be provided to this method in one of two formats:
['address', 'street']'address.street'If no path is given, this method checks for the error on the current control.
Optionalpath: ControlPathOptionalpath: ControlPathCheck whether a synchronous validator function is present on this control. The provided validator must be a reference to the exact same function that was provided.
The validator to check for presence. Compared by function reference.
Whether the provided validator was found on this control.
// Reference to the RequiredValidator
const ctrl = new FormControl<number | null>(0, Validators.required);
expect(ctrl.hasValidator(Validators.required)).toEqual(true)
// Reference to anonymous function inside MinValidator
const minValidator = Validators.min(3);
const ctrl = new FormControl<number | null>(0, minValidator);
expect(ctrl.hasValidator(minValidator)).toEqual(true)
expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)
Insert a new AbstractControl at the given index in the array.
Index in the array to insert the control. If index is negative, wraps around
from the back. If index is greatly negative (less than -length), prepends to the array.
This behavior is the same as Array.splice(index, 0, control).
Form control to be inserted
inserts a new control at the specified index. If the index is undefined the new control will be added to the end.
Optionalindex: number(optional) the index where the control should be created
Optionalstate: T(optional) the initial state of the new control
Optionaloptions: ControlEventOptions(optional) ControlEventOptions
Marks the control and all its descendant controls as touched.
Optionalopts: { emitEvent?: boolean }Configuration options that determine how the control propagates changes and emits events after marking is applied.
emitEvent: When true or not supplied (the default), the events
observable emits a TouchedChangeEvent with the touched property being true.
When false, no events are emitted.Marks the control as dirty. A control becomes dirty when
the control's value is changed through the UI; compare markAsTouched.
Optionalopts: OnlySelfConfiguration options that determine how the control propagates changes and emits events after marking is applied.
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the events
observable emits a PristineChangeEvent with the pristine property being false.
When false, no events are emitted.Marks the control as pending.
A control is pending while the control performs async validation.
Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }Configuration options that determine how the control propagates changes and emits events after marking is applied.
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the statusChanges
observable emits an event with the latest status the control is marked pending
and the events observable emits a StatusChangeEvent with the status property being
PENDING When false, no events are emitted.Marks the control as pristine.
If the control has any children, marks all children as pristine,
and recalculates the pristine status of all parent
controls.
Optionalopts: OnlySelfConfiguration options that determine how the control emits events after marking is applied.
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the events
observable emits a PristineChangeEvent with the pristine property being true.
When false, no events are emitted.Marks the control as touched. A control is touched by focus and
blur events that do not change the value.
Optionalopts: OnlySelfConfiguration options that determine how the control propagates changes and emits events after marking is applied.
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the events
observable emits a TouchedChangeEvent with the touched property being true.
When false, no events are emitted.Marks the control as untouched.
If the control has any children, also marks all children as untouched
and recalculates the touched status of all parent controls.
Optionalopts: OnlySelfConfiguration options that determine how the control propagates changes and emits events after the marking is applied.
onlySelf: When true, mark only this control. When false or not supplied,
marks all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the events
observable emits a TouchedChangeEvent with the touched property being false.
When false, no events are emitted.Patches the value of the FormArray. It accepts an array that matches the
structure of the control, and does its best to match the values to the correct
controls in the group.
It accepts both super-sets and sub-sets of the array without throwing an error.
Optionaloptions: ControlEventOptionsConfigure options that determine how the control propagates changes and emits events after the value changes
onlySelf: When true, each change only affects this control, and not its parent. Default
is false.emitEvent: When true or not supplied (the default), both the statusChanges and
valueChanges observables emit events with the latest status and value when the control
value is updated. When false, no events are emitted. The configuration options are passed to
the updateValueAndValidity method.Insert a new AbstractControl at the end of the array.
Form control to be inserted
Optionaloptions: ControlEventOptionsSpecifies whether this FormArray instance should emit events after a new control is added.
emitEvent: When true or not supplied (the default), both the statusChanges and
valueChanges observables emit events with the latest status and value when the control is
inserted. When false, no events are emitted.Remove an asynchronous validator from this control, without affecting other validators. Validators are compared by function reference; you must pass a reference to the exact same validator function as the one that was originally set. If a provided validator is not found, it is ignored.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
The asynchronous validator or validators to remove.
Remove the control at the given index in the array.
Index in the array to remove the control. If index is negative, wraps around
from the back. If index is greatly negative (less than -length), removes the first
element. This behavior is the same as Array.splice(index, 1).
Optionalopts: ControlEventOptionsRemove a synchronous validator from this control, without affecting other validators. Validators are compared by function reference; you must pass a reference to the exact same validator function as the one that was originally set. If a provided validator is not found, it is ignored.
The validator or validators to remove.
// Reference to the RequiredValidator
const ctrl = new FormControl<string | null>('', Validators.required);
ctrl.removeValidators(Validators.required);
// Reference to anonymous function inside MinValidator
const minValidator = Validators.min(3);
const ctrl = new FormControl<string | null>('', minValidator);
expect(ctrl.hasValidator(minValidator)).toEqual(true)
expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)
ctrl.removeValidators(minValidator);
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
Resets the FormArray and all descendants are marked pristine and untouched, and the
value of all descendants to null or null maps.
You reset to a specific form state by passing in an array of states that matches the structure of the control. The state is a standalone value or a form state object with both a value and a disabled status.
Optionalvalue: T[]Array of values for the controls
Optionaloptions: ControlEventOptionsConfigure options that determine how the control propagates changes and emits events after the value changes
onlySelf: When true, each change only affects this control, and not its parent. Default
is false.emitEvent: When true or not supplied (the default), both the statusChanges and
valueChanges
observables emit events with the latest status and value when the control is reset.
When false, no events are emitted.
The configuration options are passed to the updateValueAndValidity method.const arr = new FormArray([
new FormControl(),
new FormControl()
]);
arr.reset(['name', 'last name']);
console.log(arr.value); // ['name', 'last name']
arr.reset([
{value: 'name', disabled: true},
'last'
]);
console.log(arr.value); // ['last']
console.log(arr.at(0).status); // 'DISABLED'
Sets the asynchronous validators that are active on this control. Calling this overwrites any existing asynchronous validators.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
If you want to add a new validator without affecting existing ones, consider
using addAsyncValidators() method instead.
Replace an existing control.
Index in the array to replace the control. If index is negative, wraps around
from the back. If index is greatly negative (less than -length), replaces the first
element. This behavior is the same as Array.splice(index, 1, control).
The AbstractControl control to replace the existing control
Optionaloptions: ControlEventOptionsSpecifies whether this FormArray instance should emit events after an existing control is replaced with a new one.
emitEvent: When true or not supplied (the default), both the statusChanges and
valueChanges observables emit events with the latest status and value when the control is
replaced with a new one. When false, no events are emitted.Optionalopts: ControlEventOptionsOptionalopts: ControlEventOptionsSets errors on a form control when running validations manually, rather than automatically.
Calling setErrors also updates the validity of the parent control.
Sets the parent of the control
The new parent.
Sets the synchronous validators that are active on this control. Calling this overwrites any existing synchronous validators.
When you add or remove a validator at run time, you must call
updateValueAndValidity() for the new validation to take effect.
If you want to add a new validator without affecting existing ones, consider
using addValidators() method instead.
Sets the value of the FormArray. It accepts an array that matches
the structure of the control.
This method performs strict checks, and throws an error if you try to set the value of a control that doesn't exist or if you exclude the value of a control.
Optionaloptions: ControlEventOptionsConfigure options that determine how the control propagates changes and emits events after the value changes
onlySelf: When true, each change only affects this control, and not its parent. Default
is false.emitEvent: When true or not supplied (the default), both the statusChanges and
valueChanges
observables emit events with the latest status and value when the control value is updated.
When false, no events are emitted.
The configuration options are passed to the updateValueAndValidity method.Recalculates the value and validation status of the control.
By default, it also updates the value and validity of its ancestors.
Optionalopts: { emitEvent?: boolean; onlySelf?: boolean }Configuration options determine how the control propagates changes and emits events after updates and validity checks are applied.
onlySelf: When true, only update this control. When false or not supplied,
update all direct ancestors. Default is false.emitEvent: When true or not supplied (the default), the statusChanges,
valueChanges and events
observables emit events with the latest status and value when the control is updated.
When false, no events are emitted.
An object containing any errors generated by failing validation, or null if there are no errors.