NgForm
Creates a top-level FormGroup
instance and binds it to a form
to track aggregate form value and validation status.
Exported from
Selectors
Properties
Property | Description |
---|---|
submitted: boolean
|
Read-Only
Returns whether the form submission has been triggered. |
form: FormGroup
|
The |
@Output()
|
Event emitter for the "ngSubmit" event |
@Input('ngFormOptions')
|
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
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
-
validator: ValidatorFn | null
-
asyncValidator: AsyncValidatorFn | 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.
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>
Native DOM validation UI
In order to prevent the native DOM form validation UI from interfering with Angular's form
validation, Angular automatically adds the novalidate
attribute on any <form>
whenever
FormModule
or ReactiveFormModule
are imported into the application.
If you want to explicitly enable native DOM validation UI with Angular forms, you can add the
ngNativeValidate
attribute to the <form>
element:
<form ngNativeValidate>
...
</form>
Methods
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. |
getControl() | |||
---|---|---|---|
Retrieves the |
|||
Parameters
Returns |
removeControl() |
---|
Removes the |
addFormGroup() | |||
---|---|---|---|
Adds a new |
|||
Parameters
Returns
|
removeFormGroup() | |||
---|---|---|---|
Removes the |
|||
Parameters
Returns
|
getFormGroup() | |||
---|---|---|---|
Retrieves the |
|||
Parameters
Returns |
updateModel() |
---|
Sets the new value for the provided |
setValue() |
---|
Sets the value for this |
onSubmit() |
---|
Method called when the "submit" event is triggered on the form.
Triggers the |
onReset() |
---|
Method called when the "reset" event is triggered on the form. |
ParametersThere are no parameters. Returns
|
resetForm() |
---|
Resets the form to an initial value and resets its submitted status. |