Forms API Overview

Comprehensive reference for Angular’s reactive forms API including FormControl, FormGroup, FormArray, and Validators.

The Angular Forms API provides a robust set of tools for building reactive forms in your Angular applications. This API consists of fundamental building blocks that enable you to track form values, manage validation, and handle user interactions.

Core Concepts

Angular’s reactive forms are built on four fundamental building blocks:

• FormControl: Tracks the value and validation status of an individual form control
• FormGroup: Tracks the value and validation status of a group of form controls
• FormArray: Tracks the value and validation status of an array of form controls
• FormRecord: Tracks the value and validation status of a collection of form controls with dynamic keys

Key Classes

FormControl

The FormControl class tracks the value and validation status of an individual form control. It extends the AbstractControl class and provides methods for setting values, validating input, and responding to changes.

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

const nameControl = new FormControl('', Validators.required);
console.log(nameControl.value); // ''
console.log(nameControl.status); // 'INVALID'

Learn more about FormControl →

FormGroup

The FormGroup class aggregates the values of multiple FormControl instances into a single object, with each control name as the key. It calculates its status by reducing the status values of its children.

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

const form = new FormGroup({
  firstName: new FormControl('Nancy'),
  lastName: new FormControl('Drew')
});

console.log(form.value); // { firstName: 'Nancy', lastName: 'Drew' }

Learn more about FormGroup →

FormArray

The FormArray class tracks the value and validity state of an array of form controls. It’s useful for managing dynamic lists of controls.

import { FormArray, FormControl } from '@angular/forms';

const arr = new FormArray([
  new FormControl('Nancy'),
  new FormControl('Drew')
]);

console.log(arr.value); // ['Nancy', 'Drew']
console.log(arr.length); // 2

Validators

The Validators class provides a set of built-in validators for form controls, including required, email, min, max, minLength, maxLength, and pattern.

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

const emailControl = new FormControl('', [
  Validators.required,
  Validators.email
]);

Learn more about Validators →

Type Safety

Angular forms support strict typing with TypeScript. You can specify the type of values your controls will hold:

const ageControl = new FormControl<number>(25);
const nameControl = new FormControl<string>('John');

const form = new FormGroup({
  age: ageControl,
  name: nameControl
});

// form.value is typed as { age: number | null, name: string | null }

Validation

Forms support both synchronous and asynchronous validation:

Synchronous Validators

const control = new FormControl('', Validators.required);

Asynchronous Validators

function asyncValidator(control: AbstractControl): Observable<ValidationErrors | null> {
  return checkUsername(control.value).pipe(
    map(exists => exists ? { usernameTaken: true } : null)
  );
}

const usernameControl = new FormControl('', {
  validators: Validators.required,
  asyncValidators: asyncValidator
});

Status Values

Form controls and groups can have the following status values:

• VALID: The control has passed all validation checks
• INVALID: The control has failed one or more validation checks
• PENDING: The control is in the midst of conducting a validation check
• DISABLED: The control is exempt from validation checks

Update Strategies

You can configure when form values and validity are updated:

• change (default): Update on every change event
• blur: Update when the control loses focus
• submit: Update when the parent form is submitted

const control = new FormControl('', {
  validators: Validators.required,
  updateOn: 'blur'
});

Resources

• Reactive Forms Guide
• Form Validation Guide
• Typed Forms Guide