FormGroupDirective

directive

Binds an existing FormGroup to a DOM element.

See more...

See also

  • Reactive Forms Guide

  • AbstractControl

    Register Form Group

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

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

NgModule

Selectors

  • [formGroup]

Properties

Property Description
submitted: boolean Read-Only

Reports whether the form submission has been triggered.

directives: FormControlName[]

Tracks the list of added FormControlName instances

@Input('formGroup')form: FormGroup

Tracks the FormGroup bound to this directive.

@Output()ngSubmit: EventEmitter

Emits an event when the form submission has been triggered.

formDirective: Form Read-Only

Returns this directive's instance.

control: FormGroup Read-Only

Returns the FormGroup bound to this directive.

path: string[] Read-Only

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

Inherited from ControlContainer

Inherited from AbstractControlDirective

Template variable references

Identifier Usage
ngForm #myTemplateVar="ngForm"

Description

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

Methods

A lifecycle method called when the directive's inputs change. For internal use only.

ngOnChanges(changes: SimpleChanges): void

Parameters
changes SimpleChanges

A object of key/value pairs for the set of changed inputs.

Returns

void

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

addControl(dir: FormControlName): FormControl

Parameters
dir FormControlName

The FormControlName directive instance.

Returns

FormControl

Retrieves the FormControl instance from the provided FormControlName directive

getControl(dir: FormControlName): FormControl

Parameters
dir FormControlName

The FormControlName directive instance.

Returns

FormControl

Removes the FormControlName instance from the internal list of directives

removeControl(dir: FormControlName): void

Parameters
dir FormControlName

The FormControlName directive instance.

Returns

void

Adds a new FormGroupName directive instance to the form.

addFormGroup(dir: FormGroupName): void

Parameters
dir FormGroupName

The FormGroupName directive instance.

Returns

void

No-op method to remove the form group.

removeFormGroup(dir: FormGroupName): void

Parameters
dir FormGroupName

The FormGroupName directive instance.

Returns

void

Retrieves the FormGroup for a provided FormGroupName directive instance

getFormGroup(dir: FormGroupName): FormGroup

Parameters
dir FormGroupName

The FormGroupName directive instance.

Returns

FormGroup

Adds a new FormArrayName directive instance to the form.

addFormArray(dir: FormArrayName): void

Parameters
dir FormArrayName

The FormArrayName directive instance.

Returns

void

No-op method to remove the form array.

removeFormArray(dir: FormArrayName): void

Parameters
dir FormArrayName

The FormArrayName directive instance.

Returns

void

Retrieves the FormArray for a provided FormArrayName directive instance.

getFormArray(dir: FormArrayName): FormArray

Parameters
dir FormArrayName

The FormArrayName directive instance.

Returns

FormArray

Sets the new value for the provided FormControlName directive.

updateModel(dir: FormControlName, value: any): void

Parameters
dir FormControlName

The FormControlName directive instance.

value any

The new value for the directive's control.

Returns

void

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

onSubmit($event: Event): boolean

Parameters
$event Event

The "submit" event object

Returns

boolean

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

onReset(): void

Parameters

There are no parameters.

Returns

void

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

resetForm(value: any = undefined): void

Parameters
value any

The new value for the form.

Optional. Default is undefined.

Returns

void

Inherited from AbstractControlDirective

© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v9.angular.io/api/forms/FormGroupDirective