This is the archived documentation for Angular v5. Please visit angular.io to see documentation for the current version of Angular.

FormGroupName

npm Package @angular/forms
Module import { FormGroupName } from '@angular/forms';
Source forms/src/directives/reactive_directives/form_group_name.ts

Syncs a nested FormGroup to a DOM element.

Overview

      
      @Directive({ selector: '[formGroupName]', providers: [formGroupNameProvider] })
class FormGroupName extends AbstractFormGroupDirective implements OnInit, OnDestroy {
  name: string
  // inherited from forms/AbstractFormGroupDirective
  ngOnInit(): void
  ngOnDestroy(): void
  get control: FormGroup
  get path: string[]
  get formDirective: Form | null
  get validator: ValidatorFn | null
  get asyncValidator: AsyncValidatorFn | null
  // inherited from forms/ControlContainer
  name: string
  get formDirective: Form | null
  get path: string[] | null
  // inherited from forms/AbstractControlDirective
  get control: AbstractControl | null
  get value: any
  get valid: boolean | null
  get invalid: boolean | null
  get pending: boolean | null
  get disabled: boolean | null
  get enabled: boolean | null
  get errors: ValidationErrors | null
  get pristine: boolean | null
  get dirty: boolean | null
  get touched: boolean | null
  get status: string | null
  get untouched: boolean | null
  get statusChanges: Observable<any> | null
  get valueChanges: Observable<any> | null
  get path: string[] | null
  reset(value: any = undefined): void
  hasError(errorCode: string, path?: string[]): boolean
  getError(errorCode: string, path?: string[]): any
}

How To Use

This directive can only be used with a parent FormGroupDirective (selector: [formGroup]).

It accepts the string name of the nested FormGroup you want to link, and will look for a FormGroup registered with that name in the parent FormGroup instance you passed into FormGroupDirective.

Nested form groups can come in handy when you want to validate a sub-group of a form separately from the rest or when you'd like to group the values of certain controls into their own nested object.

Access the group: You can access the associated FormGroup using the get method. Ex: this.form.get('name').

You can also access individual controls within the group using dot syntax. Ex: this.form.get('name.first')

Get the value: the value property is always synced and available on the FormGroup. See a full list of available properties in AbstractControl.

Set the value: You can set an initial value for each child control when instantiating the FormGroup, or you can set it programmatically later using setValue or patchValue.

Listen to value: If you want to listen to changes in the value of the group, you can subscribe to the valueChanges event. You can also listen to statusChanges to be notified when the validation status is re-calculated.

Example

      
      import {Component} from '@angular/core';
import {FormControl, FormGroup, Validators} from '@angular/forms';

@Component({
  selector: 'example-app',
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <p *ngIf="name.invalid">Name is invalid.</p>

      <div formGroupName="name">
        <input formControlName="first" placeholder="First name">
        <input formControlName="last" placeholder="Last name">
      </div>
      <input formControlName="email" placeholder="Email">
      <button type="submit">Submit</button>
    </form>

    <button (click)="setPreset()">Set preset</button>
`,
})
export class NestedFormGroupComp {
  form = new FormGroup({
    name: new FormGroup({
      first: new FormControl('Nancy', Validators.minLength(2)),
      last: new FormControl('Drew', Validators.required)
    }),
    email: new FormControl()
  });

  get first(): any { return this.form.get('name.first'); }

  get name(): any { return this.form.get('name'); }

  onSubmit() {
    console.log(this.first.value);  // 'Nancy'
    console.log(this.name.value);   // {first: 'Nancy', last: 'Drew'}
    console.log(this.form.value);   // {name: {first: 'Nancy', last: 'Drew'}, email: ''}
    console.log(this.form.status);  // VALID
  }

  setPreset() { this.name.setValue({first: 'Bess', last: 'Marvin'}); }
}

Selectors

      
      [formGroupName]

Inputs

formGroupName bound to FormGroupName.name

Constructor

      
      constructor(parent: ControlContainer, validators: any[], asyncValidators: any[])

Members

      
      name: string