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

NgFormlink

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

Creates a top-level FormGroup instance and binds it to a form\nto track aggregate form value and validation status.

\n\n

See more...

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

NgModulelink

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

Selectorslink

\n \n
    \n
  • form:not([ngNoForm]):not([formGroup])
    • \n \n
  • ng-form
    • \n \n
  • [ngForm]
    • \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 submitted: boolean\n Read-Only\n \n

Returns whether the form submission has been triggered.

\n\n \n
\n \n form: FormGroup\n \n \n

The FormGroup instance created for this form.

\n\n \n
\n \n @Output()
ngSubmit: EventEmitter\n 		\n \n

Event emitter for the \"ngSubmit\" event

\n\n \n
\n \n @Input('ngFormOptions')
options: {\n updateOn?: FormHooks;\n}\n 		\n \n

Tracks options for the NgForm instance.

\n\n

updateOn: Sets the default updateOn value for all child NgModels below it\nunless explicitly set by a child NgModel using ngModelOptions). Defaults to 'change'.\nPossible values: 'change' | 'blur' | 'submit'.

\n\n
\n \n formDirective: Form\n Read-Only\n \n

The directive instance.

\n\n \n
\n \n control: FormGroup\n Read-Only\n \n

The internal FormGroup instance.

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

Returns an array representing the path to this group. Because this directive\nalways lives at the top level of a form, it is always an empty array.

\n\n \n
\n \n controls: {\n [key: string]: AbstractControl;\n}\n Read-Only\n \n

Returns a map of the controls in this group.

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

Inherited from ControlContainerlink

\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
ngForm#myTemplateVar=\"ngForm\"
\n
\n\n\n\n \n
\n

Descriptionlink

\n

As soon as you import the FormsModule, this directive becomes active by default on\nall <form> tags. You don't need to add a special selector.

\n

You optionally export the directive into a local template variable using ngForm as the key\n(ex: #myForm=\"ngForm\"). This is optional, but useful. Many properties from the underlying\nFormGroup instance are duplicated on the directive itself, so a reference to it\ngives you access to the aggregate value and validity status of the form, as well as\nuser interaction properties like dirty and touched.

\n

To register child controls with the form, use NgModel with a name\nattribute. You may use NgModelGroup to create sub-groups within the form.

\n

If necessary, listen to the directive's ngSubmit event to be notified when the user has\ntriggered a form submission. The ngSubmit event emits the original form\nsubmission event.

\n

In template driven forms, all <form> tags are automatically tagged as NgForm.\nTo import the FormsModule but skip its usage in some forms,\nfor example, to use native HTML5 validation, add the ngNoForm and the <form>\ntags won't create an NgForm directive. In reactive forms, using ngNoForm is\nunnecessary because the <form> tags are inert. In that case, you would\nrefrain from using the formGroup directive.

\n\n

Listening for form submissionlink

\n

The following example shows how to capture the form values from the \"ngSubmit\" event.

\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

Setting the update optionslink

\n

The following example shows you how to change the \"updateOn\" option from its default using\nngFormOptions.

\n\n<form [ngFormOptions]=\"{updateOn: 'blur'}\">\n <input name=\"one\" ngModel> <!-- this ngModel will update on blur -->\n</form>\n\n

Native DOM validation UIlink

\n

In order to prevent the native DOM form validation UI from interfering with Angular's form\nvalidation, Angular automatically adds the novalidate attribute on any <form> whenever\nFormModule or ReactiveFormModule are imported into the application.\nIf you want to explicitly enable native DOM validation UI with Angular forms, you can add the\nngNativeValidate attribute to the <form> element:

\n\n<form ngNativeValidate>\n ...\n</form>\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 addControl()\n \n link

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

Method that sets up the control directive in this group, re-calculates its value\nand validity, and adds the instance to the internal list of directives.

\n\n
\n
\n \n\n addControl(dir: NgModel): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgModel\n

The NgModel directive instance.

\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 \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n getControl()\n \n link

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

Retrieves the FormControl instance from the provided NgModel directive.

\n\n
\n
\n \n\n getControl(dir: NgModel): FormControl\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgModel\n

The NgModel directive instance.

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

FormControl

\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 removeControl()\n \n link

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

Removes the NgModel instance from the internal list of directives

\n\n
\n
\n \n\n removeControl(dir: NgModel): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgModel\n

The NgModel directive instance.

\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 \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n addFormGroup()\n \n link

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

Adds a new NgModelGroup directive instance to the form.

\n\n
\n
\n \n\n addFormGroup(dir: NgModelGroup): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgModelGroup\n

The NgModelGroup directive instance.

\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 \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n removeFormGroup()\n \n link

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

Removes the NgModelGroup directive instance from the form.

\n\n
\n
\n \n\n removeFormGroup(dir: NgModelGroup): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgModelGroup\n

The NgModelGroup directive instance.

\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 \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n getFormGroup()\n \n link

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

Retrieves the FormGroup for a provided NgModelGroup directive instance

\n\n
\n
\n \n\n getFormGroup(dir: NgModelGroup): FormGroup\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgModelGroup\n

The NgModelGroup directive instance.

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

FormGroup

\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 updateModel()\n \n link

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

Sets the new value for the provided NgControl directive.

\n\n
\n
\n \n\n updateModel(dir: NgControl, value: any): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n dir\n NgControl\n

The NgControl directive instance.

\n\n
\n \n value\n any\n

The new value for the directive's control.

\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 \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n setValue()\n \n link

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

Sets the value for this FormGroup.

\n\n
\n
\n \n\n setValue(value: { [key: string]: any; }): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n value\n object\n

The new value

\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 \n \n \n \n \n \n \n\n \n\n \n \n
\n
\n

\n onSubmit()\n \n link

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

Method called when the \"submit\" event is triggered on the form.\nTriggers the ngSubmit emitter to emit the \"submit\" event as its payload.

\n\n
\n
\n \n\n onSubmit($event: Event): boolean\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n $event\n Event\n

The \"submit\" event object

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

boolean

\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 onReset()\n \n link

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

Method called when the \"reset\" event is triggered on the form.

\n\n
\n
\n \n\n onReset(): void\n\n \n\n
Parameters
\n

There are no parameters.

\n\n \n
Returns
\n

void

\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 resetForm()\n \n link

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

Resets the form to an initial value and resets its submitted status.

\n\n
\n
\n \n\n resetForm(value: any = undefined): void\n\n \n\n
Parameters
\n \n \n \n \n \n \n \n \n \n
\n \n value\n any\n

The new value for the form.

\n

Optional. Default is undefined.

\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\n\n
\n

Inherited from AbstractControlDirectivelink

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