> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/angular/angular/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```ts theme={null}
import { FormControl } from '@angular/forms';
```

## Constructor

<ParamField path="formState" type="T | FormControlState<T>" default="null">
  Initial value for the control, or an object that defines the initial value and disabled state.
</ParamField>

<ParamField path="validatorOrOpts" type="ValidatorFn | ValidatorFn[] | FormControlOptions | null" optional>
  A synchronous validator function, an array of such functions, or a `FormControlOptions` object that contains validation functions and a validation trigger.
</ParamField>

<ParamField path="asyncValidator" type="AsyncValidatorFn | AsyncValidatorFn[] | null" optional>
  A single async validator or array of async validator functions.
</ParamField>

## Basic Usage

### Creating a FormControl

```ts theme={null}
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:

```ts theme={null}
const ageControl = new FormControl<number>(25);
const nameControl = new FormControl<string>('');

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

## Properties

<ResponseField name="value" type="T">
  The current value of the control.
</ResponseField>

<ResponseField name="status" type="'VALID' | 'INVALID' | 'PENDING' | 'DISABLED'">
  The validation status of the control.
</ResponseField>

<ResponseField name="valid" type="boolean">
  A control is valid when its status is `VALID`.
</ResponseField>

<ResponseField name="invalid" type="boolean">
  A control is invalid when its status is `INVALID`.
</ResponseField>

<ResponseField name="pending" type="boolean">
  A control is pending when its status is `PENDING`.
</ResponseField>

<ResponseField name="disabled" type="boolean">
  A control is disabled when its status is `DISABLED`.
</ResponseField>

<ResponseField name="enabled" type="boolean">
  A control is enabled as long as its status is not `DISABLED`.
</ResponseField>

<ResponseField name="errors" type="ValidationErrors | null">
  An object containing any errors generated by failing validation, or null if there are no errors.
</ResponseField>

<ResponseField name="pristine" type="boolean">
  A control is pristine if the user has not yet changed the value in the UI.
</ResponseField>

<ResponseField name="dirty" type="boolean">
  A control is dirty if the user has changed the value in the UI.
</ResponseField>

<ResponseField name="touched" type="boolean">
  True if the control is marked as touched.
</ResponseField>

<ResponseField name="untouched" type="boolean">
  True if the control has not been marked as touched.
</ResponseField>

<ResponseField name="defaultValue" type="T">
  The default value of this FormControl, used whenever the control is reset without an explicit value.
</ResponseField>

<ResponseField name="valueChanges" type="Observable<T>">
  A multicasting observable that emits an event every time the value of the control changes.
</ResponseField>

<ResponseField name="statusChanges" type="Observable<FormControlStatus>">
  A multicasting observable that emits an event every time the validation status of the control recalculates.
</ResponseField>

## Methods

### setValue()

Sets a new value for the form control.

<ParamField path="value" type="T" required>
  The new value for the control.
</ParamField>

<ParamField path="options.onlySelf" type="boolean" default="false">
  When true, each change only affects this control, and not its parent.
</ParamField>

<ParamField path="options.emitEvent" type="boolean" default="true">
  When true, both the `statusChanges` and `valueChanges` observables emit events with the latest status and value.
</ParamField>

<ParamField path="options.emitModelToViewChange" type="boolean" default="true">
  When true, each change triggers an `onChange` event to update the view.
</ParamField>

<ParamField path="options.emitViewToModelChange" type="boolean" default="true">
  When true, each change triggers an `ngModelChange` event to update the model.
</ParamField>

```ts theme={null}
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()`.

```ts theme={null}
control.patchValue('new value');
```

### reset()

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

<ParamField path="formState" type="T | FormControlState<T>" optional>
  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.
</ParamField>

<ParamField path="options.onlySelf" type="boolean" default="false">
  When true, each change only affects this control, and not its parent.
</ParamField>

