react-native-recyclerview-list
v0.3.4
Published
A RecyclerView implementation for React Native
Downloads
47
Maintainers
Readme
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
import RecyclerviewList, { DataSource } from 'react-native-recyclerview-list';
// Take an array as data
var 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 = new DataSource(rawdata, (item, index) => item.id);
...
// Render the list
render() {
return (
<RecyclerviewList
style={{ flex: 1 }}
dataSource={dataSource}
renderItem={({item, index}) => (
<Text>{item.text} - {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.