NgForm
directive
Creates a top-level FormGroup
instance and binds it to a form to track aggregate form value and validation status.
NgModule
-
FormsModule
Selectors
form:not([ngNoForm]):not([formGroup])
ngForm
ng-form
[ngForm]
Properties
Property | Description |
---|---|
submitted: boolean
|
Read-Only Returns whether the form submission has been triggered. |
form: FormGroup
|
The FormGroup instance created for this form.
|
@Output()ngSubmit: EventEmitter
|
Event emitter for the "ngSubmit" event |
@Input('ngFormOptions')options: { updateOn?: FormHooks; }
|
Tracks options for the updateOn: Sets the default |
formDirective: Form
|
Read-Only The directive instance. |
control: FormGroup
|
Read-Only
The internal |
path: string[]
|
Read-Only Returns an array representing the path to this group. Because this directive always lives at the top level of a form, it is always an empty array. |
controls: { [key: string]: AbstractControl; }
|
Read-Only Returns a map of the controls in this group. |
Inherited from ControlContainer
name: string
formDirective: Form | null
path: string[] | 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
Template variable references
Identifier | Usage |
---|---|
ngForm
|
#myTemplateVar="ngForm"
|
Description
As soon as you import the FormsModule
, this directive becomes active by default on all <form>
tags. You don't need to add a special selector.
You optionally export the directive into a local template variable using ngForm
as the key (ex: #myForm="ngForm"
). This is optional, but useful. Many properties from the underlying FormGroup
instance are duplicated on the directive itself, so a reference to it gives you access to the aggregate value and validity status of the form, as well as user interaction properties like dirty
and touched
.
To register child controls with the form, use NgModel
with a name
attribute. You may use NgModelGroup
to create sub-groups within the form.
If necessary, listen to the directive's ngSubmit
event to be notified when the user has triggered a form submission. The ngSubmit
event emits the original form submission event.
In template driven forms, all <form>
tags are automatically tagged as NgForm
. To import the FormsModule
but skip its usage in some forms, for example, to use native HTML5 validation, add the ngNoForm
and the <form>
tags won't create an NgForm
directive. In reactive forms, using ngNoForm
is unnecessary because the <form>
tags are inert. In that case, you would refrain from using the formGroup
directive.
Migrating from deprecated ngForm selector
Support for using ngForm
element selector has been deprecated in Angular v6 and will be removed in Angular v9.
This has been deprecated to keep selectors consistent with other core Angular selectors, as element selectors are typically written in kebab-case.
Now deprecated:
<ngForm #myForm="ngForm">
After:
<ng-form #myForm="ngForm">
Listening for form submission
The following example shows how to capture the form values from the "ngSubmit" event.
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
}
}
Setting the update options
The following example shows you how to change the "updateOn" option from its default using ngFormOptions.
<form [ngFormOptions]="{updateOn: 'blur'}">
<input name="one" ngModel> <!-- this ngModel will update on blur -->
</form>
Methods
ngAfterViewInit() |
---|
Lifecycle method called after the view is initialized. For internal use only. |
ngAfterViewInit()ParametersThere are no parameters.
|
addControl() | |||
---|---|---|---|
Method that sets up the control directive in this group, re-calculates its value and validity, and adds the instance to the internal list of directives. | |||
addControl(dir: NgModel): voidParameters
Returns
|
getControl() | |||
---|---|---|---|
Retrieves the FormControl instance from the provided NgModel directive.
| |||
getControl(dir: NgModel): FormControlParameters
Returns
|
removeControl() | |||
---|---|---|---|
Removes the NgModel instance from the internal list of directives
| |||
removeControl(dir: NgModel): voidParameters
Returns
|
addFormGroup() | |||
---|---|---|---|
Adds a new NgModelGroup directive instance to the form.
| |||
addFormGroup(dir: NgModelGroup): voidParameters
Returns
|
removeFormGroup() | |||
---|---|---|---|
Removes the NgModelGroup directive instance from the form.
| |||
removeFormGroup(dir: NgModelGroup): voidParameters
Returns
|
getFormGroup() | |||
---|---|---|---|
Retrieves the FormGroup for a provided NgModelGroup directive instance
| |||
getFormGroup(dir: NgModelGroup): FormGroupParameters
Returns
|
updateModel() | ||||||
---|---|---|---|---|---|---|
Sets the new value for the provided NgControl directive.
| ||||||
updateModel(dir: NgControl, value: any): voidParameters
Returns
|
setValue() | |||
---|---|---|---|
Sets the value for this FormGroup .
| |||
setValue(value: { [key: string]: any; }): voidParameters
Returns
|
onSubmit() | |||
---|---|---|---|
Method called when the "submit" event is triggered on the form. Triggers the ngSubmit emitter to emit the "submit" event as its payload.
| |||
onSubmit($event: Event): booleanParameters
Returns
|
onReset() |
---|
Method called when the "reset" event is triggered on the form. |
onReset(): voidParametersThere are no parameters. Returns
|
resetForm() | |||
---|---|---|---|
Resets the form to an initial value and resets its submitted status. | |||
resetForm(value: any = undefined): voidParameters
Returns
|
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.
https://v8.angular.io/api/forms/NgForm