ons-lazy-repeat

Using this component a list with millions of items can be rendered without a drop in performance. It does that by “lazily” loading elements into the DOM when they come into view and removing items from the DOM when they are not visible.

Using this component a list with millions of items can be rendered without a drop in performance. It does that by “lazily” loading elements into the DOM when they come into view and removing items from the DOM when they are not visible.

Tutorial

Infinite lists

In mobile apps it is often necessary to display very large lists of items. One problem with this is that a large number of DOM elements must be created which can affect performance.

For AngularJS, Onsen UI provides a directive called ons-lazy-repeat which helps rendering large numbers of items. It will automatically calculate which elements are visible and only render those. When the user scrolls it will remove items that are outside the screen and add elements that become visible dynamically.

Using the element

The element is attached as a children of an <ons-list> item:

<ons-list ng-controller="ListController as list">
  <ons-list-item ons-lazy-repeat="list.delegate">
    {{ item }}
  </ons-list-item>
</ons-list>

The items will be rendered in the same position as the element is defined.

The delegate object

To use the element an object called the delegate must be defined. This object contains information about how to create a new item and how many items are in the list.

ons.bootstrap()
 .controller('ListController', function() {

    this.delegate = {
      configureItemScope: function(index, itemScope) {
        // Prepare the item scope.
      },

      countItems: function() {
        // Return the number of items here.
      },

      calculateItemHeight: function(index) {
        // Return the height of the item at position `index`.
      },

      destroyItem: function(index, element) {
        // Remove event listeners, etc. here to avoid memory leaks.
      }
    };
 });

In order to refresh the list when the data has changed, refresh method is exposed in the delegate object: this.delegate.refresh().

Calculating the height

<ons-lazy-repeat> can dynamically calculate the height of every item once they are rendered, but in order to know how many items it should render beforehand we must provide a hint. By default, <ons-lazy-repeat> pre-renders the very first item and takes its height to do the calculations.

However, it is also possible to pass an optional calculateItemHeight function in the delegate object that gets the element index and returns its approximate height. This can enhance the calculations and allow better scrolling.

list.delegate = {
  ...
  calculateItemHeight: function(index) {
    return heights[index];
  },
  ...
}

See also

Attributes

Name Type Description
ons-lazy-repeat Expression A delegate object, can be either an object attached to the scope (when using AngularJS) or a normal JavaScript variable. Optional. Works only during initialization.

Properties

Name Description
delegate Specify a delegate object to load and unload item elements.
delegate.createItemContent

This function should return a HTMLElement. To help rendering the element, the current index and a template is supplied as arguments. The template is the initial content of the <ons-lazy-repeat> element.

delegate.countItems Should return the number of items in the list.
delegate.calculateItemHeight

Should return the height of an item. The index is provided as an argument. This is important when rendering lists where the items have different height. The function is optional and if it isn’t present the height of the first item will be automatically calculated and used for all other items.

delegate.destroyItem

This function is used called when an item is removed from the DOM. The index and DOM element is provided as arguments. The function is optional but may be important in order to avoid memory leaks.

delegate.configureItemScope Function which recieves an index and the scope for the item. Can be used to configure values in the item scope.

Methods

Signature Description
refresh() Refresh the list. Use this method when the data has changed.
refresh()

Refresh the list. Use this method when the data has changed.

Discussion

Need Help?

If you have any questions, use our Community Forum or talk to us via Gitter chat. The Onsen UI team and your peers in the community will work together to help solve your issues.

For bug reports and feature requests use our GitHub Issues page.