@angular/forms

FormControlName

directive

stable

Syncs a FormControl in an existing FormGroup to a form control element by name.

Reactive Forms Guide FormControl AbstractControl

API

    
      class FormControlName extends NgControl implements OnChanges ,OnDestroy {  constructor(parent: ControlContainer, validators: (ValidatorFn | Validator)[], asyncValidators: (AsyncValidatorFn | AsyncValidator)[], valueAccessors: ControlValueAccessor[], _ngModelWarningConfig: string | null, renderer?: Renderer2 | undefined, injector?: Injector | undefined);  readonly control: FormControl<any>;  @Input('formControlName') name: string | number | null;  @Input('disabled') set isDisabled(value: boolean);  @Input('ngModel') model: any;  @Output('ngModelChange') update: EventEmitter<any>;  viewToModelUpdate(newValue: any): void;  readonly path: string[];  readonly formDirective: any;  override valueAccessor: ControlValueAccessor | null;  protected override isCustomControlBased: boolean;  protected override readonly selectedValueAccessor: ControlValueAccessor | null;  protected override parseErrorsValidator: ValidatorFn | null;  protected override customControlBindings: { value?: unknown; disabled?: boolean | undefined; touched?: boolean | undefined; dirty?: boolean | undefined; valid?: boolean | undefined; invalid?: boolean | undefined; pending?: boolean | undefined; required?: boolean | undefined; errors?: ValidationErrors | null | undefined; } | null;  protected override setupCustomControl(): void;  protected override ngControlUpdate(host: ControlDirectiveHost<undefined>, bindRequired: boolean): void;  protected override readonly shouldBindRequired: boolean;  protected override removeParseErrorsValidator(control: AbstractControl<any, any, any> | null | undefined): void;  override readonly value: any;  override readonly valid: boolean | null;  override readonly invalid: boolean | null;  override readonly pending: boolean | null;  override readonly disabled: boolean | null;  override readonly enabled: boolean | null;  override readonly errors: ValidationErrors | null;  override readonly pristine: boolean | null;  override readonly dirty: boolean | null;  override readonly touched: boolean | null;  override readonly status: string | null;  override readonly untouched: boolean | null;  override readonly statusChanges: any;  override readonly valueChanges: any;  override readonly validator: ValidatorFn | null;  override readonly asyncValidator: AsyncValidatorFn | null;  override reset(value?: any): void;  override hasError(errorCode: string, path?: string | (string | number)[] | undefined): boolean;  override getError(errorCode: string, path?: string | (string | number)[] | undefined): any;}

constructor

FormControlName

@paramparentControlContainer

@paramvalidators(ValidatorFn | Validator)[]

@paramasyncValidators(AsyncValidatorFn | AsyncValidator)[]

@paramvalueAccessorsControlValueAccessor[]

@param_ngModelWarningConfigstring | null

@paramrendererRenderer2 | undefined

@paraminjectorInjector | undefined

@returnsFormControlName

control

FormControl<any>

Tracks the FormControl instance bound to the directive.

Tracks the name of the FormControl bound to the directive. The name corresponds to a key in the parent FormGroup or FormArray. Accepts a name as a string or a number. The name in the form of a string is useful for individual forms, while the numerical form allows for form controls to be bound to indices when iterating over controls in a FormArray.

isDisabled

boolean

Triggers a warning in dev mode that this input should not be used with reactive forms.

model

any

@deprecated

as of v6

update

EventEmitter<any>

@deprecated

as of v6

viewToModelUpdate

void

Sets the new value for the view model and emits an ngModelChange event.

@paramnewValueany

The new value for the view model.

@returnsvoid

path

string[]

Returns an array that represents the path from the top-level form to this control. Each index is the string name of the control on that level.

formDirective

any

The top-level directive for this group if present, otherwise null.

valueAccessor

ControlValueAccessor | null

The value accessor for the control

isCustomControlBased

boolean

selectedValueAccessor

ControlValueAccessor | null

parseErrorsValidator

ValidatorFn | null

Validator function that returns current parse errors.

customControlBindings

{ value?: unknown; disabled?: boolean | undefined; touched?: boolean | undefined; dirty?: boolean | undefined; valid?: boolean | undefined; invalid?: boolean | undefined; pending?: boolean | undefined; required?: boolean | undefined; errors?: ValidationErrors | null | undefined; } | null

Tracks last bound values to avoid unnecessary FVC updates.

setupCustomControl

void

@returnsvoid

ngControlUpdate

void

@paramhostControlDirectiveHost<undefined>

@parambindRequiredboolean

@returnsvoid

shouldBindRequired

boolean

Whether the control should bind the required property (in custom control mode).

Can be overridden by subclasses that handle required in a different way.

removeParseErrorsValidator

void

@paramcontrolAbstractControl<any, any, any> | null | undefined

@returnsvoid

value

any

Reports the value of the control if it is present, otherwise null.

valid

boolean | null

