# `form` (directive in module `ng` )

Improve this doc

## Description

Directive that instantiates `FormController`.

If `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, for this reason angular provides ``ngForm`` alias which behaves identical to `<form>` but allows form nesting.

### CSS classes

- `ng-valid` Is set if the form is valid.
- `ng-invalid` Is set if the form is invalid.
- `ng-pristine` Is set if the form is pristine.
- `ng-dirty` Is set if the form is dirty.

### Submitting a form and preventing 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 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 ngSubmit or ngClick directives. This is because of the following form submission rules coming from the html spec:

- If a form has only one input field then hitting enter in this field triggers form submit (`ngSubmit`)
- if a form has 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`)

## Usage

This directive can be used as custom element, but we aware of IE restrictions.

as element:

    <form
           [name="{string}"]>
    </form>

### Parameters

- `name(optional) – {string=} –`

  Name of the form. If specified, the form controller will be published into related scope, under this name.

## Example

#### Source

#### Demo