@angular/forms

FormBuilder

Class

stable

Creates an AbstractControl from a user-specified configuration.

API

    
      class FormBuilder {  readonly nonNullable: NonNullableFormBuilder;  group<T extends {}>(controls: T, options?: AbstractControlOptions | null | undefined): FormGroup<NullableFormControls<T>>;  group(controls: { [key: string]: any; }, options: { [key: string]: any; }): FormGroup<any>;
  record<T>(controls: { [key: string]: T; }, options?: AbstractControlOptions | null): FormRecord<Element<T, null>>;  control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & { initialValueIsDefault: true; }): FormControl<T>;  control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & { nonNullable: true; }): FormControl<T>;  control<T>(formState: T | FormControlState<T>, opts: FormControlOptions, asyncValidator: AsyncValidatorFn | AsyncValidatorFn[]): FormControl<T | null>;  control<T>(formState: T | FormControlState<T>, validatorOrOpts?: ValidatorFn | FormControlOptions | ValidatorFn[] | null | undefined, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null | undefined): FormControl<T | null>;
  array<T>(controls: T[], validatorOrOpts?: ValidatorFn | AbstractControlOptions | ValidatorFn[] | null | undefined, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null | undefined): FormArray<Element<T, null>>;}

nonNullable

NonNullableFormBuilder

Returns a FormBuilder in which automatically constructed FormControl elements have {nonNullable: true} and are non-nullable.

Constructing non-nullable controls

When constructing a control, it will be non-nullable, and will reset to its initial value.

let nnfb = new FormBuilder().nonNullable;
let name = nnfb.control('Alex'); // FormControl<string>
name.reset();
console.log(name); // 'Alex'

Constructing non-nullable groups or arrays

When constructing a group or array, all automatically created inner controls will be non-nullable, and will reset to their initial values.

let nnfb = new FormBuilder().nonNullable;
let name = nnfb.group({who: 'Alex'}); // FormGroup<{who: FormControl<string>}>
name.reset();
console.log(name); // {who: 'Alex'}

Constructing nullable fields on groups or arrays

It is still possible to have a nullable field. In particular, any FormControl which is already constructed will not be altered. For example:

let nnfb = new FormBuilder().nonNullable;
// FormGroup<{who: FormControl<string|null>}>
let name = nnfb.group({who: new FormControl('Alex')});
name.reset(); console.log(name); // {who: null}

Because the inner control is constructed explicitly by the caller, the builder has no control over how it is created, and cannot exclude the null.

group

2 overloads

Constructs a new FormGroup instance. Accepts a single generic argument, which is an object containing all the keys and corresponding inner control types.

@paramcontrolsT

A collection of child controls. The key for each child is the name under which it is registered. Each value can be one of:

An AbstractControl instance passed through as-is.
A raw value shorthand for fb.control(value).
A FormControlState object ({value, disabled}) initializes the control with a value and disabled status.
A ControlConfig tuple [value | FormControlState, validatorOrOpts?, asyncValidator?]. The second element accepts a ValidatorFn, an array of ValidatorFn, or an AbstractControlOptions object (use this to set updateOn). The optional third element accepts an AsyncValidatorFn or an array of AsyncValidatorFn.

@paramoptionsAbstractControlOptions | null | undefined

Configuration options object for the FormGroup. The object should have the AbstractControlOptions type and might contain the following fields:

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').

@returnsFormGroup<NullableFormControls<T>>

Usage notes

Different ways to specify a control value

const fb = new FormBuilder();

fb.group({
  // Raw value  equivalent to fb.control('Ada')
  name: 'Ada',

  // FormControlState  sets initial value and disabled status
  city: {value: 'London', disabled: true},

  // ControlConfig tuple  value with a sync validator
  email: ['ada@example.com', Validators.email],

  // ControlConfig tuple  value, sync validator, and async validator
  username: ['ada', Validators.required, checkUsernameAvailable],

  // ControlConfig tuple  disabled value with updateOn option
  role: [{value: 'admin', disabled: true}, {updateOn: 'blur'}],

  // Pre-built control  passed through unchanged
  address: new FormControl('', Validators.required),
});

Constructs a new FormGroup instance.

@deprecated

This API is not typesafe and can result in issues with Closure Compiler renaming. Use the FormBuilder#group overload with AbstractControlOptions instead. Note that AbstractControlOptions expects validators and asyncValidators to be valid validators. If you have custom validators, make sure their validation function parameter is AbstractControl and not a sub-class, such as FormGroup. These functions will be called with an object of type AbstractControl and that cannot be automatically downcast to a subclass, so TypeScript sees this as an error. For example, change the (group: FormGroup) => ValidationErrors|null signature to be (group: AbstractControl) => ValidationErrors|null.

@paramcontrols{ [key: string]: any; }

A record of child controls. The key for each child is the name under which the control is registered.

@paramoptions{ [key: string]: any; }

Configuration options object for the FormGroup. The legacy configuration object consists of:

validator: A synchronous validator function, or an array of validator functions.
asyncValidator: A single async validator or array of async validator functions Note: the legacy format is deprecated and might be removed in one of the next major versions of Angular.

@returnsFormGroup<any>

record

FormRecord<Element<T, null>>

Constructs a new FormRecord instance. Accepts a single generic argument, which is an object containing all the keys and corresponding inner control types.

@paramcontrols{ [key: string]: T; }

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

@paramoptionsAbstractControlOptions | null

Configuration options object for the FormRecord. The object should have the AbstractControlOptions type and might contain the following fields:

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').

@returnsFormRecord<Element<T, null>>

control

4 overloads

@deprecated

Use nonNullable instead.

@paramformStateT | FormControlState<T>

@paramoptsFormControlOptions & { initialValueIsDefault: true; }

@returnsFormControl<T>

@paramformStateT | FormControlState<T>

@paramoptsFormControlOptions & { nonNullable: true; }

@returnsFormControl<T>

@deprecated

When passing an options argument, the asyncValidator argument has no effect.

@paramformStateT | FormControlState<T>

@paramoptsFormControlOptions

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[]

@returnsFormControl<T | null>

@paramformStateT | FormControlState<T>

@paramvalidatorOrOptsValidatorFn | FormControlOptions | ValidatorFn[] | null | undefined

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[] | null | undefined

@returnsFormControl<T | null>

array

FormArray<Element<T, null>>

Constructs a new FormArray from the given array of configurations, validators and options. Accepts a single generic argument, which is the type of each control inside the array.

@paramcontrolsT[]

An array of child controls or control configs. Each child control is given an index when it is registered.

@paramvalidatorOrOptsValidatorFn | AbstractControlOptions | ValidatorFn[] | null | undefined

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

@paramasyncValidatorAsyncValidatorFn | AsyncValidatorFn[] | null | undefined

A single async validator or array of async validator functions.

@returnsFormArray<Element<T, null>>

Description

Creates an AbstractControl from a user-specified configuration.

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.

FormBuilder

On this page

API

nonNullable

group

Different ways to specify a control value

record

control

array

Description

Social Media

Community

Resources

Community translations