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.

Onsen UI provides an element 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>
  <ons-lazy-repeat id="infinite-list">
    An optional template can be defined here.
  </ons-lazy-repeat>
</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.

var list = document.getElementById('infinite-list');

list.delegate = {
  createItemContent: function(index, template) {
    // Return a DOM element here.
  },

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

  calculateItemHeight: function(index) {
    // Optional: return the height of the item at position `index`.
    // This can enhance calculations and allow better scrolling.
  },

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

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];
  },
  ...
}