Improve this doc View Source

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:

Variable | Type | Details
--- | --- | ---
`$index` | number | iterator offset of the repeated element (0..length-1)
`$first` | boolean | true if the repeated element is first in the iterator.
`$middle` | boolean | true if the repeated element is between the first and last in the iterator.
`$last` | boolean | true if the repeated element is last in the iterator.
`$even` | boolean | true if the iterator position `$index` is even (otherwise false).
`$odd` | boolean | true if the iterator position `$index` is odd (otherwise false).

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

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

## Directive Info

- This directive creates new scope.
- This directive executes at priority level 1000.

## Usage

- as attribute:

      <ANY
        ng-repeat="">
      ...
      </ANY>

## Animations

.enter - when a new item is added to the list or when an item is revealed after a filter

.leave - when an item is removed from the list or when an item is filtered out

.move - when an adjacent item is filtered out causing a reorder or when the item contents are reordered

Click here to learn more about the steps involved in the animation.

### Arguments

Param | Type | Details
--- | --- | ---
ngRepeat | repeat_expression | The expression indicating how to enumerate a collection. These formats are currently supported: `variable in expression` – where variable is the user defined loop variable and `expression` is a scope expression giving the collection to enumerate. For example: `album in artist.albums`. `(key, value) in expression` – where `key` and `value` can be any user defined identifiers, and `expression` is the scope expression giving the collection to enumerate. For example: `(name, age) in {'adam':10, 'amalie':12}`. `variable in expression track by tracking_expression` – You can also provide an optional tracking function which can be used to associate the objects in the collection with the DOM elements. If no tracking function is specified the ng-repeat associates elements by identity in the collection. It is an error to have more than one tracking function to resolve to the same key. (This would mean that two distinct objects are mapped to the same DOM element, which is not possible.) Filters should be applied to the expression, before specifying a tracking expression. For example: `item in items` is equivalent to `item in items track by $id(item)`. This implies that the DOM elements will be associated by item identity in the array. For example: `item in items track by $id(item)`. A built in `$id()` function can be used to assign a unique `$$hashKey` property to each item in the array. This property is then used as a key to associated DOM elements with the corresponding item in the array by identity. Moving the same object in array would move the DOM element in the same way in the DOM. For example: `item in items track by item.id` is a typical pattern when the items come from the database. In this case the object identity does not matter. Two objects are considered equivalent as long as their `id` property is same. For example: `item in items | filter:searchText track by item.id` is a pattern that might be used to apply a filter to items in conjunction with a tracking expression.

## Example

This example initializes the scope to a list of names and then uses `ngRepeat` to display every person:

Edit in Plunker

    <div ng-init="friends = [
      {name:'John', age:25, gender:'boy'},
      {name:'Jessie', age:30, gender:'girl'},
      {name:'Johanna', age:28, gender:'girl'},
      {name:'Joy', age:15, gender:'girl'},
      {name:'Mary', age:28, gender:'girl'},
      {name:'Peter', age:95, gender:'boy'},
      {name:'Sebastian', age:50, gender:'boy'},
      {name:'Erika', age:27, gender:'girl'},
      {name:'Patrick', age:40, gender:'boy'},
      {name:'Samantha', age:60, gender:'girl'}
    ]">
      I have {{friends.length}} friends. They are:
      <input type="search" ng-model="q" placeholder="filter friends..." />
      <ul class="example-animate-container">
        <li class="animate-repeat" ng-repeat="friend in friends | filter:q">
          [{{$index + 1}}] {{friend.name}} who 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:40px;
      list-style:none;
      box-sizing:border-box;
    }

    .animate-repeat.ng-move,
    .animate-repeat.ng-enter,
    .animate-repeat.ng-leave {
      -webkit-transition:all linear 0.5s;
      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:40px;
    }

    var friends = element.all(by.repeater('friend in friends'));

    it('should render initial data set', function() {
      expect(friends.count()).toBe(10);
      expect(friends.get(0).getText()).toEqual('[1] John who is 25 years old.');
      expect(friends.get(1).getText()).toEqual('[2] Jessie who is 30 years old.');
      expect(friends.last().getText()).toEqual('[10] Samantha who is 60 years old.');
      expect(element(by.binding('friends.length')).getText())
          .toMatch("I have 10 friends. They are:");
    });

     it('should update repeater when filter predicate changes', function() {
       expect(friends.count()).toBe(10);

       element(by.model('q')).sendKeys('ma');

       expect(friends.count()).toBe(2);
       expect(friends.get(0).getText()).toEqual('[1] Mary who is 28 years old.');
       expect(friends.last().getText()).toEqual('[2] Samantha who is 60 years old.');
     });