Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including react-native-immutable-list-view with all npm packages installed. Try it out:

require("react/package.json"); // react is a peer dependency. require("react-native/package.json"); // react-native is a peer dependency. var reactNativeImmutableListView = require("react-native-immutable-list-view")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

react-native-immutable-list-view v1.0.1

Drop-in replacement for React Native's ListView, FlatList, and VirtualizedList.

React Native Immutable ListView

Build status npm downloads npm version Latest GitHub tag


Logo


Drop-in replacement for React Native's ListView, FlatList, and VirtualizedList.

ImmutableListView screenshot

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:

<ImmutableVirtualizedList
  immutableData={this.state.listData}
  renderItem={this.renderItem}
/>

For ListView:

<ImmutableListView
  immutableData={this.state.listData}
  renderRow={this.renderRow}
/>

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';
    

Example usage -- replacing FlatList

Goodbye, keyExtractor boilerplate!

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 <Text style={style.row}>{item}</Text>;
   }

  render() {
    return (
      <View style={style.container}>
         <Text style={style.welcome}>
           Welcome to React Native!
         </Text>
-        <FlatList
-          data={listData}
-          getItem={(items, index) => items.get(index)}
-          getItemCount={(items) => items.size}
-          keyExtractor={(item, index) => String(index)}
+        <ImmutableVirtualizedList
+          immutableData={listData}
           renderItem={this.renderItem}
         />
      </View>
    );
  }

}

Example usage -- replacing ListView

You can remove all that boilerplate in your constructor, as well as lifecycle methods like componentWillReceiveProps if all they're doing is updating your dataSource. ImmutableListView will handle all of this for you.

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';

 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 <Text style={style.header}>{category}</Text>;
  }

  render() {
    return (
      <View style={style.container}>
         <Text style={style.welcome}>
           Welcome to React Native!
         </Text>
-        <ListView
-          dataSource={this.state.dataSource}
+        <ImmutableListView
+          immutableData={listData}
           renderRow={this.renderRow}
           renderSectionHeader={this.renderSectionHeader}
         />
      </View>
    );
  }

}

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 for FlatList and VirtualizedList or renderRow for ListView.

Here are the additional props that ImmutableVirtualizedList and ImmutableListView accept:

Prop nameData typeDefault value?Description
immutableDataAny Immutable.IterableRequired.The data to render. See below for some examples.
rowsDuringInteractionnumberundefinedHow many rows of data to initially display while waiting for interactions to finish (e.g. Navigation animations).
sectionHeaderHasChangedfunc(prevSectionData, nextSectionData) => falseOnly needed if your section header is dependent on your row data (uncommon; see ListViewDataSource's constructor for details).
renderEmptystring or funcundefinedIf your data is empty (e.g. null, [], {}) and this prop is defined, then this will be rendered instead. Pull-refresh and scrolling functionality will be lost. Most of the time you should use renderEmptyInList instead.
renderEmptyInListstring or func'No data.'If your data is empty (e.g. null, [], {}) and this prop is defined, then this will be rendered instead. Pull-refresh and scrolling functionality will be kept! See below for more details.

Also see React Native's FlatListExample for more inspiration.

Methods

Methods such as scrollToEnd are passed through just like the props described above. You can read about them here for ListView or here for FlatList and VirtualizedList.

The references to the raw VirtualizedList or ListView component are available via getVirtualizedList() or getListView(). These references allow you to access any other methods on the underlying List that you might need.

How to format your data

ImmutableListView accepts several standard formats for list data. Here are some examples:

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 too, similar to SectionList. See PR #34.

Loading / Empty / Error states

The optional renderEmptyInList prop takes a string and renders an Immutable List displaying the text you specified. By default, this text is simply No data., but you can customize this based on your state. For example:

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

  return (
    <ImmutableVirtualizedList
      immutableData={this.state.listData}
      renderItem={this.renderItem}
      renderEmptyInList={emptyText}
    />
  );
}

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

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free