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:
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
Last updated