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

FormGroupDirectivelink

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

Binds an existing FormGroup to a DOM element.

\n\n

See more...

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

See alsolink

\n \n
\n\n\n

NgModulelink

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

Selectorslink

\n \n
    \n
  • [formGroup]
    • \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 \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
PropertyDescription
\n \n submitted: boolean\n Read-Only\n \n

Reports whether the form submission has been triggered.

\n\n \n
\n \n directives: FormControlName[]\n \n \n

Tracks the list of added FormControlName instances

\n\n \n
\n \n @Input('formGroup')
form: FormGroup\n 		\n \n

Tracks the FormGroup bound to this directive.

\n\n \n
\n \n @Output()
ngSubmit: EventEmitter\n 		\n \n

Emits an event when the form submission has been triggered.

\n\n \n
\n \n formDirective: Form\n Read-Only\n \n

Returns this directive's instance.

\n\n \n
\n \n control: FormGroup\n Read-Only\n \n

Returns the FormGroup bound to this directive.

\n\n \n
\n \n path: string[]\n Read-Only\n \n

Returns an array representing the path to this group. Because this directive\nalways lives at the top level of a form, it always an empty array.

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

Inherited from ControlContainerlink

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

Inherited from AbstractControlDirectivelink

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

Template variable referenceslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
IdentifierUsage
ngForm#myTemplateVar=\"ngForm\"
\n
\n\n\n\n \n
\n

Descriptionlink

\n

This directive accepts an existing FormGroup instance. It will then use this\nFormGroup instance to match any child FormControl, FormGroup,\nand FormArray instances to child FormControlName, FormGroupName,\nand FormArrayName directives.

\n\n

Register Form Grouplink

\n

The following example registers a FormGroup with first name and last name controls,\nand listens for the ngSubmit event when the button is clicked.

\n\nimport {Component} from '@angular/core';\nimport {FormControl, FormGroup, Validators} from '@angular/forms';\n\n@Component({\n selector: 'example-app',\n template: `\n <form [formGroup]=\"form\" (ngSubmit)=\"onSubmit()\">\n <div *ngIf=\"first.invalid\"> Name is too short. </div>\n\n <input formControlName=\"first\" placeholder=\"First name\">\n <input formControlName=\"last\" placeholder=\"Last name\">\n\n <button type=\"submit\">Submit</button>\n </form>\n <button (click)=\"setValue()\">Set preset value</button>\n `,\n})\nexport class SimpleFormGroup {\n form = new FormGroup({\n first: new FormControl('Nancy', Validators.minLength(2)),\n last: new FormControl('Drew'),\n });\n\n get first(): any {\n return this.form.get('first');\n }\n\n onSubmit(): void {\n console.log(this.form.value); // {first: 'Nancy', last: 'Drew'}\n }\n\n setValue() {\n this.form.setValue({first: 'Carson', last: 'Drew'});\n }\n}\n\n\n\n\n\n
\n \n\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 addControl()\n \n link

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

Method that sets up the control directive in this group, re-calculates its value\nand validity, and adds the instance to the internal list of directives.

\n\n
\n
\n \n\n addControl(dir: FormControlName): FormControl\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormControlName\n

The FormControlName directive instance.

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

FormControl

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

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

Retrieves the FormControl instance from the provided FormControlName directive

\n\n
\n
\n \n\n getControl(dir: FormControlName): FormControl\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormControlName\n

The FormControlName directive instance.

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

FormControl

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

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

Removes the FormControlName instance from the internal list of directives

\n\n
\n
\n \n\n removeControl(dir: FormControlName): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormControlName\n

The FormControlName directive instance.

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

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

Adds a new FormGroupName directive instance to the form.

\n\n
\n
\n \n\n addFormGroup(dir: FormGroupName): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormGroupName\n

The FormGroupName directive instance.

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

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

Performs the necessary cleanup when a FormGroupName directive instance is removed from the\nview.

\n\n
\n
\n \n\n removeFormGroup(dir: FormGroupName): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormGroupName\n

The FormGroupName directive instance.

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

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

Retrieves the FormGroup for a provided FormGroupName directive instance

\n\n
\n
\n \n\n getFormGroup(dir: FormGroupName): FormGroup\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormGroupName\n

The FormGroupName directive instance.

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

FormGroup

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

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

Performs the necessary setup when a FormArrayName directive instance is added to the view.

\n\n
\n
\n \n\n addFormArray(dir: FormArrayName): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormArrayName\n

The FormArrayName directive instance.

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

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

Performs the necessary cleanup when a FormArrayName directive instance is removed from the\nview.

\n\n
\n
\n \n\n removeFormArray(dir: FormArrayName): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormArrayName\n

The FormArrayName directive instance.

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

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

Retrieves the FormArray for a provided FormArrayName directive instance.

\n\n
\n
\n \n\n getFormArray(dir: FormArrayName): FormArray\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormArrayName\n

The FormArrayName directive instance.

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

FormArray

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

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

Sets the new value for the provided FormControlName directive.

\n\n
\n
\n \n\n updateModel(dir: FormControlName, value: any): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n dir\n FormControlName\n

The FormControlName directive instance.

\n\n
\n \n value\n any\n

The new value for the directive's control.

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

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

Method called with the \"submit\" event is triggered on the form.\nTriggers the ngSubmit emitter to emit the \"submit\" event as its payload.

\n\n
\n
\n \n\n onSubmit($event: Event): boolean\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n $event\n Event\n

The \"submit\" event object

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

boolean

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

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

Method called when the \"reset\" event is triggered on the form.

\n\n
\n
\n \n\n onReset(): void\n\n \n\n
Parameters
\n

There are no parameters.

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

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

Resets the form to an initial value and resets its submitted status.

\n\n
\n
\n \n\n resetForm(value: any = undefined): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n value\n any\n

The new value for the form.

\n

Optional. Default is undefined.

\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

Inherited from AbstractControlDirectivelink

\n \n
\n\n\n\n\n \n \n\n
\n
\n\n\n" }