Documentation

infiniteScroll (directive in module infinite-scroll)

Description

infiniteScroll allows you to specify behavior when the bottom of an element nears the bottom of the browser window.

Usage

<ANY infinite-scroll='{expression}'
     [infinite-scroll-distance='{number}']
     [infinite-scroll-disabled='{boolean}']
     [infinite-scroll-immediate-check='{boolean}']
     [infinite-scroll-listen-for-event='{string}']
     [infinite-scroll-container='{HTMLElement | [] | string}']
     [infinite-scroll-use-document-bottom='{boolean}']
     [infinite-scroll-parent]>
</ANY>

Parameters

• infinite-scroll - {expression} - Expression to evaluate (usually a function call) when the bottom of the element approaches the bottom of the browser window.
• infinite-scroll-distance (optional) - {number} - A number representing how close the bottom of the element must be to the bottom of the browser window before the expression specified by infinite-scroll is triggered. Measured in multiples of the window height; for example, if the browser window is 1000 pixels tall and infinite-scroll-distance is set to 2, the infinite scroll expression will be evaluated when the bottom of the element is within 2000 pixels of the bottom of the browser window. Defaults to 0 (e.g. the expression will be evaluated when the bottom of the element crosses the bottom of the browser window).
• infinite-scroll-disabled (optional) - {boolean} - A boolean expression that, when true, indicates that the infininite scroll expression should not be evaluated even if all other conditions are met. This is usually used to throttle or pause the infinite scroll, for example when data is loading via Ajax. If a scroll event triggers the directive but this attribute prevents the expression evaluation, the event will be handled instead immediately after this attribute again evaluates to false.
• infinite-scroll-immediate-check (optional) - {boolean} - A boolean expression that indicates that the directive should check immediately to see if a scroll event would trigger an evaluation of the infinite scroll expression even if a scroll event does not occur. Useful if it's possible that the content inside the directive's element is not tall enough to fill up the entire browser window's height. Defaults to true.
• infinite-scroll-listen-for-event (optional) - {string} - The name of an event that, when received, will cause the scroll position check to be re-run. This is useful if you need to manually trigger the scroll handler, for instance if your items have been filtered or modified without altering the collection.
• infinite-scroll-container (optional) - {HTMLElement | [] | string} - The HTMLElement in which scrolling is contained. This is an expression that results in an HTMLElement object, an array whose first element is evaluated using angular.element(), or a string which is used as the parameter to document.querySelector(). The selector is similar to jQuery selectors but should evaluate to a single element. Remember to use single quotes around string constants.
• infinite-scroll-use-document-bottom (optional) - {boolean} - True, use the bottom of the document, rather than the containing element, to determine infinite-scroll-distance.
• infinite-scroll-parent (optional) - When present, the scroll container that is tracked is the parent element of the element on which the ngInfiniteScroll directive is placed.

Loading the Module

The infiniteScroll directive lives inside the infinite-scroll module; to get access to it, ensure that your application's own module includes infinite-scroll as a dependency (in addition to any other dependencies):

var myApp = angular.module('myApp', ['infinite-scroll']);

Throttling scroll events

Scroll events can be triggered very frequently, which can hurt performance and make scrolling appear jerky. To mitigate this, infiniteScroll can be configured to process scroll events a maximum of once every x milliseconds:

// you might call this after your module initalization
angular.module('infinite-scroll').value('THROTTLE_MILLISECONDS', 250)
    

Triggering the scroll handler manually

If your items can change their height or be hidden — for instance in a filtered list — it is possible for your list to get shorter and require repopulating without the user triggering a scroll event. In this case, you can use the infinite-scroll-listen-for-event attribute. Later, when you need to trigger the scroll check, fire the corresponding event. For example:

<div infinite-scroll="addMoreItems()" infinite-scroll-listen-for-event="list:filtered">
  [...]
</div>

And then, when you need to trigger the check, for instance in your controller:

$scope.$emit('list:filtered')

Typical Usage

Typically, you will use the infiniteScroll directive on an element that contains another element that uses ngRepeat to show a series of elements based on an array (or object); the expression you pass in to the infinite-scroll attribute will generally add additional elements to the array, expanding the ngRepeat.

<div infinite-scroll="addMoreItems()">
  <div ng-repeat="item in items">Item number {{$index}}: {{$item}}</div>
</div>

For an example of how you can implement this pattern, see the demos.