Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit 1ef7415

Browse files
Thesoropetebacondarwin
authored andcommitted
docs(ngModel): add section explaining that ngModel watches by reference
The new section explains that changing only a property on an object doesn't trigger re-rendering. Closes #13224 Closes #13518
1 parent 2d44a68 commit 1ef7415

File tree

1 file changed

+16
-0
lines changed

1 file changed

+16
-0
lines changed

src/ng/directive/ngModel.js

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -921,6 +921,22 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
921921
* - {@link ng.directive:select select}
922922
* - {@link ng.directive:textarea textarea}
923923
*
924+
* # Complex Models (objects or collections)
925+
*
926+
* By default, `ngModel` watches the model by reference, not value. This is important to know when
927+
* binding inputs to models that are objects (e.g. `Date`) or collections (e.g. arrays). If only properties of the
928+
* object or collection change, `ngModel` will not be notified and so the input will not be re-rendered.
929+
*
930+
* The model must be assigned an entirely new object or collection before a re-rendering will occur.
931+
*
932+
* Some directives have options that will cause them to use a custom `$watchCollection` on the model expression
933+
* - for example, `ngOptions` will do so when a `track by` clause is included in the comprehension expression or
934+
* if the select is given the `multiple` attribute.
935+
*
936+
* The `$watchCollection()` method only does a shallow comparison, meaning that changing properties deeper than the
937+
* first level of the object (or only changing the properties of an item in the collection if it's an array) will still
938+
* not trigger a re-rendering of the model.
939+
*
924940
* # CSS classes
925941
* The following CSS classes are added and removed on the associated input/select/textarea element
926942
* depending on the validity of the model.

0 commit comments

Comments
 (0)