Skip to main content

FlatList

A list on top of ScrollView, with the React Native FlatList API.

import { FlatList, Text } from 'react-native'

export function Contacts({ contacts }) {
return (
<FlatList
data={contacts}
keyExtractor={(contact) => contact.id}
renderItem={({ item }) => <Text>{item.name}</Text>}
onEndReached={loadMore}
/>
)
}
No virtualizer yet

FlatList renders every item, so each one costs DOM memory and render time. Load a long list in pages with onEndReached.

Each item sits in a cell View, with its separator after it, as on native. The default keyExtractor uses key, then id, then the index, as on native.

Props​

PropOn the web
data, renderItem, ListItemComponent, keyExtractorAs on native.
ItemSeparatorComponentGets highlighted and leadingItem. separators.highlight(), unhighlight(), and updateProps() in renderItem work.
ListHeaderComponent, ListFooterComponent, ListEmptyComponentA component or an element. ListHeaderComponentStyle and ListFooterComponentStyle style their wrappers.
numColumns, columnWrapperStyleGroups the items into rows. A row's key joins the keys of its items.
horizontalA row of items.
invertedFlips the scroller and each cell with a transform, as on native, so the first item is at the bottom.
initialScrollIndexScrolls to that item on mount.
onViewableItemsChanged, viewabilityConfigThe React Native rules: an item is viewable when it's whole in the viewport, or when its visible part reaches itemVisiblePercentThreshold or viewAreaCoveragePercentThreshold. minimumViewTime and waitForInteraction work.
viewabilityConfigCallbackPairsWorks, as on native.
onEndReached, onEndReachedThresholdFires once per content length, when the scroll comes within the threshold of the end. The threshold is a share of the viewport. Without one, it's 2 px, as on native. A list shorter than its viewport fires it after mount.
onStartReached, onStartReachedThresholdThe same, at the start.
CellRendererComponentRenders inside the cell View, with cellKey, index, item, style, and the item and separator as children.
renderScrollComponentRenders the scroller. It gets the scroll props and onRefresh, refreshing, and progressViewOffset, without the ref. The list adds no RefreshControl then, as on native.
stickyHeaderIndicesAs on ScrollView. With every item rendered, the indices match native.
onRefresh, refreshing, progressViewOffsetWrap the scroller in a RefreshControl, as on native. With onRefresh, refreshing must be a boolean, or the list throws. A refreshControl prop wins. In an inverted list, the pull starts at the bottom and goes up.
ScrollView propsAs on ScrollView.

These virtualizer props are accepted and ignored: initialNumToRender, maxToRenderPerBatch, windowSize, updateCellsBatchingPeriod, removeClippedSubviews, disableVirtualization, extraData, and getItemLayout. Every cell is in the DOM, so the list measures each one there.

Ref​

The ref is an object with the React Native methods:

MethodOn the web
scrollToOffset({ offset, animated })As on native.
scrollToIndex({ index, viewPosition, viewOffset, animated })As on native. With numColumns, the index is a row index.
scrollToItem({ item, viewPosition, viewOffset, animated })Finds the row of the item and scrolls to it.
scrollToEnd({ animated })Scrolls to the end.
recordInteraction()Starts viewability for waitForInteraction.
getScrollableNode(), getNativeScrollRef(), getScrollResponder()The scroll element of the ScrollView.
flashScrollIndicators(), setNativeProps()Do nothing.

onScrollToIndexFailed never fires, because every cell is in the DOM.