A FormGroup aggregates the values of each child FormControl into one object,
with each control name as the key. It calculates its status by reducing the status values
of its children. For example, if one of the controls in a group is invalid, the entire
group becomes invalid.
FormGroup is one of the three fundamental building blocks used to define forms in Angular,
along with FormControl and FormArray.
When instantiating a FormGroup, pass in a collection of child controls as the first
argument. The key for each child registers the name for the control.
A collection of child controls. The key for each child is the name
under which it is registered.
validatorOrOpts
A synchronous validator function, or an array of
such functions, or an AbstractControlOptions object that contains validation functions
and a validation trigger.
Optional. Default is undefined.
asyncValidator
A single async validator or array of async validator functions
The new value for the control that matches the structure of the group.
options
Configuration options that determine how the control propagates changes
and emits events after the value changes.
The configuration options are passed to the updateValueAndValidity method.
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.
Optional. Default is {}.
Returns
void
Throws
Error When strict checks fail, such as setting the value of a control
that doesn't exist or if you excluding the value of a control.
Patches the value of the FormGroup. It accepts an object with control
names as keys, and does its best to match the values to the correct controls
in the group.
The object that matches the structure of the group.
options
Configuration options that determine how the control propagates changes and
emits events after the value is patched.
onlySelf: When true, each change only affects this control and not its parent. Default is
true.
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.
Optional. Default is {}.
Returns
void
It accepts both super-sets and sub-sets of the group without throwing an error.
Configuration options that determine how the control propagates changes
and emits events when the group is reset.
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.
Optional. Default is {}.
Returns
void
You reset to a specific form state by passing in a map of states
that matches the structure of your form, with control names as keys. The state
is a standalone value or a form state object with both a value and a disabled
status.
The aggregate value of the FormGroup, including any disabled controls.
getRawValue(): any
getRawValue(): any
Parameters
There are no parameters.
Returns
any
Retrieves all values regardless of disabled status.
The value property is the best way to get the value of the group, because
it excludes disabled controls in the FormGroup.
const form = new FormGroup({
first: new FormControl('Nancy', Validators.minLength(2)),
last: new FormControl('Drew'),
});
console.log(form.value); // {first: 'Nancy', last; 'Drew'}
console.log(form.status); // 'VALID'
const form = new FormGroup({
first: new FormControl('Nancy', Validators.minLength(2)),
last: new FormControl('Drew'),
});
console.log(form.value); // {first: 'Nancy', last; 'Drew'}
console.log(form.status); // 'VALID'
Create a form group with a group-level validatorlink
You include group-level validators as the second arg, or group-level async
validators as the third arg. These come in handy when you want to perform validation
that considers the value of more than one child control.
const form = new FormGroup({
password: new FormControl('', Validators.minLength(2)),
passwordConfirm: new FormControl('', Validators.minLength(2)),
}, passwordMatchValidator);
function passwordMatchValidator(g: FormGroup) {
return g.get('password').value === g.get('passwordConfirm').value
? null : {'mismatch': true};
}
const form = new FormGroup({
password: new FormControl('', Validators.minLength(2)),
passwordConfirm: new FormControl('', Validators.minLength(2)),
}, passwordMatchValidator);
function passwordMatchValidator(g: FormGroup) {
return g.get('password').value === g.get('passwordConfirm').value
? null : {'mismatch': true};
}
Like FormControl instances, you choose to pass in
validators and async validators as part of an options object.
Set the updateOn property for all controls in a form grouplink
The options object is used to set a default value for each child
control's updateOn property. If you set updateOn to 'blur' at the
group level, all child controls default to 'blur', unless the child
has explicitly specified a different updateOn value.
