FormControl

API reference for Angular’s FormControl class, which tracks the value and validation status of an individual form control.

The FormControl class tracks the value and validation status of an individual form control. It is one of the four fundamental building blocks of Angular forms, along with FormGroup, FormArray, and FormRecord.

Import

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

Constructor

formState · T | FormControlState<T> · default: "null"

Initial value for the control, or an object that defines the initial value and disabled state.

validatorOrOpts · ValidatorFn | ValidatorFn[] | FormControlOptions | null

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

asyncValidator · AsyncValidatorFn | AsyncValidatorFn[] | null

A single async validator or array of async validator functions.

Basic Usage

Creating a FormControl

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

// Simple control with initial value
const nameControl = new FormControl('John');

// Control with validator
const emailControl = new FormControl('', Validators.required);

// Control with initial value and disabled state
const ageControl = new FormControl({ value: 25, disabled: true });

// Control with multiple validators
const passwordControl = new FormControl('', [
  Validators.required,
  Validators.minLength(8)
]);

Type Safety

FormControl accepts a generic type argument:

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

// For nullable values
const optionalControl = new FormControl<string | null>(null);

Properties

value · T

The current value of the control.

status · 'VALID' | 'INVALID' | 'PENDING' | 'DISABLED'

The validation status of the control.

valid · boolean

A control is valid when its status is VALID.

invalid · boolean

A control is invalid when its status is INVALID.

pending · boolean

A control is pending when its status is PENDING.

disabled · boolean

A control is disabled when its status is DISABLED.

enabled · boolean

A control is enabled as long as its status is not DISABLED.

errors · ValidationErrors | null

An object containing any errors generated by failing validation, or null if there are no errors.

pristine · boolean

A control is pristine if the user has not yet changed the value in the UI.

dirty · boolean

A control is dirty if the user has changed the value in the UI.

touched · boolean

True if the control is marked as touched.

untouched · boolean

True if the control has not been marked as touched.

defaultValue · T

The default value of this FormControl, used whenever the control is reset without an explicit value.

valueChanges · Observable<T>

A multicasting observable that emits an event every time the value of the control changes.

statusChanges · Observable<FormControlStatus>

A multicasting observable that emits an event every time the validation status of the control recalculates.

Methods

setValue()

Sets a new value for the form control.

value · T · required

The new value for the control.

options.onlySelf · boolean · default: "false"

When true, each change only affects this control, and not its parent.

options.emitEvent · boolean · default: "true"

When true, both the statusChanges and valueChanges observables emit events with the latest status and value.

options.emitModelToViewChange · boolean · default: "true"

When true, each change triggers an onChange event to update the view.

options.emitViewToModelChange · boolean · default: "true"

When true, each change triggers an ngModelChange event to update the model.

const control = new FormControl('initial');
control.setValue('updated');
console.log(control.value); // 'updated'

// Set value without emitting events
control.setValue('silent', { emitEvent: false });

patchValue()

Patches the value of the control. For FormControl, this is functionally the same as setValue().

control.patchValue('new value');

reset()

Resets the form control, marking it pristine and untouched, and resetting the value.

formState · T | FormControlState<T>

Resets the control with an initial value, or an object that defines the initial value and disabled state. If not provided, resets to null or the default value if nonNullable was set.

options.onlySelf · boolean · default: "false"

When true, each change only affects this control, and not its parent.

options.emitEvent · boolean · default: "true"

When true, both the statusChanges and valueChanges observables emit events.

const control = new FormControl('Nancy');
control.reset('Drew');
console.log(control.value); // 'Drew'

// Reset to null (default behavior)
control.reset();
console.log(control.value); // null

// Reset with nonNullable option
const nonNullControl = new FormControl('Nancy', { nonNullable: true });
nonNullControl.reset();
console.log(nonNullControl.value); // 'Nancy'

getRawValue()

Returns the value of the control. For FormControl, the raw value is equivalent to the value.

