ListView #

ListView - A core component designed for efficient display of vertically scrolling lists of changing data. The minimal API is to create a ListView.DataSource, populate it with a simple array of data blobs, and instantiate a ListView component with that data source and a renderRow callback which takes a blob from the data array and returns a renderable component.

Minimal example:

class MyComponent extends Component { constructor() { super(); const ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2}); this.state = { dataSource: ds.cloneWithRows(['row 1', 'row 2']), }; } render() { return ( <ListView dataSource={this.state.dataSource} renderRow={(rowData) => <Text>{rowData}</Text>} /> ); } }

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

  • Only re-render changed rows - the rowHasChanged function provided to the data source tells the ListView if it needs to re-render a row because the source data has changed - see ListViewDataSource for more details.

  • Rate-limited row rendering - By default, only one row is rendered per event-loop (customizable with the pageSize prop). This breaks up the work into smaller chunks to reduce the chance of dropping frames while rendering rows.

Props #

dataSource: ListViewDataSource #

An instance of ListView.DataSource to use

enableEmptySections?: bool #

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

initialListSize: number #

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

onChangeVisibleRows?: function #

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

onEndReached?: function #

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

onEndReachedThreshold: number #

Threshold in pixels (virtual, not physical) for calling onEndReached.

pageSize: number #

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

removeClippedSubviews?: bool #

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

renderFooter?: function #

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass.

renderHeader?: function #

renderRow: function #

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

renderScrollComponent: function #

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

renderSectionHeader?: function #

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

renderSeparator?: function #

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

scrollRenderAheadDistance: number #

How early to start rendering rows before they come on screen, in pixels.

iosstickyHeaderIndices: [number] #

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

iosstickySectionHeadersEnabled?: bool #

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header.

Methods #

getMetrics() #

Exports some data, e.g. for perf investigations or analytics.

scrollTo(...args: Array) #

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd(options?: object) #

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

You can edit the content above on GitHub and send us a pull request!

Examples #

Edit on GitHub
'use strict'; var React = require('react'); var ReactNative = require('react-native'); var { Image, ListView, TouchableHighlight, StyleSheet, Text, View, } = ReactNative; var UIExplorerPage = require('./UIExplorerPage'); var ListViewSimpleExample = React.createClass({ statics: { title: '<ListView>', description: 'Performant, scrollable list of data.' }, getInitialState: function() { var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2}); return { dataSource: ds.cloneWithRows(this._genRows({})), }; }, _pressData: ({}: {[key: number]: boolean}), componentWillMount: function() { this._pressData = {}; }, render: function() { return ( <UIExplorerPage title={this.props.navigator ? null : '<ListView>'} noSpacer={true} noScroll={true}> <ListView dataSource={this.state.dataSource} renderRow={this._renderRow} renderSeparator={this._renderSeparator} /> </UIExplorerPage> ); }, _renderRow: function(rowData: string, sectionID: number, rowID: number, highlightRow: (sectionID: number, rowID: number) => void) { var rowHash = Math.abs(hashCode(rowData)); var imgSource = THUMB_URLS[rowHash % THUMB_URLS.length]; return ( <TouchableHighlight onPress={() => { this._pressRow(rowID); highlightRow(sectionID, rowID); }}> <View> <View style={styles.row}> <Image style={styles.thumb} source={imgSource} /> <Text style={styles.text}> {rowData + ' - ' + LOREM_IPSUM.substr(0, rowHash % 301 + 10)} </Text> </View> </View> </TouchableHighlight> ); }, _genRows: function(pressData: {[key: number]: boolean}): Array<string> { var dataBlob = []; for (var ii = 0; ii < 100; ii++) { var pressedText = pressData[ii] ? ' (pressed)' : ''; dataBlob.push('Row ' + ii + pressedText); } return dataBlob; }, _pressRow: function(rowID: number) { this._pressData[rowID] = !this._pressData[rowID]; this.setState({dataSource: this.state.dataSource.cloneWithRows( this._genRows(this._pressData) )}); }, _renderSeparator: function(sectionID: number, rowID: number, adjacentRowHighlighted: bool) { return ( <View key={`${sectionID}-${rowID}`} style={{ height: adjacentRowHighlighted ? 4 : 1, backgroundColor: adjacentRowHighlighted ? '#3B5998' : '#CCCCCC', }} /> ); } }); var THUMB_URLS = [ require('./Thumbnails/like.png'), require('./Thumbnails/dislike.png'), require('./Thumbnails/call.png'), require('./Thumbnails/fist.png'), require('./Thumbnails/bandaged.png'), require('./Thumbnails/flowers.png'), require('./Thumbnails/heart.png'), require('./Thumbnails/liking.png'), require('./Thumbnails/party.png'), require('./Thumbnails/poke.png'), require('./Thumbnails/superlike.png'), require('./Thumbnails/victory.png'), ]; var LOREM_IPSUM = 'Lorem ipsum dolor sit amet, ius ad pertinax oportere accommodare, an vix civibus corrumpit referrentur. Te nam case ludus inciderint, te mea facilisi adipiscing. Sea id integre luptatum. In tota sale consequuntur nec. Erat ocurreret mei ei. Eu paulo sapientem vulputate est, vel an accusam intellegam interesset. Nam eu stet pericula reprimique, ea vim illud modus, putant invidunt reprehendunt ne qui.'; /* eslint no-bitwise: 0 */ var hashCode = function(str) { var hash = 15; for (var ii = str.length - 1; ii >= 0; ii--) { hash = ((hash << 5) - hash) + str.charCodeAt(ii); } return hash; }; var styles = StyleSheet.create({ row: { flexDirection: 'row', justifyContent: 'center', padding: 10, backgroundColor: '#F6F6F6', }, thumb: { width: 64, height: 64, }, text: { flex: 1, }, }); module.exports = ListViewSimpleExample;