Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jsdf/react-native-refreshable-listview

Deprecated. A pull-to-refresh ListView which shows a loading spinner while your data reloads
https://github.com/jsdf/react-native-refreshable-listview

Last synced: about 1 month ago
JSON representation

Deprecated. A pull-to-refresh ListView which shows a loading spinner while your data reloads

Lists

README 

        
# React Native RefreshableListView

A pull-to-refresh ListView which shows a loading spinner while your data reloads



*Deprecated*: now you can use the built-in [RefreshControl](https://facebook.github.io/react-native/docs/refreshcontrol.html) instead.



![Build Status](https://api.travis-ci.org/jsdf/react-native-refreshable-listview.svg)



In action (from [ReactNativeHackerNews](https://github.com/jsdf/ReactNativeHackerNews)):



![React Native Hacker News](http://i.imgur.com/gVmrxDe.png)



## Usage



**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](https://github.com/jsdf/react-native-refreshable-listview/tree/1.x).



You can install the latest beta with `npm install react-native-refreshable-listview@next`



### RefreshableListView

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).



```js

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 

  },

  render() {

    return (

      

    )

  }

})

```



#### Props



- `loadData: func.isRequired`

  A 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 custom 

  `refreshingIndicatorComponent` is used this value will be passed as its 

  `description` prop.

- `refreshingIndicatorComponent: oneOfType([func, element])`

  Content to show in list header when refreshing. Can be a component class or 

  instantiated element. Defaults to `RefreshableListView.RefreshingIndicator`.

  You can easily customise the appearance of the indicator by passing in a

  customised ``, or provide your own

  entirely custom content to be displayed.

- `minDisplayTime: number`

  Minimum time the spinner will show for.

- `minBetweenTime: number`

  Minimum time after a refresh before another refresh can be performed.

- `minPulldownDistance: number`

  Minimum distance (in px) which the list has to be scrolled off the top to 

  trigger a refresh.

- `ignoreInertialScroll: bool`

  Require the user to be actually touching the screen when the pulldown distance 

  exceeds `minPulldownDistance` to trigger a refresh (eg. not just inertially 

  scrolling off the top). Defaults to `true`.

- `onScroll: func`

  An event handler for the `onScroll` event which will be chained after the one

  defined by the `RefreshableListView`.

- `scrollEventThrottle: number`

  How often `ListView` produces 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 strings`

  Colors to be used for pull to refresh indicator in Android

- `progressBackgroundColor: string`

  Color to be used for pull to refresh indicator background in Android



### ControlledRefreshableListView

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](https://github.com/rackt/redux)-style connected component.



```js

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 

  },

  render() {

    return (

      

    )

  }

})

```



#### Props

- `onRefresh: func.isRequired`

  Called when user pulls listview down to refresh.

- `isRefreshing: bool.isRequired`

  Whether or not to show the refreshing indicator.

- `refreshDescription: oneOfType([string, element])`

  *See `RefreshableListView`*

- `refreshingIndicatorComponent: oneOfType([func, element])`

  *See `RefreshableListView`*

- `minPulldownDistance: number`

  *See `RefreshableListView`*

- `ignoreInertialScroll: bool`

  *See `RefreshableListView`*

- `onScroll: func`

  *See `RefreshableListView`*

- `scrollEventThrottle: number`

  *See `RefreshableListView`*



### RefreshableListView.RefreshingIndicator

Component with activity indicator to be displayed in list header when refreshing.

(also exposed as `ControlledRefreshableListView.RefreshingIndicator`)



#### Props



- `description: oneOfType([string, element])`

  Text/element to show alongside spinner.

- `stylesheet: object`

  A stylesheet object which overrides one or more of the styles defined in the 

  [RefreshingIndicator stylesheet](lib/RefreshingIndicator.js).

- `activityIndicatorComponent: oneOfType([func, element])`

  The spinner to display. Defaults to ``.



### RefreshableListView.DataSource, ControlledRefreshableListView.DataSource

Aliases of `ListView.DataSource`, for convenience.



## Howto



### Customise the refresh indicator (spinner)



Your first option is to style the default RefreshingIndicator:



```js

var indicatorStylesheet = StyleSheet.create({

  wrapper: {

    backgroundColor: 'red',

    height: 60,

    marginTop: 10,

  },

  content: {

    backgroundColor: 'blue',

    marginTop: 10,

    height: 60,

  },

})



  }

/>

```



Alternatively, you can provide a custom RefreshingIndicator:



```js

var MyRefreshingIndicator = React.createClass({

  render() {

    return (

      

        

        {this.props.description}

      

    )

  },

})



// or

} />

```



## Changelog



- **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

  - `renderHeaderWrapper` is no longer used 

  - fixed infinite refreshing when pulled down



- **1.2.0**

  - deprecated `renderHeader` in favour of `renderHeaderWrapper` as some 

  developers seemed to be confused by the fact that a `renderHeader` handler 

  for a standard `ListView` will not automatically *just work* with this component,

  but rather needs to be modified as described in the documentation. The new prop

  `renderHeaderWrapper` works 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 with `ListView`. The `renderHeader` prop will be removed in 2.0.

- **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

- **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)