@angular/forms

FormGroup

Class

Tracks the value and validity state of a group of FormControl instances.

class FormGroup {
}

Tracks the value and validity state of a group of FormControl instances.

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 four fundamental building blocks used to define forms in Angular, along with FormControl, FormArray, and FormRecord.

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.

FormGroup is intended for use cases where the keys are known ahead of time. If you need to dynamically add and remove controls, use FormRecord instead.

FormGroup accepts an optional type parameter TControl, which is an object type with inner control types as values.

Create a form group with 2 controls

          
            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'

The type argument, and optional controls

FormGroup accepts one generic argument, which is an object containing its inner controls. This type will usually be inferred automatically, but you can always specify it explicitly if you wish.

If you have controls that are optional (i.e. they can be removed, you can use the ? in the type):

          
            const form = new FormGroup<{  first: FormControl<string|null>,  middle?: FormControl<string|null>, // Middle name is optional.  last: FormControl<string|null>,}>({  first: new FormControl('Nancy'),  last: new FormControl('Drew'),});

Create a form group with a group-level validator

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};}

Like FormControl instances, you choose to pass in validators and async validators as part of an options object.

          
            const form = new FormGroup({  password: new FormControl('')  passwordConfirm: new FormControl('')}, { validators: passwordMatchValidator, asyncValidators: otherValidator });

Set the updateOn property for all controls in a form group

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.

          
            const c = new FormGroup({  one: new FormControl()}, { updateOn: 'blur' });

Using a FormGroup with optional controls

It is possible to have optional controls in a FormGroup. An optional control can be removed later using removeControl, and can be omitted when calling reset. Optional controls must be declared optional in the group's type.

          
            const c = new FormGroup<{one?: FormControl<string>}>({  one: new FormControl('')});

Notice that c.value.one has type string|null|undefined. This is because calling c.reset({}) without providing the optional key one will cause it to become null.

controls

ɵTypedOrUntyped<TControl, TControl, { [key: string]: AbstractControl<any, any>; }>

registerControl

2 overloads

Registers a control with the group's list of controls. In a strongly-typed group, the control must be in the group's type (possibly as an optional key).

This method does not update the value or validity of the control. Use FormGroupaddControl addControl instead.

@paramnameK

The control name to register in the collection

@paramcontrolTControl[K]

Provides the control for the given name

@returnsTControl[K]

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any>; }>

@paramnamestring

@paramcontrolAbstractControl<any, any>

@returnsAbstractControl<any, any>

addControl

2 overloads

Add a control to this group. In a strongly-typed group, the control must be in the group's type (possibly as an optional key).

If a control with a given name already exists, it would not be replaced with a new one. If you want to replace an existing control, use the FormGroupsetControl setControl method instead. This method also updates the value and validity of the control.

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any>; }>

@paramnamestring

The control name to add to the collection

@paramcontrolAbstractControl<any, any>

Provides the control for the given name

@paramoptions{ emitEvent?: boolean; }

Specifies whether this FormGroup 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 added. When false, no events are emitted.

@returnsvoid

@paramnameK

@paramcontrolRequired<TControl>[K]

@paramoptions{ emitEvent?: boolean; }

@returnsvoid

removeControl

2 overloads

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any>; }>

@paramnamestring

@paramoptions{ emitEvent?: boolean; }

@returnsvoid

@paramnameɵOptionalKeys<TControl> & S

@paramoptions{ emitEvent?: boolean; }

@returnsvoid

setControl

2 overloads

Replace an existing control. In a strongly-typed group, the control must be in the group's type (possibly as an optional key).

If a control with a given name does not exist in this FormGroup, it will be added.

@paramnameK

The control name to replace in the collection

@paramcontrolTControl[K]

Provides the control for the given name

@paramoptions{ emitEvent?: boolean; }

Specifies whether this FormGroup instance should emit events after an existing control is replaced.

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.

@returnsvoid

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any>; }>

@paramnamestring

@paramcontrolAbstractControl<any, any>

@paramoptions{ emitEvent?: boolean; }

@returnsvoid

contains

2 overloads

Check whether there is an enabled control with the given name in the group.

Reports false for disabled controls. If you'd like to check for existence in the group only, use AbstractControlget get instead.

@paramcontrolNameK

The control name to check for existence in the collection

@returnsboolean

@paramthisFormGroup<{ [key: string]: AbstractControl<any, any>; }>

@paramcontrolNamestring

@returnsboolean

setValue

void

Sets the value of the FormGroup. It accepts an object that matches the structure of the group, with control names as keys.

@paramvalueɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>

The new value for the control that matches the structure of the group.

@paramoptions{ onlySelf?: boolean; emitEvent?: boolean; }

Configuration options that determine how the control propagates changes and emits events after the value changes. The configuration options are passed to the AbstractControlupdateValueAndValidity * 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.