Reports whether the control is valid. A control is considered valid if no validation errors exist with the current value. If the control is not present, null is returned.

invalid

boolean | null

Reports whether the control is invalid, meaning that an error exists in the input value. If the control is not present, null is returned.

pending

boolean | null

Reports whether a control is pending, meaning that async validation is occurring and errors are not yet available for the input value. If the control is not present, null is returned.

disabled

boolean | null

Reports whether the control is disabled, meaning that the control is disabled in the UI and is exempt from validation checks and excluded from aggregate values of ancestor controls. If the control is not present, null is returned.

enabled

boolean | null

Reports whether the control is enabled, meaning that the control is included in ancestor calculations of validity or value. If the control is not present, null is returned.

errors

ValidationErrors | null

Reports the control's validation errors. If the control is not present, null is returned.

pristine

boolean | null

Reports whether the control is pristine, meaning that the user has not yet changed the value in the UI. If the control is not present, null is returned.

dirty

boolean | null

Reports whether the control is dirty, meaning that the user has changed the value in the UI. If the control is not present, null is returned.

touched

boolean | null

Reports whether the control is touched, meaning that the user has triggered a blur event on it. If the control is not present, null is returned.

status

string | null

Reports the validation status of the control. Possible values include: 'VALID', 'INVALID', 'DISABLED', and 'PENDING'. If the control is not present, null is returned.

untouched

boolean | null

Reports whether the control is untouched, meaning that the user has not yet triggered a blur event on it. If the control is not present, null is returned.

statusChanges

any

Returns a multicasting observable that emits a validation status whenever it is calculated for the control. If the control is not present, null is returned.

valueChanges

any

Returns a multicasting observable of value changes for the control that emits every time the value of the control changes in the UI or programmatically. If the control is not present, null is returned.

validator

ValidatorFn | null

Synchronous validator function composed of all the synchronous validators registered with this directive.

asyncValidator

AsyncValidatorFn | null

Asynchronous validator function composed of all the asynchronous validators registered with this directive.

reset

void

Resets the control with the provided value if the control is present.

@paramvalueany

@returnsvoid

hasError

boolean

Reports whether the control with the given path has the error specified.

@paramerrorCodestring

The code of the error to check

@parampathstring | (string | number)[] | undefined

A list of control names that designates how to move from the current control to the control that should be queried for errors.

@returnsboolean

whether the given error is present in the control at the given path.

If the control is not present, false is returned.

Usage notes

For example, for the following FormGroup:

form = new FormGroup({
  address: new FormGroup({ street: new FormControl() })
});

The path to the 'street' control from the root form would be 'address' -> 'street'.

It can be provided to this method in one of two formats:

An array of string control names, e.g. ['address', 'street']
A period-delimited list of control names in one string, e.g. 'address.street'

If no path is given, this method checks for the error on the current control.

getError

any

Reports error data for the control with the given path.

@paramerrorCodestring

The code of the error to check

@parampathstring | (string | number)[] | undefined

A list of control names that designates how to move from the current control to the control that should be queried for errors.

@returnsany

error data for that particular error. If the control or error is not present, null is returned.

Usage notes

For example, for the following FormGroup:

form = new FormGroup({
  address: new FormGroup({ street: new FormControl() })
});

The path to the 'street' control from the root form would be 'address' -> 'street'.

It can be provided to this method in one of two formats:

An array of string control names, e.g. ['address', 'street']
A period-delimited list of control names in one string, e.g. 'address.street'

Description

Syncs a FormControl in an existing FormGroup to a form control element by name.

Exported by

ReactiveFormsModule

Usage Notes

Register `FormControl` within a group

The following example shows how to register multiple form controls within a form group and set their value.

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

@Component({
  selector: 'example-app',
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      @if (first.invalid) {
        <div>Name is too short.</div>
      }
      <input formControlName="first" placeholder="First name" />
      <input formControlName="last" placeholder="Last name" />

      <button type="submit">Submit</button>
    </form>
    <button (click)="setValue()">Set preset value</button>
  `,
  standalone: false,
})
export class SimpleFormGroup {
  form = new FormGroup({
    first: new FormControl('Nancy', Validators.minLength(2)),
    last: new FormControl('Drew'),
  });

  get first(): any {
    return this.form.get('first');
  }

  onSubmit(): void {
    console.log(this.form.value); // {first: 'Nancy', last: 'Drew'}
  }

  setValue() {
    this.form.setValue({first: 'Carson', last: 'Drew'});
  }
}

To see formControlName examples with different form control types, see:

Radio buttons: RadioControlValueAccessor
Selects: SelectControlValueAccessor

Use with ngModel is deprecated

Support for using the ngModel input property and ngModelChange event with reactive form directives has been deprecated in Angular v6 and is scheduled for removal in a future version of Angular.

FormControlName

On this page

Register FormControl within a group

Social Media

Community

Resources

Community translations

Register `FormControl` within a group