Help Angular by taking a 1 minute survey!Go to surveyHome
API > @angular/forms

FormBuilder

Creates an AbstractControl from a user-specified configuration.

See more...

      
      class FormBuilder {
  group(controlsConfig: { [key: string]: any; }, options: AbstractControlOptions | { [key: string]: any; } = null): FormGroup
  control(formState: any, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormControl
  array(controlsConfig: any[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormArray
}

See also

Description

The FormBuilder provides syntactic sugar that shortens creating instances of a FormControl, FormGroup, or FormArray. It reduces the amount of boilerplate needed to build complex forms.

Methods

group()

Construct a new FormGroup instance.
group(controlsConfig: { [key: string]: any; }, options: AbstractControlOptions | { [key: string]: any; } = null): FormGroup
      
      group(controlsConfig: { [key: string]: any; }, options: AbstractControlOptions | { [key: string]: any; } = null): FormGroup
Parameters
controlsConfig object

A collection of child controls. The key for each child is the name under which it is registered.
options AbstractControlOptions | { [key: string]: any; }

Configuration options object for the FormGroup. The object can have two shapes:

1) AbstractControlOptions object (preferred), which consists of:

  • validators: A synchronous validator function, or an array of validator functions
  • asyncValidators: A single async validator or array of async validator functions
  • updateOn: The event upon which the control should be updated (options: 'change' | 'blur' | submit')

2) Legacy configuration object, which consists of:

  • validator: A synchronous validator function, or an array of validator functions
  • asyncValidator: A single async validator or array of async validator functions

Optional. Default is null.
Returns

FormGroup

control()

Construct a new FormControl with the given state, validators and options.
control(formState: any, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormControl
      
      control(formState: any, validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormControl
Parameters
formState any

Initializes the control with an initial state value, or with an object that contains both a value and a disabled status.
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.
Returns

FormControl

Usage Notes

Initialize a control as disabled

The following example returns a control with an initial value in a disabled state.

import {Component, Inject} from '@angular/core'; import {FormBuilder, FormControl, FormGroup, Validators} from '@angular/forms'; /* . . . */ @Component({ selector: 'app-disabled-form-control', template: ` <input [formControl]="control" placeholder="First"> ` }) export class DisabledFormControlComponent { control: FormControl; constructor(private fb: FormBuilder) { this.control = fb.control({value: 'my val', disabled: true}); } } 
      
      import {Component, Inject} from '@angular/core';
import {FormBuilder, FormControl, FormGroup, Validators} from '@angular/forms';
/* . . . */
@Component({
  selector: 'app-disabled-form-control',
  template: `
    <input [formControl]="control" placeholder="First">
  `
})
export class DisabledFormControlComponent {
  control: FormControl;

  constructor(private fb: FormBuilder) {
    this.control = fb.control({value: 'my val', disabled: true});
  }
}

array()

Constructs a new FormArray from the given array of configurations, validators and options.
array(controlsConfig: any[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormArray
      
      array(controlsConfig: any[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[], asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[]): FormArray
Parameters
controlsConfig any[]

An array of child controls or control configs. Each child control is given an index when 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.
Returns

FormArray