Improve this Doc View Source ngRepeat

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:

Creating aliases for these properties is possible with ngInit. This may be useful when, for instance, nesting ngRepeats.

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>

You need to be aware that the JavaScript specification does not define what order it will return the keys for an object. In order to have a guaranteed deterministic order for the keys, Angular versions up to and including 1.3 sort the keys alphabetically.

If this is not desired, 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.

In version 1.4 we will remove the sorting, since it seems that 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.

Tracking and Duplicates

When the contents of the collection change, ngRepeat 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.

By default, ngRepeat does not allow duplicate items in arrays. This is because when there are duplicates, it is not possible to maintain a one-to-one mapping between collection items and DOM elements.

If you do need to repeat duplicate items, you can substitute the default tracking behavior with your own using the track by expression.

For example, you may track items by the index of each item in the collection, using the special scope property $index:

<div ng-repeat="n in [42, 42, 43, 43] track by $index">
  {{n}}
</div>

You may use arbitrary expressions in track by, including references to custom functions on the scope:

<div ng-repeat="n in [42, 42, 43, 43] track by myTrackingFunction(n)">
  {{n}}
</div>

If you are working with objects that have an identifier property, you can track by the identifier instead of the whole object. Should you reload your data later, ngRepeat will not have to rebuild the DOM elements for items it has already rendered, even if the JavaScript objects in the collection have been substituted for new ones:

<div ng-repeat="model in collection track by model.id">
  {{model.name}}
</div>

When no track by expression is provided, it is equivalent to tracking by the built-in $id function, which tracks items by their identity:

<div ng-repeat="obj in collection track by $id(obj)">
  {{obj.prop}}
</div>

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).