VirtualizedList
A more convenient foundational implementation for <FlatList> and <SectionList>, with more comprehensive documentation for those components. In general, you only need to use this if you require more flexibility than FlatList provides, for example when working with immutable data instead of plain arrays.
Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-priority (after any running interactions) if they are far from the visible area, or with high-priority otherwise to minimize the potential for seeing blank space.
Examples
- TypeScript
- JavaScript
Some notes:
- Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
- This is a
PureComponentwhich means that it will not re-render ifpropsremain shallow-equal. Make sure that everything yourrenderItemfunction depends on is passed as a prop (e.g.extraData) that is not===after updates, otherwise your UI may not update on changes. This includes thedataproperty and parent component state. - In order to constrain memory consumption and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
- By default, the list looks for a
keyprop on each item and uses that for the React key. Alternatively, you can provide a customkeyExtractorprop.
Reference
Props
ScrollView Props
Inherits ScrollView Props.
data
An opaque data type passed to getItem and getItemCount to retrieve items.
| Type |
|---|
| any |
Required getItem
(data: any, index: number) => any;
A generic accessor for extracting an item from any sort of data blob.
| Type |
|---|
| function |
Required getItemCount
(data: any) => number;
Determines how many items are in the data blob.
| Type |
|---|
| function |
Required renderItem
(info: any) => ?React.Element<any>
Takes an item from data and renders it into the list.
| Type |
|---|
| function |
CellRendererComponent
Allows custom cells rendered by renderItem/ListItemComponent to be wrapped in a special way such as with CellRendererComponent. The component must accept event handlers to notify VirtualizedList of changes within the cell.
| Type |
|---|
React.ComponentType<CellRendererProps> |
ItemSeparatorComponent
Rendered between each item, but not at the top or bottom. By default, highlighted and leadingItem props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, and can also use separators.updateProps to add custom props. Can be a React component, e.g. SomeComponent, or a React element, e.g. <SomeComponent />.
| Type |
|---|
| component, function, element |
ListEmptyComponent
Rendered when the list is empty. Can be a React component, e.g. SomeComponent, or a React element, e.g. <SomeComponent />.
| Type |
|---|
| component, element |
ListItemComponent
Each item in the data is rendered using this element. It can be a React component class, or a render function.
| Type |
|---|
| component, function |
ListFooterComponent
Rendered at the bottom of all the items. Can be a React component, e.g. SomeComponent, or a React element, e.g. <SomeComponent />.
| Type |
|---|
| component, element |
ListFooterComponentStyle
Styling for internal View for ListFooterComponent.
| Type | Required |
|---|---|
| ViewStyleProp | No |
ListHeaderComponent
Rendered at the top of all the items. Can be a React component, e.g. SomeComponent, or a React element, e.g. <SomeComponent />.
| Type |
|---|
| component, element |
ListHeaderComponentStyle
Styling for internal View for ListHeaderComponent.
| Type |
|---|
| view style |
debug
Enables extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit.
| Type |
|---|
| boolean |
🗑️ disableVirtualization
Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You typically only need to disable it while debugging.
| Type |
|---|
| boolean |
extraData
A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.
| Type |
|---|
| any |
getItemLayout
(
data: any,
index: number,
) => {length: number, offset: number, index: number}
| Type |
|---|
| function |
horizontal
If true, renders items horizontally instead of vertically.
| Type |
|---|
| boolean |
initialNumToRender
How many items to render in the initial batch. Should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.
| Type | Default |
|---|---|
| number | 10 |
initialScrollIndex
Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.
| Type |
|---|
| number |
inverted
Reverses the direction of scroll. Uses scale transforms of -1.
| Type |
|---|
| boolean |
keyExtractor
(item: any, index: number) => string;
Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.
| Type |
|---|
| function |
maxToRenderPerBatch
The maximum number of items to render in each incremental render batch. More rendered at once means better fill rate, but responsiveness may suffer because rendering content may interfere with responding to button touches or other interactions.
| Type |
|---|
| number |
onEndReached
Called once when the scroll position gets within onEndReachedThreshold of the logical end of the list.
| Type |
|---|
(info: {distanceFromEnd: number}) => void |
onEndReachedThreshold
How far from the end (in units of visible length of the list) the trailing edge of the list must be from the end of the content to trigger the onEndReached callback. Thus, a value of 0.5 will trigger when the end of the content is within half the visible length of the list.
| Type | Default |
|---|---|
| number | 2 |
onRefresh
() => void;
If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.
| Type |
|---|
| function |
onScrollToIndexFailed
(info: {
index: number,
highestMeasuredFrameIndex: number,
averageItemLength: number,
}) => void;
Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and scrollTo it, or scroll as far as possible and then try again after more items have been rendered.
| Type |
|---|
| function |
onStartReached
Called once when the scroll position gets within onStartReachedThreshold of the logical start of the list.
| Type |
|---|
(info: {distanceFromStart: number}) => void |
onStartReachedThreshold
How far from the start (in units of visible length of the list) the leading edge of the list must be from the start of the content to trigger the onStartReached callback. Thus, a value of 0.5 will trigger when the start of the content is within half the visible length of the list.
| Type | Default |
|---|---|
| number | 2 |
onViewableItemsChanged
Called when the visibility of rows changes, as defined by the viewabilityConfig prop.
persistentScrollbar
| Type |
|---|
| bool |
progressViewOffset
Set this when offset is needed for the loading indicator to show correctly.
| Type |
|---|
| number |
refreshControl
A custom refresh control element. When set, it overrides the default <RefreshControl> component built internally and ignores the onRefresh and refreshing props. Only works for vertical VirtualizedList.
| Type |
|---|
| element |
refreshing
Set to true while waiting for new data from a refresh.
| Type |
|---|
| boolean |
removeClippedSubviews
Using this property can lead to bugs (missing content) in some circumstances - use at your own risk.
Note that this may improve scroll performance for large lists when the offscreen child views are removed from their native backing superview. Default is true for Android.
| Type |
|---|
| boolean |
renderScrollComponent
(props: object) => element;
Render a custom scrolling component, e.g. with a differently styled RefreshControl.
| Type |
|---|
| function |
viewabilityConfig
See ViewabilityHelper.js for flow type definitions and documentation.
| Type |
|---|
| ViewabilityConfig |
viewabilityConfigCallbackPairs
A pair of ViewabilityConfig and onViewableItemsChanged callbacks. When an item satisfies the visibility condition, the corresponding onViewableItemsChanged is called. See ViewabilityHelper.js for flow type definitions and documentation.
| Type |
|---|
Array<ViewabilityConfigCallbackPair> |
updateCellsBatchingPeriod
Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as maxToRenderPerBatch.
| Type |
|---|
| number |
windowSize
Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So, if your list fills the screen, windowSize={21} (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas.
| Type |
|---|
| number |
Methods
flashScrollIndicators()
flashScrollIndicators();
getScrollableNode()
getScrollableNode(): any;
getScrollRef()
getScrollRef():
| React.ElementRef<typeof ScrollView>
| React.ElementRef<typeof View>
| null;
getScrollResponder()
getScrollResponder () => ScrollResponderMixin | null;
Provides a reference to the underlying scroll responder. Note that this._scrollRef is not necessarily a ScrollView, so you must confirm it supports getScrollResponder before calling it.
scrollToEnd()
scrollToEnd(params?: {animated?: boolean});
Scrolls to the end of the content. If getItemLayout is not implemented, this may cause jank.
Parameters:
| Name | Type |
|---|---|
| params | Object |
Supported params keys:
'animated'(boolean), whether to enable scroll animation, defaults totrue.
scrollToIndex()
scrollToIndex(params: {
index: number;
animated?: boolean;
viewOffset?: number;
viewPosition?: number;
});
Parameters:
'index'(number), required.'animated'(boolean), optional.'viewOffset'(number), optional.'viewPosition'(number), optional.
scrollToItem()
scrollToItem(params: {
item: ItemT;
animated?: boolean;
viewOffset?: number;
viewPosition?: number;
);
Parameters:
'item'(item), required.'animated'(boolean), optional.'viewOffset'(number), optional.'viewPosition'(number), optional.
scrollToOffset()
scrollToOffset(params: {
offset: number;
animated?: boolean;
});
Scroll to a specific pixel offset in the list.
The offset parameter is the offset to scroll to. When horizontal is true, the offset is an x-value; otherwise, it is a y-value.
The animated parameter (default true) specifies whether the scroll should be animated.