React Native’s new FlatList component

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

The demo video posted on Facebook by Ahrens. Image link goes to YouTube.

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

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

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

Update 1: The original ListView is planned to be deprecated.

Earlier in February, Spencer Ahrens published 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](https://github.com/cooperka/react-native-immutable-list-view), which makes it easier to use Immutable data with the old ListView as well as the new VirtualizedList.

Here’s a migration guide from the old component if you want to try it yourself. As you can see, your code should get a lot simpler (red means delete, green means add):

Or if you were previously using [ImmutableListView](https://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](https://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 Bruno Lemos for this tip).

There’s a more extensive [FlatListExample](https://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 example app 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 issue with any questions — I’m happy to help.

Final note: FlatList intentionally will never support section headers like [ListView](https://facebook.github.io/react-native/docs/listview.html#rendersectionheader) has; 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!

Keep an eye out for more updates — I’ll keep this post updated.