VirtualListView *

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

Installation

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

NPM
Yarn
NPM
$ npm i react-ult-ext-virtuallistview
Yarn
$ yarn add react-ult-ext-virtuallistview

Description

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.

Props

Name

Type

Description

animateChanges?

boolean

  • Should the list animate additions, removals and moves within the list?

initialSelectedKey?

string

  • Should the list animate additions, removals and moves within the list?

itemList

VirtualizeItemInfo[]

  • Ordered list of descriptors for items to display in the list.

keyboardFocusScrollOffset?

number

  • Use this if you want to vertically offset the focused item from the top of the viewport when using keyboard navigation

logInfo?

(textToLog: string) => void

  • Logging callback to debug issues.

onItemSelected?

(item: ItemInfo) => void

  • Callback when an item is selected

padding?

number

  • Optional padding around the scrolling content within the list

renderItem

(renderDetails: VirtualListCellRenderDetails) => JSX.Element | JSX.Element[]

  • Callback for rendering item when it becomes visible within view port

showOverflow?

boolean

  • If true, allows each item to overflow its visible cell boundaries; by default, item contents are clipped to cell boundaries

skipRenderIfItemUnchanged?

boolean

  • By default, Virtualize re-renders every item during the render

  • Setting this flag to true allows the list view to re-render only items from itemList whose descriptor has changed, thus avoiding unnecessary rendering. It uses _.isEqual to perform this check. In this mode, renderItem should not depend on any external state, only on VirtualizeItemInfo, to render item

testId

string

  • ID that can be used to identify the instantiated element for testing purposes

keyboardDismissMode?

'none' | 'interactive' | 'on-drag'

  • Pass-through properties for scroll view

keyboardShouldPersistTaps?

boolean

  • Pass-through properties for scroll view

disableScrolling?

boolean

  • Pass-through properties for scroll view

scrollsToTop?

boolean

  • Pass-through properties for scroll view

disableBouncing?

boolean

  • Pass-through properties for scroll view

scrollIndicatorInsets?

{top: number, left: number, bottom: number, right: number}

  • Pass-through properties for scroll view

onLayout?

(e: ViewOnLayoutEvent) => void

  • Pass-through properties for scroll view

scrollEventThrottle?

number

  • Pass-through properties for scroll view

onScroll?

(scrollTop: number, scrollLeft: number) => void

  • Pass-through properties for scroll view

scrollXAnimatedValue?

AnimatedValue

  • Pass-through properties for scroll view

scrollYAnimatedValue?

AnimatedValue

  • Pass-through properties for scroll view