Improve this Doc View Source ngModel

The ngModel directive binds an input,select, textarea (or custom form control) to a property on the scope using NgModelController, which is created and exposed by this directive.

ngModel is responsible for:

• Binding the view into the model, which other directives such as input, textarea or select require.
• Providing validation behavior (i.e. required, number, email, url).
• Keeping the state of the control (valid/invalid, dirty/pristine, touched/untouched, validation errors).
• Setting related css classes on the element (ng-valid, ng-invalid, ng-dirty, ng-pristine, ng-touched, ng-untouched, ng-empty, ng-not-empty) including animations.
• Registering the control with its parent form.

Note: ngModel will try to bind to the property given by evaluating the expression on the current scope. If the property doesn't already exist on this scope, it will be created implicitly and added to the scope.

For best practices on using ngModel, see:

• Understanding Scopes

For basic examples, how to use ngModel, see:

• input
  • text
  • checkbox
  • radio
  • number
  • email
  • url
  • date
  • datetime-local
  • time
  • month
  • week
• select
• textarea

Complex Models (objects or collections)

By default, ngModel watches the model by reference, not value. This is important to know when binding inputs to models that are objects (e.g. Date) or collections (e.g. arrays). If only properties of the object or collection change, ngModel will not be notified and so the input will not be re-rendered.

The model must be assigned an entirely new object or collection before a re-rendering will occur.

Some directives have options that will cause them to use a custom $watchCollection on the model expression

• for example, ngOptions will do so when a track by clause is included in the comprehension expression or if the select is given the multiple attribute.

The $watchCollection() method only does a shallow comparison, meaning that changing properties deeper than the first level of the object (or only changing the properties of an item in the collection if it's an array) will still not trigger a re-rendering of the model.

CSS classes

The following CSS classes are added and removed on the associated input/select/textarea element depending on the validity of the model.

• ng-valid: the model is valid
• ng-invalid: the model is invalid
• ng-valid-[key]: for each valid key added by $setValidity
• ng-invalid-[key]: for each invalid key added by $setValidity
• ng-pristine: the control hasn't been interacted with yet
• ng-dirty: the control has been interacted with
• ng-touched: the control has been blurred
• ng-untouched: the control hasn't been blurred
• ng-pending: any $asyncValidators are unfulfilled
• ng-empty: the view does not contain a value or the value is deemed "empty", as defined by the ngModel.NgModelController method
• ng-not-empty: the view contains a non-empty value

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

Animation Hooks

Animations within models are triggered when any of the associated CSS classes are added and removed on the input element which is attached to the model. These classes include: .ng-pristine, .ng-dirty, .ng-invalid and .ng-valid as well as any other validations that are performed on the model itself. The animations that are triggered within ngModel 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 an input 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-input {
  transition:0.5s linear all;
  background: white;
}
.my-input.ng-invalid {
  background: red;
  color:white;
}