React Native’s new FlatList component

Including: How to migrate from _ListView_ (soon to be ), and how to try it in your own app without building React Native from source.

Update 4: It’s stable enough now to be exported by default from with React Native v0.43. No custom downloads needed! Keep reading for easy migration steps.

Update 3: It’s as of March 1. Everything below is still up-to-date and accurate.

Update 2: There are now multiple new components: , , , and . Their locations have moved several times, but the links below should be up-to-date.

Update 1: The original is .

Earlier in February, an experimental new React Native component called FlatList. It significantly improves memory usage and efficiency (especially for large or complex lists) while also significantly simplifying the props — no more dataSource necessary!

By default, FlatList expects your data to be a simple array of values. One big advantage of the new API, however, is the ability to provide your own implementation of getItem. This is extremely useful for non-standard data formats such as Immutable data or complex nesting. You’ll need to use the underlying VirtualizedList component for this.

Disclaimer: I’m the creator of [react-native-immutable-list-view](//github.com/cooperka/react-native-immutable-list-view), which to use Immutable data with the old ListView as well as the new VirtualizedList.

Or if you were previously using [ImmutableListView](//github.com/cooperka/react-native-immutable-list-view), it’s even more straightforward:

The only caveat here is that you need to actually get the source code for the new React Native components in order to use them [Update 4: this step is no longer necessary as of React Native v0.43]. They currently exist only on [master](//github.com/facebook/react-native/tree/master/Libraries/CustomComponents/Lists), so here’s a quick script that will download them straight into your project (assuming you’ve already installed react-native using npm or Yarn). Copy this whole command into your terminal:

This will download the latest version of FlatList and its related dependencies into your app’s node_modules so you can refer to it as in the examples above, without needing to checkout React Native’s master and build it from source.

You could, for example, add the above command to your package’s postinstall script to make sure the files exist for every developer and build pipeline on your team (thanks to for this tip).

There’s a more extensive [FlatListExample](//github.com/facebook/react-native/blob/master/Examples/UIExplorer/js/FlatListExample.js) in React Native’s repo if you want to get a feel for the full set of props and how powerful the new component can be. I also have my own that should work out of the box with no extra steps other than copying the files and running npm install. Feel free to post an with any questions — I’m happy to help.

Final note: FlatList intentionally will like [ListView](//facebook.github.io/react-native/docs/listview.html#rendersectionheader) ; for this there’s a separate component called SectionList, or you can use the lower-level VirtualizedList directly.

If you found this useful, please help by tapping the 👏 button as many times as you’d like so others can find it too. Thank you!