react-native-recyclerview-list
A RecyclerView implementation for ReactNative, that overcomes some limitations of FlatList
, VirtualizedList
and ListView
.
Supported React Native Versions
Component Version | RN Versions |
---|---|
0.1.x | 0.45, 0.46 |
0.2.0 - 0.2.2 | 0.47, 0.48 |
0.2.3 - latest | >= 0.49 |
Features
- Supports native animation during adding or removal of items (as the classic RecyclerView does)
- Add items at the top with no scrolling issue: it means that you can easily implement an infinite scroll in both directions
- Scroll to whatever index you want: even if you don't know the exact dimensions of your rendered items, you can scroll to any index without any scrolling issue
- Control the scrolling velocity: the
velocity
param in thescrollToIndex
method is exactly for this - Initial scroll index: specify the scroll position at startup, and there will be no flicker
- Low memory usage: it renders just the visible items plus some extra items around
- Supports both scroll direction: use the
inverted
prop to invert the scroll direction
Caveats
- It's just for Android.
- Just vertical linear layout. No fancy layouts as grid.
Getting started
$ npm install react-native-recyclerview-list --save
Mostly automatic installation
$ react-native link react-native-recyclerview-list
Manual installation
Android
- Open up
android/app/src/main/java/[...]/MainActivity.java
- Add
import com.github.godness84.RNRecyclerViewList.RNRecyclerviewListPackage;
to the imports at the top of the file - Add
new RNRecyclerviewListPackage()
to the list returned by thegetPackages()
method
- Append the following lines to
android/settings.gradle
:include ':react-native-recyclerview-list' project(':react-native-recyclerview-list').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-recyclerview-list/android')
- Insert the following lines inside the dependencies block in
android/app/build.gradle
:compile project(':react-native-recyclerview-list')
Usage
; // Take an array as datavar rawdata = id: 1 text: 'Item #1' id: 2 text: 'Item #2' id: 3 text: 'Item #3' id: 4 text: 'Item #4' id: 5 text: 'Item #5' ; // Wrap your data in a DataSource.// The second argument is the 'keyExtractor' function that returns the unique key of the item.var dataSource = rawdata itemid; ... // Render the list { return <RecyclerviewList style= flex: 1 dataSource=dataSource renderItem= <Text>itemtext - index</Text> /> ;}
Props
Prop name | Description | Type | Default value |
---|---|---|---|
style |
Style for the list | object | {} |
dataSource |
The datasource that contains the data to render | DataSource | none |
windowSize |
Number of items to render at the top (and bottom) of the visible items | int | 30 |
initialListSize |
Number of items to render at startup. | int | 10 |
initialScrollIndex |
Index of the item to scroll at startup | int | none |
initialScrollOffset |
Offset of the scroll position at startup | int | none |
inverted |
Reverses the scrolling direction; the first model from the data source is rendered at the bottom | boolean | false |
itemAnimatorEnabled |
Whether animates items when they are added or removed | boolean | true |
ListHeaderComponent |
Component to render as header | component | none |
ListFooterComponent |
Component to render as footer | component | none |
ListEmptyComponent |
Component to render in case of no items | component | none |
ItemSeparatorComponent |
Component to render as item separator | component | none |
onVisibleItemsChange |
Called when the first and last index of the visible items change | function | none |
onScroll |
Called when the list is scrolling | function | none |
onScrollBeginDrag |
Called when the user starts scrolling | function | none |
onScrollEndDrag |
Called when the user stops dragging | function | none |
Methods
Method name | Params | Description |
---|---|---|
scrollToIndex |
{ index, animated, velocity, viewPosition, viewOffset } |
Scroll the list to the index ed item such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle. viewOffset is a fixed number of pixels to offset the final target position. It can be animated . velocity is the amount of milliseconds per inch. |
scrollToEnd |
{ animated, velocity } |
Scroll to the end of the list. It can be animated . velocity is the amount of milliseconds per inch. |
DataSource
It wraps your array, giving you some useful methods to update the data.
Methods
Method name | Params | Description |
---|---|---|
push |
item | Add an item to the end of the array |
unshift |
item | Add an item to the beginning of the array |
splice |
index, deleteCount, ...items | Equals to Array.prototype.splice |
set |
index, item | Set the item at the specified index |
get |
index | Returns the item at the specified index |
size |
Returns the length of the array | |
setDirty |
Forces the RecyclerViewList to render again the visible items | |
moveUp |
index | Move the item up of 1 position |
moveDown |
index | Move the item down of 1 position |
How to contribute to this library
Directory structure
.
├── example
│ ├── __tests__
│ ├── android
│ ├── ios
│ ├── app.json
│ ├── index.android.js
│ ├── index.ios.js
│ └── package.json
├── android
│ └── src
│ └── main
│ └── java
│ └── com
│ └── github
│ └── godness84
│ └── RNRecyclerViewList
│ ├── ContentSizeChangeEvent.java
│ ├── NotAnimatedItemAnimator.java
│ ├── RNRecyclerviewListModule.java
│ ├── RNRecyclerviewListPackage.java
│ ├── RecyclerViewBackedScrollView.java
│ ├── RecyclerViewBackedScrollViewManager.java
│ ├── RecyclerViewItemView.java
│ ├── RecyclerViewItemViewManager.java
│ └── VisibleItemsChangeEvent.java
├── src
│ ├── DataSource.js
│ └── RecyclerViewList.js
├── index.js
├── package.json
├── LICENSE.md
└── README.md
If you have to change Android native code, you must have a look at the code in library/android/src/main/java/com/github/godness84/RNRecyclerViewList
. Depending of your changes you might have to change the Javascript interface as well in library/src/
.
Run the example app
Make sure to have an emulator running or an Android device connected, and then:
$ cd example/
$ react-native run-android
This will build the Android library (via gradle
) and example app, then launch the main example activity on your connected device and run the Metro bundler at the same time.