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

FormGrouplink

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

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

\n\n

See more...

\n
\n \n \n \n
\n\nclass FormGroup extends AbstractControl {\n constructor(controls: { [key: string]: AbstractControl; }, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])\n controls: {...}\n registerControl(name: string, control: AbstractControl): AbstractControl\n addControl(name: string, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void\n removeControl(name: string, options: { emitEvent?: boolean; } = {}): void\n setControl(name: string, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void\n contains(controlName: string): boolean\n setValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n patchValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n reset(value: any = {}, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void\n getRawValue(): any\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 \n \n
\n

Descriptionlink

\n

A FormGroup aggregates the values of each child FormControl into one object,\nwith each control name as the key. It calculates its status by reducing the status values\nof its children. For example, if one of the controls in a group is invalid, the entire\ngroup becomes invalid.

\n

FormGroup is one of the three fundamental building blocks used to define forms in Angular,\nalong with FormControl and FormArray.

\n

When instantiating a FormGroup, pass in a collection of child controls as the first\nargument. The key for each child registers the name for the control.

\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 FormGroup instance.

\n\n
\n
\n \n\n constructor(controls: { [key: string]: AbstractControl; }, 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 controls\n object\n

A collection of child controls. The key for each child is the name\nunder which it is registered.

\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

Propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n controls: {\n [key: string]: AbstractControl;\n}\n \n Declared in Constructor\n \n

A collection of child controls. The key for each child is the name\nunder which it is registered.

\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
\n

\n registerControl()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Registers a control with the group's list of controls.

\n\n
\n
\n \n\n registerControl(name: string, control: AbstractControl): AbstractControl\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n name\n string\n

The control name to register in the collection

\n\n
\n \n control\n AbstractControl\n

Provides the control for the given name

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

AbstractControl

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

This method does not update the value or validity of the control.\nUse addControl instead.

\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 addControl()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Add a control to this group.

\n\n
\n
\n \n\n addControl(name: string, control: AbstractControl, options: { 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 \n \n \n
\n \n name\n string\n

The control name to add to the collection

\n\n
\n \n control\n AbstractControl\n

Provides the control for the given name

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

Specifies whether this FormGroup instance should emit events after a new\ncontrol is added.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\nadded. When 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

This method also updates the value and validity of the control.

\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 removeControl()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Remove a control from this group.

\n\n
\n
\n \n\n removeControl(name: string, options: { 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 name\n string\n

The control name to remove from the collection

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

Specifies whether this FormGroup instance should emit events after a\ncontrol is removed.

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\nremoved. When 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

This method also updates the value and validity of the control.

\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 setControl()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Replace an existing control.

\n\n
\n
\n \n\n setControl(name: string, control: AbstractControl, options: { 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 \n \n \n
\n \n name\n string\n

The control name to replace in the collection

\n\n
\n \n control\n AbstractControl\n

Provides the control for the given name

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

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

\n
    \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control is\nreplaced with a new one. When 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
\n

\n contains()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

\n\n
\n
\n \n\n contains(controlName: string): boolean\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n controlName\n string\n

The control name to check for existence in the collection

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

boolean: false for disabled controls, true otherwise.

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

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

\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 setValue()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

\n\n
\n
\n \n\n setValue(value: { [key: string]: any; }, 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 value\n object\n

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

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

Configuration options that determine how the control propagates changes\nand emits events after 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
    • \n
\n

Optional. Default is {}.

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

void

\n\n \n\n\n \n
Throws
\n \n

Error When strict checks fail, such as setting the value of a control\nthat doesn't exist or if you exclude a value of a control that does exist.

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

Usage Noteslink

\n
Set the complete value for the form grouplink
\n\nconst form = new FormGroup({\n first: new FormControl(),\n last: new FormControl()\n});\n\nconsole.log(form.value); // {first: null, last: null}\n\nform.setValue({first: 'Nancy', last: 'Drew'});\nconsole.log(form.value); // {first: 'Nancy', last: 'Drew'}\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 mode_edit\n code\n
\n
\n
\n

Patches the value of the FormGroup. It accepts an object with control\nnames as keys, and does its best to match the values to the correct controls\nin the group.

\n\n
\n
\n \n\n patchValue(value: { [key: string]: any; }, 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 value\n object\n

The object that matches the structure of the group.

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

Configuration options that determine how the control propagates changes and\nemits events after the value is patched.

\n
    \n
  • onlySelf: When true, each change only affects this control and not its parent. Default is\ntrue.
    • \n
  • emitEvent: When true or not supplied (the default), both the statusChanges and\nvalueChanges observables emit events with the latest status and value when the control value\nis updated. When false, no events are emitted. The configuration options are passed to\nthe updateValueAndValidity method.\n
    • \n
\n

Optional. Default is {}.

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

void

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

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

\n\n
\n

Usage Noteslink

\n
Patch the value for a form grouplink
\n\nconst form = new FormGroup({\n first: new FormControl(),\n last: new FormControl()\n});\nconsole.log(form.value); // {first: null, last: null}\n\nform.patchValue({first: 'Nancy'});\nconsole.log(form.value); // {first: 'Nancy', last: null}\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 reset()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

Resets the FormGroup, marks all descendants pristine and untouched and sets\nthe value of all descendants to null.

\n\n
\n
\n \n\n reset(value: any = {}, 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 value\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 {}.

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

Configuration options that determine how the control propagates changes\nand emits events when the group is reset.

\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.\nThe configuration options are passed to the updateValueAndValidity method.
    • \n
\n

Optional. Default is {}.

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

void

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

You reset to a specific form state by passing in a map of states\nthat matches the structure of your form, with control names as keys. The state\nis a standalone value or a form state object with both a value and a disabled\nstatus.

\n\n
\n

Usage Noteslink

\n
Reset the form group valueslink
\n\nconst form = new FormGroup({\n first: new FormControl('first name'),\n last: new FormControl('last name')\n});\n\nconsole.log(form.value); // {first: 'first name', last: 'last name'}\n\nform.reset({ first: 'name', last: 'last name' });\n\nconsole.log(form.value); // {first: 'name', last: 'last name'}\n\n
Reset the form group values and disabled statuslink
\n\nconst form = new FormGroup({\n first: new FormControl('first name'),\n last: new FormControl('last name')\n});\n\nform.reset({\n first: {value: 'name', disabled: true},\n last: 'last'\n});\n\nconsole.log(form.value); // {last: 'last'}\nconsole.log(form.get('first').status); // 'DISABLED'\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 getRawValue()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

\n\n
\n
\n \n\n getRawValue(): any\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

any

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

Retrieves all values regardless of disabled status.\nThe value property is the best way to get the value of the group, because\nit excludes disabled controls in the FormGroup.

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

Usage noteslink

\n

Create a form group with 2 controlslink

\n\nconst form = new FormGroup({\n first: new FormControl('Nancy', Validators.minLength(2)),\n last: new FormControl('Drew'),\n});\n\nconsole.log(form.value); // {first: 'Nancy', last; 'Drew'}\nconsole.log(form.status); // 'VALID'\n\n

Create a form group with a group-level validatorlink

\n

You include group-level validators as the second arg, or group-level async\nvalidators as the third arg. These come in handy when you want to perform validation\nthat considers the value of more than one child control.

\n\nconst form = new FormGroup({\n password: new FormControl('', Validators.minLength(2)),\n passwordConfirm: new FormControl('', Validators.minLength(2)),\n}, passwordMatchValidator);\n\n\nfunction passwordMatchValidator(g: FormGroup) {\n return g.get('password').value === g.get('passwordConfirm').value\n ? null : {'mismatch': true};\n}\n\n

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

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

Set the updateOn property for all controls in a form grouplink

\n

The options object is used to set a default value for each child\ncontrol's updateOn property. If you set updateOn to 'blur' at the\ngroup level, all child controls default to 'blur', unless the child\nhas explicitly specified a different updateOn value.

\n\nconst c = new FormGroup({\n one: new FormControl()\n}, { updateOn: 'blur' });\n\n\n
\n\n\n\n
\n
\n\n\n" }