W3cubDocs

/Angular 12

FormGroup

class final

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

See more...

class FormGroup extends AbstractControl {
  constructor(controls: { [key: string]: AbstractControl; }, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])
  controls: {...}
  registerControl(name: string, control: AbstractControl): AbstractControl
  addControl(name: string, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void
  removeControl(name: string, options: { emitEvent?: boolean; } = {}): void
  setControl(name: string, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void
  contains(controlName: string): boolean
  setValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  patchValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  reset(value: any = {}, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  getRawValue(): any
  _syncPendingControls(): boolean
  _forEachChild(cb: (v: any, k: string) => void): void
  _updateValue(): void
  _anyControls(condition: Function): boolean
  _allControlsDisabled(): boolean

  // inherited from forms/AbstractControl
  constructor(validators: ValidatorFn | ValidatorFn[], asyncValidators: AsyncValidatorFn | AsyncValidatorFn[])
  value: any
  validator: ValidatorFn | null
  asyncValidator: AsyncValidatorFn | null
  parent: FormGroup | FormArray | null
  status: string
  valid: boolean
  invalid: boolean
  pending: boolean
  disabled: boolean
  enabled: boolean
  errors: ValidationErrors | null
  pristine: boolean
  dirty: boolean
  touched: boolean
  untouched: boolean
  valueChanges: Observable<any>
  statusChanges: Observable<any>
  updateOn: FormHooks
  root: AbstractControl
  setValidators(validators: ValidatorFn | ValidatorFn[]): void
  setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  addValidators(validators: ValidatorFn | ValidatorFn[]): void
  addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  removeValidators(validators: ValidatorFn | ValidatorFn[]): void
  removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void
  hasValidator(validator: ValidatorFn): boolean
  hasAsyncValidator(validator: AsyncValidatorFn): boolean
  clearValidators(): void
  clearAsyncValidators(): void
  markAsTouched(opts: { onlySelf?: boolean; } = {}): void
  markAllAsTouched(): void
  markAsUntouched(opts: { onlySelf?: boolean; } = {}): void
  markAsDirty(opts: { onlySelf?: boolean; } = {}): void
  markAsPristine(opts: { onlySelf?: boolean; } = {}): void
  markAsPending(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  disable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  enable(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setParent(parent: FormGroup | FormArray): void
  abstract setValue(value: any, options?: Object): void
  abstract patchValue(value: any, options?: Object): void
  abstract reset(value?: any, options?: Object): void
  updateValueAndValidity(opts: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void
  setErrors(errors: ValidationErrors, opts: { emitEvent?: boolean; } = {}): void
  get(path: string | (string | number)[]): AbstractControl | null
  getError(errorCode: string, path?: string | (string | number)[]): any
  hasError(errorCode: string, path?: string | (string | number)[]): boolean
}

Description

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

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.

Further information is available in the Usage Notes...

Constructor

Creates a new FormGroup instance.

This class is "final" and should not be extended. See the public API notes.

constructor(controls: { [key: string]: AbstractControl; }, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[])

Parameters
controls object

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

validatorOrOpts ValidatorFn | AbstractControlOptions | ValidatorFn[]

A synchronous validator function, or an array of such functions, or an AbstractControlOptions object that contains validation functions and a validation trigger.

Optional. Default is undefined.

asyncValidator AsyncValidatorFn | AsyncValidatorFn[]

A single async validator or array of async validator functions

Optional. Default is undefined.

Properties

Property Description
controls: { [key: string]: AbstractControl; } Declared in Constructor

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

Methods

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

registerControl(name: string, control: AbstractControl): AbstractControl

Parameters
name string

The control name to register in the collection

control AbstractControl

Provides the control for the given name

Returns

AbstractControl

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

Add a control to this group.

addControl(name: string, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void

Parameters
name string

The control name to add to the collection

control AbstractControl

Provides the control for the given name

options object

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.

Optional. Default is {}.

Returns

void

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 setControl method instead. This method also updates the value and validity of the control.

Remove a control from this group.

removeControl(name: string, options: { emitEvent?: boolean; } = {}): void

Parameters
name string

The control name to remove from the collection

options object

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

  • 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 removed. When false, no events are emitted.

Optional. Default is {}.

Returns

void

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

Replace an existing control.

setControl(name: string, control: AbstractControl, options: { emitEvent?: boolean; } = {}): void

Parameters
name string

The control name to replace in the collection

control AbstractControl

Provides the control for the given name

options object

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.

Optional. Default is {}.

Returns

void

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

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

contains(controlName: string): boolean

Parameters
controlName string

The control name to check for existence in the collection

Returns

boolean: false for disabled controls, true otherwise.

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

setValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void

Parameters
value object
options object

Optional. Default is {}.

Returns

void

patchValue(value: { [key: string]: any; }, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void

Parameters
value object
options object

Optional. Default is {}.

Returns

void

reset(value: any = {}, options: { onlySelf?: boolean; emitEvent?: boolean; } = {}): void

Parameters
value any

Optional. Default is {}.

options object

Optional. Default is {}.

Returns

void

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

getRawValue(): any

Parameters

There are no parameters.

Returns

any

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

_syncPendingControls(): boolean

Parameters

There are no parameters.

Returns

boolean

_forEachChild(cb: (v: any, k: string) => void): void

Parameters
cb (v: any, k: string) => void
Returns

void

_updateValue(): void

Parameters

There are no parameters.

Returns

void

_anyControls(condition: Function): boolean

Parameters
condition Function
Returns

boolean

_allControlsDisabled(): boolean

Parameters

There are no parameters.

Returns

boolean

Usage notes

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'

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

© 2010–2021 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v12.angular.io/api/forms/FormGroup