A pull-to-refresh ListView which shows a loading spinner while your data reloads
Deprecated: now you can use the built-in RefreshControl instead.
In action (from ReactNativeHackerNews):
Note: these are the docs for the 2.x branch, currently in beta. If you are looking for the docs for a 1.x version, see the 1.x branch.
You can install the latest beta with npm install react-native-refreshable-listview@next
Replace a ListView with a RefreshableListView to add pulldown-to-refresh functionality. Accepts the same props as ListView, plus a few extras (see the props definitions below).
var React = require('react-native')
var {Text, View, ListView} = React
var RefreshableListView = require('react-native-refreshable-listview')
var ArticleStore = require('../stores/ArticleStore')
var StoreWatchMixin = require('./StoreWatchMixin')
var ArticleView = require('./ArticleView')
var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2}) // assumes immutable objects
var ArticlesScreen = React.createClass({
mixins: [StoreWatchMixin],
getInitialState() {
return {dataSource: ds.cloneWithRows(ArticleStore.all())}
},
getStoreWatches() {
this.watchStore(ArticleStore, () => {
this.setState({dataSource: ds.cloneWithRows(ArticleStore.all())})
})
},
reloadArticles() {
// returns a Promise of reload completion
// for a Promise-free version see ControlledRefreshableListView below
return ArticleStore.reload()
},
renderArticle(article) {
return <ArticleView article={article} />
},
render() {
return (
<RefreshableListView
dataSource={this.state.dataSource}
renderRow={this.renderArticle}
loadData={this.reloadArticles}
refreshDescription="Refreshing articles"
/>
)
}
})loadData: func.isRequiredA function returning a Promise or taking a callback, invoked upon pulldown. The refreshing indicator (spinner) will show until the Promise resolves or the callback is called.refreshDescription: oneOfType([string, element])Text/element to show alongside spinner. If a customrefreshingIndicatorComponentis used this value will be passed as itsdescriptionprop.refreshingIndicatorComponent: oneOfType([func, element])Content to show in list header when refreshing. Can be a component class or instantiated element. Defaults toRefreshableListView.RefreshingIndicator. You can easily customise the appearance of the indicator by passing in a customised<RefreshableListView.RefreshingIndicator />, or provide your own entirely custom content to be displayed.minDisplayTime: numberMinimum time the spinner will show for.minBetweenTime: numberMinimum time after a refresh before another refresh can be performed.minPulldownDistance: numberMinimum distance (in px) which the list has to be scrolled off the top to trigger a refresh.ignoreInertialScroll: boolRequire the user to be actually touching the screen when the pulldown distance exceedsminPulldownDistanceto trigger a refresh (eg. not just inertially scrolling off the top). Defaults totrue.onScroll: funcAn event handler for theonScrollevent which will be chained after the one defined by theRefreshableListView.scrollEventThrottle: numberHow oftenListViewproduces scroll events, in ms. Defaults to a fairly low value, try setting it higher if you encounter performance issues. Keep in mind that a higher value will make the pulldown-to-refresh behaviour less responsive.colors: array of stringsColors to be used for pull to refresh indicator in AndroidprogressBackgroundColor: stringColor to be used for pull to refresh indicator background in Android
Low level component used by RefreshableListView. Use this directly if you want
to manually control the refreshing status (rather than using a Promise).
This component is more suitable for use in a Redux-style connected component.
var React = require('react-native')
var {Text, View, ListView} = React
var {ControlledRefreshableListView} = require('react-native-refreshable-listview')
var ArticleView = require('./ArticleView')
var ds = new ListView.DataSource({rowHasChanged: (r1, r2) => r1 !== r2}) // assumes immutable objects
var ArticlesScreen = React.createClass({
propTypes: {
// eg. props mapped from store state
articles: React.PropTypes.array.isRequired,
isRefreshingArticles: React.PropTypes.bool.isRequired,
// eg. a bound action creator
refreshArticles: React.PropTypes.func.isRequired,
},
getInitialState() {
return {dataSource: ds.cloneWithRows(this.props.articles)}
},
componentWillReceiveProps(nextProps) {
if (this.props.articles !== nextProps.articles) {
this.setState({dataSource: ds.cloneWithRows(nextProps.articles)})
}
},
renderArticle(article) {
return <ArticleView article={article} />
},
render() {
return (
<ControlledRefreshableListView
dataSource={this.state.dataSource}
renderRow={this.renderArticle}
isRefreshing={this.props.isRefreshingArticles}
onRefresh={this.props.refreshArticles}
refreshDescription="Refreshing articles"
/>
)
}
})onRefresh: func.isRequiredCalled when user pulls listview down to refresh.isRefreshing: bool.isRequiredWhether or not to show the refreshing indicator.refreshDescription: oneOfType([string, element])SeeRefreshableListViewrefreshingIndicatorComponent: oneOfType([func, element])SeeRefreshableListViewminPulldownDistance: numberSeeRefreshableListViewignoreInertialScroll: boolSeeRefreshableListViewonScroll: funcSeeRefreshableListViewscrollEventThrottle: numberSeeRefreshableListView
Component with activity indicator to be displayed in list header when refreshing.
(also exposed as ControlledRefreshableListView.RefreshingIndicator)
description: oneOfType([string, element])Text/element to show alongside spinner.stylesheet: objectA stylesheet object which overrides one or more of the styles defined in the RefreshingIndicator stylesheet.activityIndicatorComponent: oneOfType([func, element])The spinner to display. Defaults to<ActivityIndicatorIOS />.
Aliases of ListView.DataSource, for convenience.
Your first option is to style the default RefreshingIndicator:
var indicatorStylesheet = StyleSheet.create({
wrapper: {
backgroundColor: 'red',
height: 60,
marginTop: 10,
},
content: {
backgroundColor: 'blue',
marginTop: 10,
height: 60,
},
})
<RefreshableListView
refreshingIndicatorComponent={
<RefreshableListView.RefreshingIndicator stylesheet={indicatorStylesheet} />
}
/>Alternatively, you can provide a custom RefreshingIndicator:
var MyRefreshingIndicator = React.createClass({
render() {
return (
<View>
<MySpinner />
<Text>{this.props.description}</Text>
</View>
)
},
})
<RefreshableListView refreshingIndicatorComponent={MyRefreshingIndicator} />
// or
<RefreshableListView refreshingIndicatorComponent={<MyRefreshingIndicator />} />-
2.0.0-beta4
- added Android support! (@maraujop)
-
2.0.0-beta3
- fixed proptype warnings from internal component
- adjusted default styling of refreshing indicator
-
2.0.0-beta2
- pulling down now reveals refreshing indicator behind current view, rather than the refreshing indicator moving down from the top of the screen
renderHeaderWrapperis no longer used- fixed infinite refreshing when pulled down
-
1.2.0
- deprecated
renderHeaderin favour ofrenderHeaderWrapperas some developers seemed to be confused by the fact that arenderHeaderhandler for a standardListViewwill not automatically just work with this component, but rather needs to be modified as described in the documentation. The new proprenderHeaderWrapperworks identically to the previous one, however hopefully now it is named differently it will be more apparent that its behaviour is not the same as withListView. TherenderHeaderprop will be removed in 2.0.
- deprecated
-
1.1.0
- added behaviour to ignore inertial scrolling (@dhrrgn)
- exposed props: ignoreInertialScroll, scrollEventThrottle
-
1.0.0
- Split RefreshableListView into 3 parts:
- RefreshableListView handles 'refreshing' state by invoking 'loadData' callback and waiting for resolution.
- ControlledRefreshableListView handles rendering of ListView header, depending on isRefreshing prop. Calls onRefresh handler when pulldown-to-refresh scroll motion occurs.
- RefreshingIndicator is the component rendered in the header of the ListView when refreshing. Pass in a customised version of this (or a completely different component) to RefreshableListView or ControlledRefreshableListView if you want to customise refresh indicator appearance.
- Added Jest unit tests
- Split RefreshableListView into 3 parts:
-
0.3.0 added minPulldownTime & minBetweenTime props, fixed bug where refresh could happen twice
-
0.2.0 added support for ListView props setNativeProps and getScrollResponder (@almost & @sscotth)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent