React Native Immutable ListView

Drop-in replacement for React Native's

ListView

FlatList

VirtualizedList

It supports Immutable.js to give you faster performance and less headaches.

Motivation

• Do you use Immutable data, only to write the same boilerplate over and over in order to display it?
• Do you want to show 'Loading...', 'No results', and 'Error!' states in your lists?
• Do you have nested objects in your state so a shallow diff won't cut it for pure rendering?
• Do you want better performance while animating screen transitions?

If you answered yes to ANY of these questions, this project can help. Check out the examples below.

How it works

For FlatList and VirtualizedList:

For ListView (deprecated as of React Native v0.59):

The screenshot above shows two different lists. The first uses this data:

Immutable.fromJS({
  'Section A': [
    'foo',
    'bar',
  ],
  'Section B': [
    'fizz',
    'buzz',
  ],
})

The second list is even simpler:

Immutable.Range(1, 100)

There's an example app here if you'd like to see it in action.

Installation

1. Install:

   • Using npm:

     npm install react-native-immutable-list-view --save

   • Using Yarn:

     yarn add react-native-immutable-list-view

2. Import it in your JS:

   For FlatList and VirtualizedList:

   import { ImmutableVirtualizedList } from 'react-native-immutable-list-view';
   

   For ListView:

   import { ImmutableListView } from 'react-native-immutable-list-view/lib/ImmutableListView';
   

Example usage -- replacing FlatList

Goodbye,

keyExtractor

Note: This example diff looks much better on GitHub than on npm's site. Red means delete, green means add.

-import { Text, View, FlatList } from 'react-native';
+import { Text, View } from 'react-native';
+import { ImmutableVirtualizedList } from 'react-native-immutable-list-view';

 import style from './styles';
 import listData from './listData';
 class App extends Component {
   renderItem({ item, index }) {
     return {item};
   }
  render() {
    return (
      
         
           Welcome to React Native!
         

 items.get(index)}
getItemCount={(items) => items.size}
keyExtractor={(item, index) => String(index)}




);
}

}

Example usage -- replacing ListView

You can remove all that boilerplate in your constructor, as well as lifecycle methods like

componentWillReceiveProps

dataSource

ImmutableListView

Note: This example diff looks much better on GitHub than on npm's site. Red means delete, green means add.

-import { Text, View, ListView } from 'react-native';
+import { Text, View } from 'react-native';
+import { ImmutableListView } from 'react-native-immutable-list-view/lib/ImmutableListView';

 import style from './styles';
 import listData from './listData';
 class App extends Component {

constructor(props) {

super(props);


const dataSource = new ListView.DataSource({

rowHasChanged: (r1, r2) => r1 !== r2,

sectionHeaderHasChanged: (s1, s2) => s1 !== s2,

});


const mutableData = listData.toJS();


this.state = {

dataSource: dataSource.cloneWithRowsAndSections(mutableData),

};

}


componentWillReceiveProps(newProps) {

this.setState({

dataSource: this.state.dataSource.cloneWithRows(newProps.listData),

});

}

  renderRow(rowData) {
return <text style="{style.row}">{rowData}</text>;
  }
 renderSectionHeader(sectionData, category) {
   return {category};
 }
 render() {
   return (
 <view style="{style.container}">
    <text style="{style.welcome}">
      Welcome to React Native!
    </text>



);
}



}

Customization

All the props supported by React Native's underlying List are simply passed through, and should work exactly the same. You can see all the VirtualizedList props or ListView props on React Native's website.

You can customize the look of your list by implementing

renderItem

renderRow

Here are the additional props that

ImmutableVirtualizedList

ImmutableListView

| Prop name | Data type | Default value? | Description | |-----------|-----------|----------------|-------------| |

immutableData

Immutable.Iterable

rowsDuringInteraction

number

undefined

sectionHeaderHasChanged

func

(prevSectionData, nextSectionData) => false

ListViewDataSource

renderEmpty

string

func

undefined

null

[]

{}

renderEmptyInList

renderEmptyInList

string

func

'No data.'

null

[]

{}

Also see React Native's

FlatListExample

Methods

Methods such as

scrollToEnd

The references to the raw

VirtualizedList

ListView

getVirtualizedList()

getListView()

How to format your data

ImmutableListView

List

[rowData1, rowData2, ...]

Map of Lists

{
    section1: [
        rowData1,
        rowData2,
        ...
    ],
    ...
}

Map of Maps

{
    section1: {
        rowId1: rowData1,
        rowId2: rowData2,
        ...
    },
    ...
}

To try it out yourself, you can use the example app!

Support is coming soon for section headers with

ImmutableVirtualizedList

SectionList

Loading / Empty / Error states

The optional

renderEmptyInList

No data.

render() {
  const emptyText = this.state.isLoading
    ? "Loading..."
    : this.state.errorMsg
      ? "Error!"
      : "No data.";

  return (
    
  );
}

The empty list will receive all the same props as your normal list, so things like pull-to-refresh will still work.