Directive that instantiates FormController.

If the name attribute is specified, the form controller is published onto the current scope under this name.

Alias: `ngForm`

In Angular, forms can be nested. This means that the outer form is valid when all of the child forms are valid as well. However, browsers do not allow nesting of <form> elements, so Angular provides the ngForm directive, which behaves identically to form but can be nested. Nested forms can be useful, for example, if the validity of a sub-group of controls needs to be determined.

CSS classes

ng-valid is set if the form is valid.
ng-invalid is set if the form is invalid.
ng-pending is set if the form is pending.
ng-pristine is set if the form is pristine.
ng-dirty is set if the form is dirty.
ng-submitted is set if the form was submitted.

Keep in mind that ngAnimate can detect each of these classes when added and removed.

Submitting a form and preventing the default action

Since the role of forms in client-side Angular applications is different than in classical roundtrip apps, it is desirable for the browser not to translate the form submission into a full page reload that sends the data to the server. Instead some javascript logic should be triggered to handle the form submission in an application-specific way.

For this reason, Angular prevents the default action (form submission to the server) unless the <form> element has an action attribute specified.

You can use one of the following two ways to specify what javascript method should be called when a form is submitted:

ngSubmit directive on the form element
ngClick directive on the first button or input field of type submit (input[type=submit])

To prevent double execution of the handler, use only one of the ngSubmit or ngClick directives. This is because of the following form submission rules in the HTML specification:

If a form has only one input field then hitting enter in this field triggers form submit (ngSubmit)
if a form has 2+ input fields and no buttons or input[type=submit] then hitting enter doesn't trigger submit
if a form has one or more input fields and one or more buttons or input[type=submit] then hitting enter in any of the input fields will trigger the click handler on the first button or input[type=submit] (ngClick) and a submit handler on the enclosing form (ngSubmit)

Any pending ngModelOptions changes will take place immediately when an enclosing form is submitted. Note that ngClick events will occur before the model is updated. Use ngSubmit to have access to the updated model.

Animation Hooks

Animations in ngForm are triggered when any of the associated CSS classes are added and removed. These classes are: .ng-pristine, .ng-dirty, .ng-invalid and .ng-valid as well as any other validations that are performed within the form. Animations in ngForm are similar to how they work in ngClass and animations can be hooked into using CSS transitions, keyframes as well as JS animations.

The following example shows a simple way to utilize CSS transitions to style a form element that has been rendered as invalid after it has been validated:

//be sure to include ngAnimate as a module to hook into more
//advanced animations
.my-form {
  transition:0.5s linear all;
  background: white;
}
.my-form.ng-invalid {
  background: red;
  color:white;
}

Directive Info

This directive executes at priority level 0.

Usage

as element:
```
<form
  [name="string"]>
...
</form>
```

Arguments

Param	Type	Details
name (optional)	string	Name of the form. If specified, the form controller will be published into related scope, under this name.

Example

Edit in Plunker

<script>
  angular.module('formExample', [])
    .controller('FormController', ['$scope', function($scope) {
      $scope.userType = 'guest';
    }]);
</script>
<style>
 .my-form {
   transition:all linear 0.5s;
   background: transparent;
 }
 .my-form.ng-invalid {
   background: red;
 }
</style>
<form name="myForm" ng-controller="FormController" class="my-form">
  userType: <input name="input" ng-model="userType" required>
  <span class="error" ng-show="myForm.input.$error.required">Required!</span><br>
  <code>userType = {{userType}}</code><br>
  <code>myForm.input.$valid = {{myForm.input.$valid}}</code><br>
  <code>myForm.input.$error = {{myForm.input.$error}}</code><br>
  <code>myForm.$valid = {{myForm.$valid}}</code><br>
  <code>myForm.$error.required = {{!!myForm.$error.required}}</code><br>
 </form>

it('should initialize to model', function() {
  var userType = element(by.binding('userType'));
  var valid = element(by.binding('myForm.input.$valid'));

  expect(userType.getText()).toContain('guest');
  expect(valid.getText()).toContain('true');
});

it('should be invalid if empty', function() {
  var userType = element(by.binding('userType'));
  var valid = element(by.binding('myForm.input.$valid'));
  var userInput = element(by.model('userType'));

  userInput.clear();
  userInput.sendKeys('');

  expect(userType.getText()).toEqual('userType =');
  expect(valid.getText()).toContain('false');
});

Alias: ngForm