{"id":28710859,"url":"https://github.com/cooperka/react-native-immutable-list-view","last_synced_at":"2025-06-14T21:08:27.364Z","repository":{"id":55849823,"uuid":"70337867","full_name":"cooperka/react-native-immutable-list-view","owner":"cooperka","description":":scroll: Drop-in replacement for ListView, FlatList, and VirtualizedList.","archived":false,"fork":false,"pushed_at":"2020-12-11T08:36:21.000Z","size":1514,"stargazers_count":204,"open_issues_count":9,"forks_count":30,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-30T06:55:45.598Z","etag":null,"topics":["component","flatlist","immutable","immutablejs","listview","react-native","virtualizedlist"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cooperka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-08T14:49:51.000Z","updated_at":"2025-01-21T09:37:56.000Z","dependencies_parsed_at":"2022-08-15T07:50:50.505Z","dependency_job_id":null,"html_url":"https://github.com/cooperka/react-native-immutable-list-view","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/cooperka/react-native-immutable-list-view","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooperka%2Freact-native-immutable-list-view","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooperka%2Freact-native-immutable-list-view/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooperka%2Freact-native-immutable-list-view/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooperka%2Freact-native-immutable-list-view/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cooperka","download_url":"https://codeload.github.com/cooperka/react-native-immutable-list-view/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooperka%2Freact-native-immutable-list-view/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259763037,"owners_count":22907404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","flatlist","immutable","immutablejs","listview","react-native","virtualizedlist"],"created_at":"2025-06-14T21:08:25.967Z","updated_at":"2025-06-14T21:08:27.350Z","avatar_url":"https://github.com/cooperka.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Native Immutable ListView\n\n[![Build status](https://travis-ci.org/cooperka/react-native-immutable-list-view.svg?branch=master)](https://travis-ci.org/cooperka/react-native-immutable-list-view)\n[![npm downloads](https://img.shields.io/npm/dm/react-native-immutable-list-view.svg)](https://www.npmjs.com/package/react-native-immutable-list-view)\n[![npm version](https://img.shields.io/npm/v/react-native-immutable-list-view.svg)](https://www.npmjs.com/package/react-native-immutable-list-view)\n[![Latest GitHub tag](https://img.shields.io/github/tag/cooperka/react-native-immutable-list-view.svg)](https://github.com/cooperka/react-native-immutable-list-view)\n\n\u003cbr\u003e\n\n[![Logo](images/cover.png)](#README)\n\n\u003cbr\u003e\n\nDrop-in replacement for React Native's [`ListView`](https://facebook.github.io/react-native/docs/listview.html),\n[`FlatList`](https://facebook.github.io/react-native/docs/flatlist.html),\nand [`VirtualizedList`](https://facebook.github.io/react-native/docs/virtualizedlist.html).\n\n![ImmutableListView screenshot](example/screenshots/listview-cropped.png \"ImmutableListView screenshot\")\n\nIt supports [Immutable.js](https://facebook.github.io/immutable-js/) to give you faster performance and less headaches.\n\n## Motivation\n\n- Do you use Immutable data, only to write the same boilerplate over and over in order to display it?\n- Do you want to show 'Loading...', 'No results', and 'Error!' states in your lists?\n- Do you have nested objects in your state so a shallow diff won't cut it for pure rendering?\n- Do you want better performance while animating screen transitions?\n\nIf you answered yes to ANY of these questions, this project can help. Check out the examples below.\n\n## How it works\n\nFor FlatList and VirtualizedList:\n\n```jsx\n\u003cImmutableVirtualizedList\n  immutableData={this.state.listData}\n  renderItem={this.renderItem}\n/\u003e\n```\n\nFor ListView (deprecated as of React Native v0.59):\n\n```jsx\n\u003cImmutableListView\n  immutableData={this.state.listData}\n  renderRow={this.renderRow}\n/\u003e\n```\n\nThe screenshot above shows two different lists. The first uses this data:\n\n```js\nImmutable.fromJS({\n  'Section A': [\n    'foo',\n    'bar',\n  ],\n  'Section B': [\n    'fizz',\n    'buzz',\n  ],\n})\n```\n\nThe second list is even simpler:\n\n```js\nImmutable.Range(1, 100)\n```\n\nThere's an example app [here](https://github.com/cooperka/react-native-immutable-list-view/tree/master/example)\nif you'd like to see it in action.\n\n## Installation\n\n1. Install:\n    - Using [npm](https://www.npmjs.com/#getting-started): `npm install react-native-immutable-list-view --save`\n    - Using [Yarn](https://yarnpkg.com/): `yarn add react-native-immutable-list-view`\n\n2. Import it in your JS:\n\n    For FlatList and VirtualizedList:\n\n    ```js\n    import { ImmutableVirtualizedList } from 'react-native-immutable-list-view';\n    ```\n\n    For ListView:\n\n    ```js\n    import { ImmutableListView } from 'react-native-immutable-list-view/lib/ImmutableListView';\n    ```\n\n## Example usage -- replacing FlatList\n\nGoodbye, `keyExtractor` boilerplate!\n\n\u003e Note: This example diff looks much better on [GitHub](https://github.com/cooperka/react-native-immutable-list-view#example-usage----replacing-flatlist) than on npm's site.\n\u003e Red means delete, green means add.\n\n```diff\n-import { Text, View, FlatList } from 'react-native';\n+import { Text, View } from 'react-native';\n+import { ImmutableVirtualizedList } from 'react-native-immutable-list-view';\n\n import style from './styles';\n import listData from './listData';\n\n class App extends Component {\n\n   renderItem({ item, index }) {\n     return \u003cText style={style.row}\u003e{item}\u003c/Text\u003e;\n   }\n\n  render() {\n    return (\n      \u003cView style={style.container}\u003e\n         \u003cText style={style.welcome}\u003e\n           Welcome to React Native!\n         \u003c/Text\u003e\n-        \u003cFlatList\n-          data={listData}\n-          getItem={(items, index) =\u003e items.get(index)}\n-          getItemCount={(items) =\u003e items.size}\n-          keyExtractor={(item, index) =\u003e String(index)}\n+        \u003cImmutableVirtualizedList\n+          immutableData={listData}\n           renderItem={this.renderItem}\n         /\u003e\n      \u003c/View\u003e\n    );\n  }\n\n}\n```\n\n## Example usage -- replacing ListView\n\nYou can remove all that boilerplate in your constructor, as well as lifecycle methods like\n`componentWillReceiveProps` if all they're doing is updating your `dataSource`.\n`ImmutableListView` will handle all of this for you.\n\n\u003e Note: This example diff looks much better on [GitHub](https://github.com/cooperka/react-native-immutable-list-view#example-usage----replacing-listview) than on npm's site.\n\u003e Red means delete, green means add.\n\n```diff\n-import { Text, View, ListView } from 'react-native';\n+import { Text, View } from 'react-native';\n+import { ImmutableListView } from 'react-native-immutable-list-view/lib/ImmutableListView';\n\n import style from './styles';\n import listData from './listData';\n\n class App extends Component {\n\n-  constructor(props) {\n-    super(props);\n-\n-    const dataSource = new ListView.DataSource({\n-      rowHasChanged: (r1, r2) =\u003e r1 !== r2,\n-      sectionHeaderHasChanged: (s1, s2) =\u003e s1 !== s2,\n-    });\n-\n-    const mutableData = listData.toJS();\n-\n-    this.state = {\n-      dataSource: dataSource.cloneWithRowsAndSections(mutableData),\n-    };\n-  }\n-\n-  componentWillReceiveProps(newProps) {\n-    this.setState({\n-      dataSource: this.state.dataSource.cloneWithRows(newProps.listData),\n-    });\n-  }\n-\n   renderRow(rowData) {\n     return \u003cText style={style.row}\u003e{rowData}\u003c/Text\u003e;\n   }\n\n  renderSectionHeader(sectionData, category) {\n    return \u003cText style={style.header}\u003e{category}\u003c/Text\u003e;\n  }\n\n  render() {\n    return (\n      \u003cView style={style.container}\u003e\n         \u003cText style={style.welcome}\u003e\n           Welcome to React Native!\n         \u003c/Text\u003e\n-        \u003cListView\n-          dataSource={this.state.dataSource}\n+        \u003cImmutableListView\n+          immutableData={listData}\n           renderRow={this.renderRow}\n           renderSectionHeader={this.renderSectionHeader}\n         /\u003e\n      \u003c/View\u003e\n    );\n  }\n\n}\n```\n\n## Customization\n\nAll the props supported by React Native's underlying List are simply passed through, and should work exactly the same.\nYou can see all the [VirtualizedList props](https://facebook.github.io/react-native/docs/virtualizedlist.html#props)\nor [ListView props](https://facebook.github.io/react-native/docs/listview.html#props) on React Native's website.\n\nYou can customize the look of your list by implementing [`renderItem`](https://facebook.github.io/react-native/docs/flatlist.html#renderitem) for FlatList and VirtualizedList\nor [`renderRow`](https://facebook.github.io/react-native/docs/listview.html#renderrow) for ListView.\n\nHere are the additional props that `ImmutableVirtualizedList` and `ImmutableListView` accept:\n\n| Prop name | Data type | Default value? | Description |\n|-----------|-----------|----------------|-------------|\n| `immutableData` | Any [`Immutable.Iterable`](https://facebook.github.io/immutable-js/docs/#/Iterable/isIterable) | Required. | The data to render. See below for some examples. |\n| `rowsDuringInteraction` | `number` | `undefined` | How many rows of data to initially display while waiting for interactions to finish (e.g. Navigation animations). |\n| `sectionHeaderHasChanged` | `func` | `(prevSectionData, nextSectionData) =\u003e false` | Only needed if your section header is dependent on your row data (uncommon; see [`ListViewDataSource`'s constructor](https://facebook.github.io/react-native/docs/listviewdatasource.html#constructor) for details). |\n| `renderEmpty` | `string` or `func` | `undefined` | 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 **lost**. Most of the time you should use `renderEmptyInList` instead. |\n| `renderEmptyInList` | `string` 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](#loading--empty--error-states) for more details. |\n\nAlso see [React Native's `FlatListExample`](https://github.com/facebook/react-native/blob/master/RNTester/js/FlatListExample.js)\nfor more inspiration.\n\n## Methods\n\nMethods such as `scrollToEnd` are passed through just like the props described above.\nYou can read about them [here](https://facebook.github.io/react-native/docs/listview.html#methods) for ListView\nor [here](https://facebook.github.io/react-native/docs/virtualizedlist.html#methods) for FlatList and VirtualizedList.\n\nThe references to the raw `VirtualizedList` or `ListView` component are available via `getVirtualizedList()` or `getListView()`.\nThese references allow you to access any other methods on the underlying List that you might need.\n\n## How to format your data\n\n`ImmutableListView` accepts several [standard formats](https://facebook.github.io/react-native/releases/0.37/docs/listviewdatasource.html#constructor)\nfor list data. Here are some examples:\n\n#### List\n\n```js\n[rowData1, rowData2, ...]\n```\n\n#### Map of Lists\n\n```js\n{\n    section1: [\n        rowData1,\n        rowData2,\n        ...\n    ],\n    ...\n}\n```\n\n#### Map of Maps\n\n```js\n{\n    section1: {\n        rowId1: rowData1,\n        rowId2: rowData2,\n        ...\n    },\n    ...\n}\n```\n\nTo try it out yourself, you can use the [example app](https://github.com/cooperka/react-native-immutable-list-view/tree/master/example)!\n\nSupport is coming soon for section headers with `ImmutableVirtualizedList` too, similar to [`SectionList`](https://facebook.github.io/react-native/docs/sectionlist.html).\nSee [PR #34](https://github.com/cooperka/react-native-immutable-list-view/pull/34).\n\n## Loading / Empty / Error states\n\nThe optional `renderEmptyInList` prop takes a string and renders an Immutable List displaying the text you specified.\nBy default, this text is simply `No data.`, but you can customize this based on your state. For example:\n\n```jsx\nrender() {\n  const emptyText = this.state.isLoading\n    ? \"Loading...\"\n    : this.state.errorMsg\n      ? \"Error!\"\n      : \"No data.\";\n\n  return (\n    \u003cImmutableVirtualizedList\n      immutableData={this.state.listData}\n      renderItem={this.renderItem}\n      renderEmptyInList={emptyText}\n    /\u003e\n  );\n}\n```\n\nThe empty list will receive all the same props as your normal list, so things like pull-to-refresh will still work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcooperka%2Freact-native-immutable-list-view","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcooperka%2Freact-native-immutable-list-view","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcooperka%2Freact-native-immutable-list-view/lists"}