const value = control.getRawValue();

disable()

Disables the control, meaning it will be exempt from validation checks and excluded from aggregate values of parent controls.

options.onlySelf · boolean · default: "false"

When true, mark only this control. When false, marks all direct ancestors.

options.emitEvent · boolean · default: "true"

When true, emit a statusChanges event.

control.disable();
console.log(control.status); // 'DISABLED'

enable()

Enables the control.

control.enable();
console.log(control.disabled); // false

markAsTouched()

Marks the control as touched.

control.markAsTouched();
console.log(control.touched); // true

markAsUntouched()

Marks the control as untouched.

control.markAsUntouched();
console.log(control.untouched); // true

markAsDirty()

Marks the control as dirty.

control.markAsDirty();
console.log(control.dirty); // true

markAsPristine()

Marks the control as pristine.

control.markAsPristine();
console.log(control.pristine); // true

updateValueAndValidity()

Recalculates the value and validation status of the control.

control.updateValueAndValidity();

setValidators()

Sets the synchronous validators that are active on this control.

validators · ValidatorFn | ValidatorFn[] | null · required

The new validator or validators.

control.setValidators([Validators.required, Validators.minLength(5)]);
control.updateValueAndValidity();

setAsyncValidators()

Sets the asynchronous validators that are active on this control.

control.setAsyncValidators(asyncValidator);
control.updateValueAndValidity();

addValidators()

Adds validators to the control.

control.addValidators(Validators.email);
control.updateValueAndValidity();

removeValidators()

Removes validators from the control.

control.removeValidators(Validators.required);
control.updateValueAndValidity();

hasError()

Reports whether the control has the error specified.

errorCode · string · required

The error code to check for.

path · string | (string | number)[]

Path to check (used in FormGroup/FormArray).

const control = new FormControl('', Validators.required);
console.log(control.hasError('required')); // true

getError()

Retrieves the error object for the specified error code.

const control = new FormControl(2, Validators.min(3));
console.log(control.getError('min')); // { min: 3, actual: 2 }

FormControlOptions

Options object for configuring a FormControl.

validators · ValidatorFn | ValidatorFn[]

A synchronous validator function, or an array of such functions.

asyncValidators · AsyncValidatorFn | AsyncValidatorFn[]

A single async validator or array of async validator functions.

updateOn · 'change' | 'blur' | 'submit' · default: "'change'"

The event on which the control should update its value and validity.

nonNullable · boolean · default: "false"

Whether to use the initial value as the default value. When true, the control will reset to its initial value instead of null.

const control = new FormControl('value', {
  validators: Validators.required,
  asyncValidators: asyncValidator,
  updateOn: 'blur',
  nonNullable: true
});

FormControlState

Interface for defining both a value and disabled state for a FormControl.

value · T · required

The value of the control.

disabled · boolean · required

Whether the control is disabled.

const control = new FormControl({ value: 'text', disabled: true });
console.log(control.value); // 'text'
console.log(control.disabled); // true

Examples

Non-Nullable FormControl

const control = new FormControl('Nancy', { nonNullable: true });

console.log(control.value); // 'Nancy'

control.reset();
console.log(control.value); // 'Nancy' (not null)

Update on Blur

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

// Value and validation only update when the control loses focus

Listening to Value Changes

const control = new FormControl('');

control.valueChanges.subscribe(value => {
  console.log('Value changed to:', value);
});

control.setValue('new value'); // Logs: 'Value changed to: new value'

Custom Async Validator

import { AbstractControl, ValidationErrors } from '@angular/forms';
import { Observable, of } from 'rxjs';
import { delay, map } from 'rxjs/operators';

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

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

console.log(usernameControl.status); // 'PENDING' during validation

See Also

• FormGroup - Group multiple form controls
• FormArray - Manage an array of form controls
• Validators - Built-in validation functions
• Reactive Forms Guide
• Form Validation Guide