View Source   Improve this doc

collection-repeat

See the Pen by Ionic (@ionic) on CodePen.

collection-repeat allows an app to show huge lists of items much more performantly than ng-repeat.

It renders into the DOM only as many items as are currently visible.

This means that on a phone screen that can fit eight items, only the eight items matching the current scroll position will be rendered.

The Basics:

  • The data given to collection-repeat must be an array.
  • If the item-height and item-width attributes are not supplied, it will be assumed that every item in the list has the same dimensions as the first item.
  • Don’t use angular one-time binding (::) with collection-repeat. The scope of each item is assigned new data and re-digested as you scroll. Bindings need to update, and one-time bindings won’t.

Performance Tips:

  • The iOS webview has a performance bottleneck when switching out <img src> attributes. To increase performance of images on iOS, cache your images in advance and, if possible, lower the number of unique images. We’re working on a solution.

Usage

Basic Item List (codepen)

<ion-content>
  <ion-item collection-repeat="item in items">
    {{item}}
  </ion-item>
</ion-content>

Grid of Images (codepen)

<ion-content>
  <img collection-repeat="photo in photos"
    item-width="33%"
    item-height="200px"
    ng-src="{{photo.url}}">
</ion-content>

Horizontal Scroller, Dynamic Item Width (codepen)

<ion-content>
  <h2>Available Kittens:</h2>
  <ion-scroll direction="x" class="available-scroller">
    <div class="photo" collection-repeat="photo in main.photos"
       item-height="250" item-width="photo.width + 30">
       <img ng-src="{{photo.src}}">
    </div>
  </ion-scroll>
</ion-content>

API

Attr Type Details
collection-repeat expression

The expression indicating how to enumerate a collection, of the format 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 or album in artist.albums | orderBy:'name'.
item-width
(optional)
 expression

The width of the repeated element. The expression must return a number (pixels) or a percentage. Defaults to the width of the first item in the list. (previously named collection-item-width)
item-height
(optional)
 expression

The height of the repeated element. The expression must return a number (pixels) or a percentage. Defaults to the height of the first item in the list. (previously named collection-item-height)
item-render-buffer
(optional)
 number

The number of items to load before and after the visible items in the list. Default 3. Tip: set this higher if you have lots of images to preload, but don't set it too high or you'll see performance loss.
force-refresh-images
(optional)
 boolean

Force images to refresh as you scroll. This fixes a problem where, when an element is interchanged as scrolling, its image will still have the old src while the new src loads. Setting this to true comes with a small performance loss.