{ "id": "api/forms/NgModel", "title": "NgModel", "contents": "\n\n
\n
\n
\n \n API > @angular/forms\n
\n
\n mode_edit\n code\n
\n
\n \n
\n

NgModellink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

Creates a FormControl instance from a domain model and binds it\nto a form control element.

\n\n

See more...

\n
\n \n \n \n \n
\n

See alsolink

\n \n
\n\n\n

NgModulelink

\n\n\n\n \n
\n

Selectorslink

\n \n
    \n
  • [ngModel]:not([formControlName]):not([formControl])
    • \n \n
\n \n
\n\n\n\n \n\n
\n

Propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n control: FormControl\n Read-Only\n \n \n \n
\n \n @Input()
name: string\n 		\n \n

Tracks the name bound to the directive. If a parent form exists, it\nuses this name as a key to retrieve this control's value.

\n\n \n
\n \n @Input('disabled')
isDisabled: boolean\n 		\n \n

Tracks whether the control is disabled.

\n\n \n
\n \n @Input('ngModel')
model: any\n 		\n \n

Tracks the value bound to this directive.

\n\n \n
\n \n @Input('ngModelOptions')
options: {\n name?: string;\n standalone?: boolean;\n updateOn?: FormHooks;\n}\n 		\n \n

Tracks the configuration options for this ngModel instance.

\n\n

name: An alternative to setting the name attribute on the form control element. See\nthe example for using NgModel\nas a standalone control.

\n

standalone: When set to true, the ngModel will not register itself with its parent form,\nand acts as if it's not in the form. Defaults to false. If no parent form exists, this option\nhas no effect.

\n

updateOn: Defines the event upon which the form control value and validity update.\nDefaults to 'change'. Possible values: 'change' | 'blur' | 'submit'.

\n\n
\n \n @Output('ngModelChange')
update: EventEmitter\n 		\n \n

Event emitter for producing the ngModelChange event after\nthe view model updates.

\n\n \n
\n \n path: string[]\n Read-Only\n \n

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

\n\n \n
\n \n formDirective: any\n Read-Only\n \n

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

\n\n \n
\n
\n\n\n
\n

Inherited from NgControllink

\n \n
\n\n\n\n
\n

Inherited from AbstractControlDirectivelink

\n \n
\n\n\n\n\n\n\n \n
\n

Template variable referenceslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
IdentifierUsage
ngModel#myTemplateVar=\"ngModel\"
\n
\n\n\n\n \n
\n

Descriptionlink

\n

The FormControl instance tracks the value, user interaction, and\nvalidation status of the control and keeps the view synced with the model. If used\nwithin a parent form, the directive also registers itself with the form as a child\ncontrol.

\n

This directive is used by itself or as part of a larger form. Use the\nngModel selector to activate it.

\n

It accepts a domain model as an optional Input. If you have a one-way binding\nto ngModel with [] syntax, changing the domain model's value in the component\nclass sets the value in the view. If you have a two-way binding with [()] syntax\n(also known as 'banana-in-a-box syntax'), the value in the UI always syncs back to\nthe domain model in your class.

\n

To inspect the properties of the associated FormControl (like the validity state),\nexport the directive into a local template variable using ngModel as the key (ex:\n#myVar=\"ngModel\"). You can then access the control using the directive's control property.\nHowever, the most commonly used properties (like valid and dirty) also exist on the control\nfor direct access. See a full list of properties directly available in\nAbstractControlDirective.

\n\n

Using ngModel on a standalone controllink

\n

The following examples show a simple standalone control using ngModel:

\n\nimport {Component} from '@angular/core';\n\n@Component({\n selector: 'example-app',\n template: `\n <input [(ngModel)]=\"name\" #ctrl=\"ngModel\" required>\n\n <p>Value: {{ name }}</p>\n <p>Valid: {{ ctrl.valid }}</p>\n\n <button (click)=\"setValue()\">Set value</button>\n `,\n})\nexport class SimpleNgModelComp {\n name: string = '';\n\n setValue() {\n this.name = 'Nancy';\n }\n}\n\n\n

When using the ngModel within <form> tags, you'll also need to supply a name attribute\nso that the control can be registered with the parent form under that name.

\n

In the context of a parent form, it's often unnecessary to include one-way or two-way binding,\nas the parent form syncs the value for you. You access its properties by exporting it into a\nlocal template variable using ngForm such as (#f=\"ngForm\"). Use the variable where\nneeded on form submission.

\n

If you do need to populate initial values into your form, using a one-way binding for\nngModel tends to be sufficient as long as you use the exported form's value rather\nthan the domain model's value on submit.

\n

Using ngModel within a formlink

\n

The following example shows controls using ngModel within a form:

\n\nimport {Component} from '@angular/core';\nimport {NgForm} from '@angular/forms';\n\n@Component({\n selector: 'example-app',\n template: `\n <form #f=\"ngForm\" (ngSubmit)=\"onSubmit(f)\" novalidate>\n <input name=\"first\" ngModel required #first=\"ngModel\">\n <input name=\"last\" ngModel>\n <button>Submit</button>\n </form>\n\n <p>First name value: {{ first.value }}</p>\n <p>First name valid: {{ first.valid }}</p>\n <p>Form value: {{ f.value | json }}</p>\n <p>Form valid: {{ f.valid }}</p>\n `,\n})\nexport class SimpleFormComp {\n onSubmit(f: NgForm) {\n console.log(f.value); // { first: '', last: '' }\n console.log(f.valid); // false\n }\n}\n\n\n

Using a standalone ngModel within a grouplink

\n

The following example shows you how to use a standalone ngModel control\nwithin a form. This controls the display of the form, but doesn't contain form data.

\n\n<form>\n <input name=\"login\" ngModel placeholder=\"Login\">\n <input type=\"checkbox\" ngModel [ngModelOptions]=\"{standalone: true}\"> Show more options?\n</form>\n<!-- form value: {login: ''} -->\n\n

Setting the ngModel name attribute through optionslink

\n

The following example shows you an alternate way to set the name attribute. Here,\nan attribute identified as name is used within a custom form control component. To still be able\nto specify the NgModel's name, you must specify it using the ngModelOptions input instead.

\n\n<form>\n <my-custom-form-control name=\"Nancy\" ngModel [ngModelOptions]=\"{name: 'user'}\">\n </my-custom-form-control>\n</form>\n<!-- form value: {user: ''} -->\n\n\n
\n \n\n \n\n \n\n \n\n
\n

Methodslink

\n \n \n\n \n \n \n \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n viewToModelUpdate()\n \n link

\n
\n mode_edit\n code\n
\n
\n
\n

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

\n\n
\n
\n \n\n viewToModelUpdate(newValue: any): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n newValue\n any\n

The new value emitted by ngModelChange.

\n\n
\n\n \n
Returns
\n

void

\n\n \n\n\n \n\n \n
\n
\n\n \n
\n\n \n\n
\n

Inherited from NgControllink

\n \n
\n\n\n\n
\n

Inherited from AbstractControlDirectivelink

\n \n
\n\n\n\n\n \n \n\n
\n
\n\n\n" }