React NativeSectionList #
A performant interface for rendering sectioned lists, supporting the most handy features:
- Fully cross-platform.
- Configurable viewability callbacks.
- List header support.
- List footer support.
- Item separator support.
- Section header support.
- Section separator support.
- Heterogeneous data and item rendering support.
- Pull to Refresh.
- Scroll loading.
If you don't need section support and want a simpler interface, use <FlatList>.
If you need sticky section header support, use ListView for now.
Simple Examples:
<SectionList
renderItem={({item}) => <ListItem title={item.title}}
renderSectionHeader={({section}) => <H1 title={section.key} />}
sections={[ // homogenous rendering between sections
{data: [...], key: ...},
{data: [...], key: ...},
{data: [...], key: ...},
]}
/>
<SectionList
sections={[ // heterogeneous rendering between sections
{data: [...], key: ..., renderItem: ...},
{data: [...], key: ..., renderItem: ...},
{data: [...], key: ..., renderItem: ...},
]}
/>
This is a convenience wrapper around <VirtualizedList>,
and thus inherits the following caveats:
- 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 that is not===after updates, otherwise your UI may not update on changes. This includes thedataprop and parent component state. - In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate ands 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.
Props #
ItemSeparatorComponent?: ?ReactClass<any> #
Rendered in between adjacent Items within each section.
ListFooterComponent?: ?ReactClass<any> #
Rendered at the very end of the list.
ListHeaderComponent?: ?ReactClass<any> #
Rendered at the very beginning of the list.
SectionSeparatorComponent?: ?ReactClass<any> #
Rendered in between each section.
keyExtractor: (item: Item, 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 falls back to using the index, like react does.
onEndReached?: ?(info: {distanceFromEnd: number}) => void #
onRefresh?: ?() => void #
If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make
sure to also set the refreshing prop correctly.
onViewableItemsChanged?: ?(info: {viewableItems: Array<ViewToken>, changed: Array<ViewToken>}) => void #
Called when the viewability of rows changes, as defined by the
viewabilityConfig prop.
refreshing?: ?boolean #
Set this true while waiting for new data from a refresh.
renderItem: (info: {item: Item, index: number}) => ?React.Element<any> #
Default renderer for every item in every section. Can be over-ridden on a per-section basis.
renderSectionHeader?: ?(info: {section: SectionT}) => ?React.Element<any> #
Rendered at the top of each section. Sticky headers are not yet supported.
sections: Array<SectionT> #
shouldItemUpdate: (
prevProps: {item: Item, index: number},
nextProps: {item: Item, index: number}
) => boolean #
This is an optional optimization to minimize re-rendering items.
You can edit the content above on GitHub and send us a pull request!
Examples # | Edit on GitHub |
'use strict';
const React = require('react');
const ReactNative = require('react-native');
const {
SectionList,
StyleSheet,
Text,
View,
} = ReactNative;
const UIExplorerPage = require('./UIExplorerPage');
const infoLog = require('infoLog');
const {
HeaderComponent,
FooterComponent,
ItemComponent,
PlainInput,
SeparatorComponent,
genItemData,
pressItem,
renderSmallSwitchOption,
renderStackedItem,
} = require('./ListExampleShared');
const VIEWABILITY_CONFIG = {
minimumViewTime: 3000,
viewAreaCoveragePercentThreshold: 100,
waitForInteraction: true,
};
const renderSectionHeader = ({section}) => (
<View>
<Text style={styles.headerText}>SECTION HEADER: {section.key}</Text>
<SeparatorComponent />
</View>
);
const CustomSeparatorComponent = ({text}) => (
<View>
<SeparatorComponent />
<Text style={styles.separatorText}>{text}</Text>
<SeparatorComponent />
</View>
);
class SectionListExample extends React.PureComponent {
static title = '<SectionList>';
static description = 'Performant, scrollable list of data.';
state = {
data: genItemData(1000),
filterText: '',
logViewable: false,
virtualized: true,
};
render() {
const filterRegex = new RegExp(String(this.state.filterText), 'i');
const filter = (item) => (
filterRegex.test(item.text) || filterRegex.test(item.title)
);
const filteredData = this.state.data.filter(filter);
return (
<UIExplorerPage
noSpacer={true}
noScroll={true}>
<View style={styles.searchRow}>
<PlainInput
onChangeText={filterText => {
this.setState(() => ({filterText}));
}}
placeholder="Search..."
value={this.state.filterText}
/>
<View style={styles.optionSection}>
{renderSmallSwitchOption(this, 'virtualized')}
{renderSmallSwitchOption(this, 'logViewable')}
</View>
</View>
<SeparatorComponent />
<SectionList
ListHeaderComponent={HeaderComponent}
ListFooterComponent={FooterComponent}
SectionSeparatorComponent={() =>
<CustomSeparatorComponent text="SECTION SEPARATOR" />
}
ItemSeparatorComponent={() =>
<CustomSeparatorComponent text="ITEM SEPARATOR" />
}
enableVirtualization={this.state.virtualized}
onRefresh={() => alert('onRefresh: nothing to refresh :P')}
onViewableItemsChanged={this._onViewableItemsChanged}
refreshing={false}
renderItem={this._renderItemComponent}
renderSectionHeader={renderSectionHeader}
sections={[
{renderItem: renderStackedItem, key: 's1', data: [
{title: 'Item In Header Section', text: 'Section s1', key: '0'},
]},
{key: 's2', data: [
{noImage: true, title: '1st item', text: 'Section s2', key: '0'},
{noImage: true, title: '2nd item', text: 'Section s2', key: '1'},
]},
{key: 'Filtered Items', data: filteredData},
]}
viewabilityConfig={VIEWABILITY_CONFIG}
/>
</UIExplorerPage>
);
}
_renderItemComponent = ({item}) => (
<ItemComponent item={item} onPress={this._pressItem} />
);
// This is called when items change viewability by scrolling into our out of
// the viewable area.
_onViewableItemsChanged = (info: {
changed: Array<{
key: string,
isViewable: boolean,
item: {columns: Array<*>},
index: ?number,
section?: any
}>},
) => {
// Impressions can be logged here
if (this.state.logViewable) {
infoLog('onViewableItemsChanged: ', info.changed.map((v: Object) => (
{...v, item: '...', section: v.section.key}
)));
}
};
_pressItem = (index: number) => {
pressItem(this, index);
};
}
const styles = StyleSheet.create({
headerText: {
padding: 4,
},
optionSection: {
flexDirection: 'row',
},
searchRow: {
paddingHorizontal: 10,
},
separatorText: {
color: 'gray',
alignSelf: 'center',
padding: 4,
fontSize: 9,
},
});
module.exports = SectionListExample;