@returnsvoid

Usage notes

Set the complete value for the form group

          
            const form = new FormGroup({  first: new FormControl(),  last: new FormControl()});console.log(form.value);   // {first: null, last: null}form.setValue({first: 'Nancy', last: 'Drew'});console.log(form.value);   // {first: 'Nancy', last: 'Drew'}

patchValue

void

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.

It accepts both super-sets and sub-sets of the group without throwing an error.

@paramvalueɵIsAny<TControl, { [key: string]: any; }, Partial<{ [K in keyof TControl]: ɵValue<TControl[K]>; }>>

The object that matches the structure of the group.

@paramoptions{ onlySelf?: boolean; emitEvent?: boolean; }

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 AbstractControlupdateValueAndValidity updateValueAndValidity method.

@returnsvoid

Usage notes

Patch the value for a form group

          
            const form = new FormGroup({   first: new FormControl(),   last: new FormControl()});console.log(form.value);   // {first: null, last: null}form.patchValue({first: 'Nancy'});console.log(form.value);   // {first: 'Nancy', last: null}

reset

void

Resets the FormGroup, marks all descendants pristine and untouched and sets the value of all descendants to their default values, or null if no defaults were provided.

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.

@paramvalue

ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, Partial<{ [K in keyof TControl]: ɵValue<TControl[K]>; }>>, any>

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

@paramoptions{ onlySelf?: boolean; emitEvent?: boolean; }

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 AbstractControlupdateValueAndValidity * updateValueAndValidity method.

@returnsvoid

Usage notes

Reset the form group values

          
            const form = new FormGroup({  first: new FormControl('first name'),  last: new FormControl('last name')});console.log(form.value);  // {first: 'first name', last: 'last name'}form.reset({ first: 'name', last: 'last name' });console.log(form.value);  // {first: 'name', last: 'last name'}

Reset the form group values and disabled status

          
            const form = new FormGroup({  first: new FormControl('first name'),  last: new FormControl('last name')});form.reset({  first: {value: 'name', disabled: true},  last: 'last'});console.log(form.value);  // {last: 'last'}console.log(form.get('first').status);  // 'DISABLED'

getRawValue

ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>, any>

The aggregate value of the FormGroup, including any disabled controls.

Retrieves all values regardless of disabled status.

@returns

ɵTypedOrUntyped<TControl, ɵIsAny<TControl, { [key: string]: any; }, { [K in keyof TControl]: ɵRawValue<TControl[K]>; }>, any>

value

TValue

The current value of the control.

For a FormControl, the current value.
For an enabled FormGroup, the values of enabled controls as an object with a key-value pair for each member of the group.
For a disabled FormGroup, the values of all controls as an object with a key-value pair for each member of the group.
For a FormArray, the values of enabled controls as an array.

validator

2 overloads

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.

asyncValidator

2 overloads

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.

parent

FormGroup<any> | FormArray<any>

The parent control.

status

FormControlStatus

The validation status of the control.

valid

boolean

A control is valid when its status is VALID.

invalid

boolean

A control is invalid when its status is INVALID.

pending

boolean

A control is pending when its status is PENDING.

disabled

boolean

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.

enabled

boolean

A control is enabled as long as its status is not DISABLED.

errors

ValidationErrors

An object containing any errors generated by failing validation, or null if there are no errors.

pristine

boolean

A control is pristine if the user has not yet changed the value in the UI.

dirty

boolean

A control is dirty if the user has changed the value in the UI.

touched

boolean

True if the control is marked as touched.

A control is marked touched once the user has triggered a blur event on it.

untouched

boolean

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.

events

Observable<ControlEvent<TValue>>

A 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.

valueChanges

Observable<TValue>

A 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.

TODO: this should be piped from events() but is breaking in G3

statusChanges

Observable<FormControlStatus>

A multicasting observable that emits an event every time the validation status of the control recalculates.

updateOn

FormHooks

Reports the update strategy of the AbstractControl (meaning the event on which the control updates itself). Possible values: 'change' | 'blur' | 'submit' Default value: 'change'

setValidators

void

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.

@paramvalidatorsValidatorFn | ValidatorFn[]

@returnsvoid

setAsyncValidators

void

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.

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[]

@returnsvoid

addValidators

void

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.

@paramvalidatorsValidatorFn | ValidatorFn[]

The new validator function or functions to add to this control.

@returnsvoid

addAsyncValidators

void

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.

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[]

The new asynchronous validator function or functions to add to this control.

@returnsvoid

removeValidators

void

Remove 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.

@paramvalidatorsValidatorFn | ValidatorFn[]

The validator or validators to remove.

@returnsvoid

Usage notes

