A performant interface for rendering sectioned lists, supporting the most handy features:
If you don't need section support and want a simpler interface, use <FlatList>.
This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:
PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function 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 the data prop and parent component state.key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.Inherits VirtualizedList Props.
renderItemโDefault renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.
The render function will be passed an object with the following keys:
data keysections.() => void() => void(select, newProps) => void
sectionsโThe actual data to render, akin to the data prop in FlatList.
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.
initialNumToRenderโHow many items to render in the initial batch. This 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.
10invertedโReverses the direction of scroll. Uses scale transforms of -1.
falseItemSeparatorComponentโRendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).
keyExtractorโ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. Note that this sets keys for each item, but each overall section still needs its own key.
ListEmptyComponentโRendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).
ListFooterComponentโRendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).
ListHeaderComponentโRendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).
onRefreshโIf provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.
onViewableItemsChangedโCalled when the viewability of rows changes, as defined by the viewabilityConfig prop.
(callback: {changed: ViewToken[], viewableItems: ViewToken[]}) => voidrefreshingโSet this true while waiting for new data from a refresh.
falseremoveClippedSubviewsโUsing this property may lead to bugs (missing content) in some circumstances - use at your own risk.
When true, offscreen child views are removed from their native backing superview when offscreen. This may improve scroll performance for large lists. On Android the default value is true.
renderSectionFooterโRendered at the bottom of each section.
Type(info: {section: Section}) => element ๏ฝ nullrenderSectionHeaderโRendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.
(info: {section: Section}) => element ๏ฝ nullSectionSeparatorComponentโRendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.
stickySectionHeadersEnabledโMakes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.
false true flashScrollIndicators() flashScrollIndicators();
Displays the scroll indicators momentarily.
recordInteraction()โrecordInteraction();
Tells the list an interaction has occurred, which should trigger viewability calculations, e.g. if waitForInteractions is true and the user has not scrolled. This is typically called by taps on items or by navigation actions.
scrollToLocation()โscrollToLocation(params: SectionListScrollParams);
Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition set to 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.
You cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.
Parameters:
Valid params keys are:
true.0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.An object that identifies the data to be rendered for a given section.
TypeProperties:
FlatList's data prop.renderItem for the list.ItemSeparatorComponent for the list.keyExtractor.