From Get docs
< @angular/formsAngular/docs/8/api/forms/formcontrolname



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

See also



  • [formControlName]


Property Description
control: FormControl

Read-Only Tracks the FormControl instance bound to the directive.

@Input('formControlName')name: string Tracks the name of the FormControl bound to the directive. The name corresponds to a key in the parent FormGroup or FormArray.
@Input('disabled')isDisabled: boolean

Write-Only Triggers a warning that this input should not be used with reactive forms.

@Input('ngModel')model: any
@Output('ngModelChange')update: EventEmitter
path: string[]

Read-Only 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

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


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

asyncValidator: AsyncValidatorFn

Read-Only Async validator function composed of all the async validators registered with this directive.

Inherited from NgControl

  • name: string | null
  • valueAccessor: ControlValueAccessor | null
  • validator: ValidatorFn | null
  • asyncValidator: AsyncValidatorFn | null

Inherited from AbstractControlDirective

  • abstract control: AbstractControl | null
  • value: any
  • valid: boolean | null
  • invalid: boolean | null
  • pending: boolean | null
  • disabled: boolean | null
  • enabled: boolean | null
  • errors: ValidationErrors | null
  • pristine: boolean | null
  • dirty: boolean | null
  • touched: boolean | null
  • status: string | null
  • untouched: boolean | null
  • statusChanges: Observable<any> | null
  • valueChanges: Observable<any> | null
  • path: string[] | null


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';

  selector: 'example-app',
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <div *ngIf="first.invalid"> Name is too short. </div>

      <input formControlName="first" placeholder="First name">
      <input formControlName="last" placeholder="Last name">

      <button type="submit">Submit</button>
   <button (click)="setValue()">Set preset value</button>
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

Support for using the ngModel input property and ngModelChange event with reactive form directives has been deprecated in Angular v6 and will be removed in Angular v7.

Now deprecated:

<form [formGroup]="form">
  <input formControlName="first" [(ngModel)]="value">
this.value = 'some value';

This has been deprecated for a few reasons. First, developers have found this pattern confusing. It seems like the actual ngModel directive is being used, but in fact it's an input/output property named ngModel on the reactive form directive that simply approximates (some of) its behavior. Specifically, it allows getting/setting the value and intercepting value events. However, some of ngModel's other features - like delaying updates withngModelOptions or exporting the directive - simply don't work, which has understandably caused some confusion.

In addition, this pattern mixes template-driven and reactive forms strategies, which we generally don't recommend because it doesn't take advantage of the full benefits of either strategy. Setting the value in the template violates the template-agnostic principles behind reactive forms, whereas adding a FormControl/FormGroup layer in the class removes the convenience of defining forms in the template.

To update your code before v7, you'll want to decide whether to stick with reactive form directives (and get/set values using reactive forms patterns) or switch over to template-driven directives.

After (choice 1 - use reactive forms):

<form [formGroup]="form">
  <input formControlName="first">
this.form.get('first').setValue('some value');

After (choice 2 - use template-driven forms):

<input [(ngModel)]="value">
this.value = 'some value';

By default, when you use this pattern, you will see a deprecation warning once in dev mode. You can choose to silence this warning by providing a config for ReactiveFormsModule at import time:

imports: [
  ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'})

Alternatively, you can choose to surface a separate warning for each instance of this pattern with a config value of "always". This may help to track down where in the code the pattern is being used as the code is being updated.


A lifecycle method called when the directive's inputs change. For internal use only.

ngOnChanges(changes: SimpleChanges)

changes SimpleChanges A object of key/value pairs for the set of changed inputs.

Lifecycle method called before the directive's instance is destroyed. For internal use only.

ngOnDestroy(): void


There are no parameters.



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

viewToModelUpdate(newValue: any): void

newValue any The new value for the view model.


Inherited from NgControl

  • abstract viewToModelUpdate(newValue: any): void

Inherited from AbstractControlDirective

  • reset(value: any = undefined): void
  • hasError(errorCode: string, path?: string | (string | number)[]): boolean
  • getError(errorCode: string, path?: string | (string | number)[]): any

© 2010–2020 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.