NgModel
Creates a FormControl
instance from a domain model and binds it
to a form control element.
NgModule
Selectors
[ngModel]:not([formControlName]):not([formControl])
Properties
Property | Description |
---|---|
control: FormControl
|
Read-only. |
viewModel: any
|
|
@Input()
|
|
@Input('disabled')
|
|
@Input('ngModel')
|
|
@Input('ngModelOptions')
|
Options object for this name: An alternative to setting the name attribute on the form control element.
Sometimes, especially with custom form components, the name attribute might be used
as an
standalone: Defaults to false. If this is set to true, the
updateOn: Defaults to
|
@Output('ngModelChange')
|
|
path: string[]
|
Read-only. |
formDirective: any
|
Read-only. |
validator: ValidatorFn | null
|
Read-only. |
asyncValidator: AsyncValidatorFn | null
|
Read-only. |
Inherited from NgControl
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
Template variable references
Identifier | Usage |
---|---|
ngModel |
#myTemplateVar="ngModel" |
Description
The FormControl
instance will track the value, user interaction, and
validation status of the control and keep the view synced with the model. If used
within a parent form, the directive will also register itself with the form as a child
control.
This directive can be used by itself or as part of a larger form. All you need is the
ngModel
selector to activate it.
It accepts a domain model as an optional Input
. If you have a one-way binding
to ngModel
with []
syntax, changing the value of the domain model in the component
class will set the value in the view. If you have a two-way binding with [()]
syntax
(also known as 'banana-box syntax'), the value in the UI will always be synced back to
the domain model in your class as well.
If you wish to inspect the properties of the associated FormControl
(like
validity state), you can also export the directive into a local template variable using
ngModel
as the key (ex: #myVar="ngModel"
). You can then access the control using the
directive's control
property, but most properties you'll need (like valid
and dirty
)
will fall through to the control anyway, so you can access them directly. You can see a
full list of properties directly available in AbstractControlDirective
.
The following is an example of a simple standalone control using ngModel
:
- import {Component} from '@angular/core';
-
- @Component({
- selector: 'example-app',
- template: `
- <input [(ngModel)]="name" #ctrl="ngModel" required>
-
- <p>Value: {{ name }}</p>
- <p>Valid: {{ ctrl.valid }}</p>
-
- <button (click)="setValue()">Set value</button>
- `,
- })
- export class SimpleNgModelComp {
- name: string = '';
-
- setValue() { this.name = 'Nancy'; }
- }
When using the ngModel
within <form>
tags, you'll also need to supply a name
attribute
so that the control can be registered with the parent form under that name.
It's worth noting that in the context of a parent form, you often can skip one-way or
two-way binding because the parent form will sync the value for you. You can access
its properties by exporting it into a local template variable using ngForm
(ex:
#f="ngForm"
). Then you can pass it where it needs to go on submit.
If you do need to populate initial values into your form, using a one-way binding for
ngModel
tends to be sufficient as long as you use the exported form's value rather
than the domain model's value on submit.
Take a look at an example of using ngModel
within a form:
- import {Component} from '@angular/core';
- import {NgForm} from '@angular/forms';
-
- @Component({
- selector: 'example-app',
- template: `
- <form #f="ngForm" (ngSubmit)="onSubmit(f)" novalidate>
- <input name="first" ngModel required #first="ngModel">
- <input name="last" ngModel>
- <button>Submit</button>
- </form>
-
- <p>First name value: {{ first.value }}</p>
- <p>First name valid: {{ first.valid }}</p>
- <p>Form value: {{ f.value | json }}</p>
- <p>Form valid: {{ f.valid }}</p>
- `,
- })
- export class SimpleFormComp {
- onSubmit(f: NgForm) {
- console.log(f.value); // { first: '', last: '' }
- console.log(f.valid); // false
- }
- }
To see ngModel
examples with different form control types, see:
- Radio buttons:
RadioControlValueAccessor
- Selects:
SelectControlValueAccessor
Methods
Parameters
|
ParametersThere are no parameters. Returns
|
Parameters
Returns
|