VirtualListView *

This components supports a list of items within a scrolling area. The visible portion of the list is referred to as the “viewport”.


This component is not included by default, to use it import the following package:

$ npm i react-ult-ext-virtuallistview


The component is windowed, or virtualized, which means that items are rendered only when they are within the view port (or just above or below the view port).

Unlike other list views (such as the ListView provided in React Native), this component supports lists of heterogeneous items with different heights and completely different types.

Each item in the list is described by a VirtualizeItemInfo object. The list of items is specified by an ordered list passed in the itemList prop. When an item comes into view, it is rendered through the use of the renderItem callback. Additional fields can be added to the VirtualizeItemInfo by the caller as it sees fit. For example, it is sometimes useful to include additional identifying information such as an item type or an item-specific render method.

A height must be specified for each item. By default, this height is assumed to be accurate and constant. If you do not know the height of the object or it may change, the height can be measured at runtime. This option is expensive, so it should be avoided if possible.

It optionally supports animation of items when they are added, removed or moved within the list.

When items are added before or after the visible region, it attempts to maintain the current position of the visible items, adjusting the scroll position and list height as necessary.

Performance Techniques

The VirtualListView component employs a number of tricks to improve performance.

It uses a technique called “cell recycling” to minimize the number of mounts and unmounts. A cell is a container for a list item. When a cell is no longer visible, it can be temporarily hidden and then reused for the next item that becomes visible. This optimization is most effective when the recycled cell and its contents are used for an item that is similar in content. For this reason, callers need to specify a “template” field to identify similar items. In some cases, disabling cell recycling can be beneficial as recycled cells continue their regular react lifecycle even when not visible, which can lead to excessive background re-rendering in some cases.

It also supports “overdraw” to render items above and below the view port. This minimizes chances that the user will scroll to a new portion of the list before new items can be rendered in that area. Overdraw is employed only after the view port is initially filled. This reduces the performance impact of rendering.

It also limits the number of items it renders each time to avoid consuming too many cycles on the JavaScript thread.

It supports a special mode where items are re-rendered only if the corresponding VirtualizeItemInfo changes. This mode requires that the renderItem method use only information within this object. To use this mode, set the skipRenderIfItemUnchanged prop to true.


Last updated