Reference to a ValidatorFn

          
            // Reference to the RequiredValidatorconst ctrl = new FormControl<string | null>('', Validators.required);ctrl.removeValidators(Validators.required);// Reference to anonymous function inside MinValidatorconst 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.

removeAsyncValidators

void

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.

@paramvalidatorsAsyncValidatorFn | AsyncValidatorFn[]

The asynchronous validator or validators to remove.

@returnsvoid

hasValidator

boolean

Check 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.

@paramvalidatorValidatorFn

The validator to check for presence. Compared by function reference.

@returnsboolean

Usage notes

Reference to a ValidatorFn

          
            // Reference to the RequiredValidatorconst ctrl = new FormControl<number | null>(0, Validators.required);expect(ctrl.hasValidator(Validators.required)).toEqual(true)// Reference to anonymous function inside MinValidatorconst 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)

hasAsyncValidator

boolean

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.

@paramvalidatorAsyncValidatorFn

The asynchronous validator to check for presence. Compared by function reference.

@returnsboolean

clearValidators

void

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.

@returnsvoid

clearAsyncValidators

void

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.

@returnsvoid

markAsTouched

void

Marks the control as touched. A control is touched by focus and blur events that do not change the value.

@paramopts{ onlySelf?: boolean; emitEvent?: 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 events observable emits a TouchedChangeEvent with the touched property being true. When false, no events are emitted.

@returnsvoid

markAllAsTouched

void

Marks the control and all its descendant controls as touched.

@paramopts{ 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.

@returnsvoid

markAsUntouched

void

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.

@paramopts{ onlySelf?: boolean; emitEvent?: boolean; }

Configuration 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.

@returnsvoid

markAsDirty

void

Marks the control as dirty. A control becomes dirty when the control's value is changed through the UI; compare markAsTouched.

@paramopts{ onlySelf?: boolean; emitEvent?: 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 events observable emits a PristineChangeEvent with the pristine property being false. When false, no events are emitted.

@returnsvoid

markAsPristine

void

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.

@paramopts{ onlySelf?: boolean; emitEvent?: boolean; }

Configuration 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.

@returnsvoid

markAsPending

void

Marks the control as pending.

A control is pending while the control performs async validation.

@paramopts{ onlySelf?: boolean; emitEvent?: 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.

@returnsvoid

disable

void

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.

@paramopts{ onlySelf?: boolean; emitEvent?: 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.

@returnsvoid

enable

void

Enables 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.

@paramopts{ onlySelf?: boolean; emitEvent?: 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.

@returnsvoid

setParent

void

Sets the parent of the control

@paramparentFormGroup<any> | FormArray<any>

The new parent.

@returnsvoid

updateValueAndValidity

void

Recalculates the value and validation status of the control.

By default, it also updates the value and validity of its ancestors.

@paramopts{ onlySelf?: boolean; emitEvent?: 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.

@returnsvoid

setErrors

void

Sets errors on a form control when running validations manually, rather than automatically.

Calling setErrors also updates the validity of the parent control.

@paramerrorsValidationErrors

@paramopts{ emitEvent?: boolean; }

Configuration options that determine how the control propagates changes and emits events after the control errors are set.

emitEvent: When true or not supplied (the default), the statusChanges observable emits an event after the errors are set.

@returnsvoid

Usage notes

Manually set the errors for a control

          
            const login = new FormControl('someLogin');login.setErrors({  notUnique: true});expect(login.valid).toEqual(false);expect(login.errors).toEqual({ notUnique: true });login.setValue('someOtherLogin');expect(login.valid).toEqual(true);

get

2 overloads

Retrieves a child control given the control's name or path.

This signature for get supports strings and const arrays (.get(['foo', 'bar'] as const)).

@parampathP

@returnsAbstractControl<ɵGetProperty<TRawValue, P>, ɵGetProperty<TRawValue, P>>

Retrieves 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.

@parampathP

@returnsAbstractControl<ɵGetProperty<TRawValue, P>, ɵGetProperty<TRawValue, P>>

getError

any

Reports error data for the control with the given path.

@paramerrorCodestring

The code of the error to check

@parampathstring | (string | number)[]

A list of control names that designates how to move from the current control to the control that should be queried for errors.

@returnsany

Usage notes

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:

An array of string control names, e.g. ['address', 'street']
A period-delimited list of control names in one string, e.g. 'address.street'

hasError

boolean

Reports whether the control with the given path has the error specified.

@paramerrorCodestring

The code of the error to check

@parampathstring | (string | number)[]

A list of control names that designates how to move from the current control to the control that should be queried for errors.

@returnsboolean

Usage notes

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:

An array of string control names, e.g. ['address', 'street']
A period-delimited list of control names in one string, e.g. 'address.street'

If no path is given, this method checks for the error on the current control.

root

AbstractControl<any, any>

Retrieves the top-level ancestor of this control.