<ParamField path="options.emitEvent" type="boolean" default="true">
  When true, both the `statusChanges` and `valueChanges` observables emit events.
</ParamField>

```ts theme={null}
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.

```ts theme={null}
const value = control.getRawValue();
```

### disable()

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

<ParamField path="options.onlySelf" type="boolean" default="false">
  When true, mark only this control. When false, marks all direct ancestors.
</ParamField>

<ParamField path="options.emitEvent" type="boolean" default="true">
  When true, emit a `statusChanges` event.
</ParamField>

```ts theme={null}
control.disable();
console.log(control.status); // 'DISABLED'
```

### enable()

Enables the control.

```ts theme={null}
control.enable();
console.log(control.disabled); // false
```

### markAsTouched()

Marks the control as touched.

```ts theme={null}
control.markAsTouched();
console.log(control.touched); // true
```

### markAsUntouched()

Marks the control as untouched.

```ts theme={null}
control.markAsUntouched();
console.log(control.untouched); // true
```

### markAsDirty()

Marks the control as dirty.

```ts theme={null}
control.markAsDirty();
console.log(control.dirty); // true
```

### markAsPristine()

Marks the control as pristine.

```ts theme={null}
control.markAsPristine();
console.log(control.pristine); // true
```

### updateValueAndValidity()

Recalculates the value and validation status of the control.

```ts theme={null}
control.updateValueAndValidity();
```

### setValidators()

Sets the synchronous validators that are active on this control.

<ParamField path="validators" type="ValidatorFn | ValidatorFn[] | null" required>
  The new validator or validators.
</ParamField>

```ts theme={null}
control.setValidators([Validators.required, Validators.minLength(5)]);
control.updateValueAndValidity();
```

### setAsyncValidators()

Sets the asynchronous validators that are active on this control.

```ts theme={null}
control.setAsyncValidators(asyncValidator);
control.updateValueAndValidity();
```

### addValidators()

Adds validators to the control.

```ts theme={null}
control.addValidators(Validators.email);
control.updateValueAndValidity();
```

### removeValidators()

Removes validators from the control.

```ts theme={null}
control.removeValidators(Validators.required);
control.updateValueAndValidity();
```

### hasError()

Reports whether the control has the error specified.

<ParamField path="errorCode" type="string" required>
  The error code to check for.
</ParamField>

<ParamField path="path" type="string | (string | number)[]" optional>
  Path to check (used in FormGroup/FormArray).
</ParamField>

```ts theme={null}
const control = new FormControl('', Validators.required);
console.log(control.hasError('required')); // true
```

### getError()

Retrieves the error object for the specified error code.

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

## FormControlOptions

Options object for configuring a `FormControl`.

<ParamField path="validators" type="ValidatorFn | ValidatorFn[]" optional>
  A synchronous validator function, or an array of such functions.
</ParamField>

<ParamField path="asyncValidators" type="AsyncValidatorFn | AsyncValidatorFn[]" optional>
  A single async validator or array of async validator functions.
</ParamField>

<ParamField path="updateOn" type="'change' | 'blur' | 'submit'" default="'change'">
  The event on which the control should update its value and validity.
</ParamField>

<ParamField path="nonNullable" type="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`.
</ParamField>

```ts theme={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`.

<ParamField path="value" type="T" required>
  The value of the control.
</ParamField>

<ParamField path="disabled" type="boolean" required>
  Whether the control is disabled.
</ParamField>

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

## Examples

### Non-Nullable FormControl

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

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

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

### Update on Blur

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

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

### Listening to Value Changes

```ts theme={null}
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

```ts theme={null}
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](/api/forms/form-group) - Group multiple form controls
* [FormArray](/api/forms/form-array) - Manage an array of form controls
* [Validators](/api/forms/validators) - Built-in validation functions
* [Reactive Forms Guide](https://angular.dev/guide/forms/reactive-forms)
* [Form Validation Guide](https://angular.dev/guide/forms/form-validation)