ngRepeat

Overview

The ngRepeat directive instantiates a template once per item from a collection. Each template instance gets its own scope, where the given loop variable is set to the current collection item, and $index is set to the item index or key.

Special properties are exposed on the local scope of each template instance, including:

Iterating over object properties

It is possible to get ngRepeat to iterate over the properties of an object using the following syntax:

<div ng-repeat="(key, value) in myObj"> ... </div>

However, there are a few limitations compared to array iteration:

• The JavaScript specification does not define the order of keys returned for an object, so AngularJS relies on the order returned by the browser when running for key in myObj. Browsers generally follow the strategy of providing keys in the order in which they were defined, although there are exceptions when keys are deleted and reinstated. See the MDN page on delete for more info.

• ngRepeat will silently ignore object keys starting with $, because it's a prefix used by AngularJS for public ($) and private ($$) properties.

• The built-in filters orderBy and filter do not work with objects, and will throw an error if used with one.

If you are hitting any of these limitations, the recommended workaround is to convert your object into an array that is sorted into the order that you prefer before providing it to ngRepeat. You could do this with a filter such as toArrayFilter or implement a $watch on the object yourself.

Tracking and Duplicates

ngRepeat uses $watchCollection to detect changes in the collection. When a change happens, ngRepeat then makes the corresponding changes to the DOM:

• When an item is added, a new instance of the template is added to the DOM.
• When an item is removed, its template instance is removed from the DOM.
• When items are reordered, their respective templates are reordered in the DOM.

To minimize creation of DOM elements, ngRepeat uses a function to "keep track" of all items in the collection and their corresponding DOM elements. For example, if an item is added to the collection, ngRepeat will know that all other items already have DOM elements, and will not re-render them.

All different types of tracking functions, their syntax, and their support for duplicate items in collections can be found in the ngRepeat expression description.

Effects of DOM Element re-use

When DOM elements are re-used, ngRepeat updates the scope for the element, which will automatically update any active bindings on the template. However, other functionality will not be updated, because the element is not re-created:

• Directives are not re-compiled
• one-time expressions on the repeated template are not updated if they have stabilized.

The above affects all kinds of element re-use due to tracking, but may be especially visible when tracking by $index due to the way ngRepeat re-uses elements.

The following example shows the effects of different actions with tracking:

angular.module('ngRepeat', ['ngAnimate']).controller('repeatController', function($scope) {
  var friends = [
    {name:'John', age:25},
    {name:'Mary', age:40},
    {name:'Peter', age:85}
  ];

  $scope.removeFirst = function() {
    $scope.friends.shift();
  };

  $scope.updateAge = function() {
    $scope.friends.forEach(function(el) {
      el.age = el.age + 5;
    });
  };

  $scope.copy = function() {
    $scope.friends = angular.copy($scope.friends);
  };

  $scope.reset = function() {
    $scope.friends = angular.copy(friends);
  };

  $scope.reset();
});

<div ng-controller="repeatController">
  <ol>
    <li>When you click "Update Age", only the first list updates the age, because all others have
    a one-time binding on the age property. If you then click "Copy", the current friend list
    is copied, and now the second list updates the age, because the identity of the collection items
    has changed and the list must be re-rendered. The 3rd and 4th list stay the same, because all the
    items are already known according to their tracking functions.
    </li>
    <li>When you click "Remove First", the 4th list has the wrong age on both remaining items. This is
    due to tracking by $index: when the first collection item is removed, ngRepeat reuses the first
    DOM element for the new first collection item, and so on. Since the age property is one-time
    bound, the value remains from the collection item which was previously at this index.
    </li>
  </ol>

  <button ng-click="removeFirst()">Remove First</button>
  <button ng-click="updateAge()">Update Age</button>
  <button ng-click="copy()">Copy</button>
  <br><button ng-click="reset()">Reset List</button>
  <br>
  <code>track by $id(friend)</code> (default):
  <ul class="example-animate-container">
    <li class="animate-repeat" ng-repeat="friend in friends">
      {{friend.name}} is {{friend.age}} years old.
    </li>
  </ul>
  <code>track by $id(friend)</code> (default), with age one-time binding:
  <ul class="example-animate-container">
    <li class="animate-repeat" ng-repeat="friend in friends">
      {{friend.name}} is {{::friend.age}} years old.
    </li>
  </ul>
  <code>track by friend.name</code>, with age one-time binding:
  <ul class="example-animate-container">
    <li class="animate-repeat" ng-repeat="friend in friends track by friend.name">
      {{friend.name}}  is {{::friend.age}} years old.
    </li>
  </ul>
  <code>track by $index</code>, with age one-time binding:
  <ul class="example-animate-container">
    <li class="animate-repeat" ng-repeat="friend in friends track by $index">
      {{friend.name}} is {{::friend.age}} years old.
    </li>
  </ul>
</div>

.example-animate-container {
  background:white;
  border:1px solid black;
  list-style:none;
  margin:0;
  padding:0 10px;
}

.animate-repeat {
  line-height:30px;
  list-style:none;
  box-sizing:border-box;
}

.animate-repeat.ng-move,
.animate-repeat.ng-enter,
.animate-repeat.ng-leave {
  transition:all linear 0.5s;
}

.animate-repeat.ng-leave.ng-leave-active,
.animate-repeat.ng-move,
.animate-repeat.ng-enter {
  opacity:0;
  max-height:0;
}

.animate-repeat.ng-leave,
.animate-repeat.ng-move.ng-move-active,
.animate-repeat.ng-enter.ng-enter-active {
  opacity:1;
  max-height:30px;
}

Special repeat start and end points

To repeat a series of elements instead of just one parent element, ngRepeat (as well as other ng directives) supports extending the range of the repeater by defining explicit start and end points by using ng-repeat-start and ng-repeat-end respectively. The ng-repeat-start directive works the same as ng-repeat, but will repeat all the HTML code (including the tag it's defined on) up to and including the ending HTML tag where ng-repeat-end is placed.

The example below makes use of this feature:

<header ng-repeat-start="item in items">
  Header {{ item }}
</header>
<div class="body">
  Body {{ item }}
</div>
<footer ng-repeat-end>
  Footer {{ item }}
</footer>

And with an input of ['A','B'] for the items variable in the example above, the output will evaluate to:

<header>
  Header A
</header>
<div class="body">
  Body A
</div>
<footer>
  Footer A
</footer>
<header>
  Header B
</header>
<div class="body">
  Body B
</div>
<footer>
  Footer B
</footer>

The custom start and end points for ngRepeat also support all other HTML directive syntax flavors provided in AngularJS (such as data-ng-repeat-start, x-ng-repeat-start and ng:repeat-start).