# iscroll-react

> Encapsulating iScroll as a react component

Latest version **1.0.3** (published 2016-05-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install iscroll-react
pnpm add iscroll-react
yarn add iscroll-react
bun add iscroll-react
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2016-05-26 |
| First published | 2016-05-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Author | swenyang |
| Maintainers | swenyang |
| Keywords | react, iscroll, scroll, async, pull, down, to, refresh |

## Links

- npm: https://www.npmjs.com/package/iscroll-react
- Repository: https://github.com/swenyang/react-iscroll
- Homepage: https://github.com/swenyang/react-iscroll#readme
- Issues: https://github.com/swenyang/react-iscroll/issues
- npm.io page: https://npm.io/package/iscroll-react

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.3 (latest) — 2016-05-26
- 1.0.2 — 2016-05-16
- 1.0.1 — 2016-05-16
- 1.0.0 — 2016-05-15

## README

# React-IScroll
Encapsulating iScroll as a react component

## [iScroll][]
iScroll is a high performance, small footprint, dependency free, multi-platform javascript scroller.

## [React][]
A declarative, efficient, and flexible JavaScript library for building user interfaces.

## React-IScroll
Since [iScroll][] doesn't provide [React][] version, I found it's very inconvenient to make iScroll work with React. So I decided to write a React component encapsulating iScroll.

## How to Use
Install from npm:
```js
npm i iscroll-react
```
Use React-IScroll in your project:
```js
import IScroll from "iscroll-react"
import React, { Component } from 'react'
import iscroll from "iscroll"

class SomeComponent extends Component {
	render() {
		return <IScroll iScroll={iscroll}>
			These contents can be scrolled.
		</IScroll>
	}
}
```

## Props
You can provide props for React-IScroll to use some features.
- `iScroll`

	*Required*, iScroll library, see [here](http://iscrolljs.com/#iscroll-versions) for different versions of iScroll. Remember that if you use pull-down-to-refresh feature, please provide `iscroll-probe.js`.

- `options`

	iScroll options, see [here](http://iscrolljs.com/#configuring) for all options. It's directly provided to iScroll. Note that if you are using pull-down-to-refresh feature, options will be appended an attribute: `probeType: 2`

	Since you may use React-IScroll many times in your project, setting iScroll options many times would be redundant. To simplify this, I added a `setDefaultIScrollOptions` function. Initialized once, iScroll will copy the default props on construct.

	```js
	import {setDefaultIScrollOptions}  from "iscroll-react"

	setDefaultIScrollOptions({
	    scrollbars: true,
	    mouseWheel: true,
	    shrinkScrollbars: "scale",
	    fadeScrollbars: true,
	    click: true,
	})
	```

- iScroll events

	iScroll itself provide some custom events, here I just wrapped them. All below events will be called with the iScroll instance, e.g. `onBeforeScrollStart(iScrollInstance)`, you can do whatever like reading iScroll properties or calling functions.
	- `onBeforeScrollStart` <= `beforeScrollStart`
	- `onScrollCancel` <= `scrollCancel`
	- `onScrollStart` <= `scrollStart`
	- `onScroll` <= `scroll`
	- `onScrollEnd` <= `scrollEnd`
	- `onFlick` <= `flick`
	- `onZoomStart` <= `zoomStart`
	- `onZoomEnd` <= `zoomEnd`

- `alwaysScroll`

	By setting this value to true, the scroller can be scrolled even the scroller's height is smaller than the wrappers. Default is `true`.

- `dynamicTop`

	Calculate the wrapper's top dynamically. Default is `false`.

- `dynamicBottomFunc`

	Calculate the wrapper's bottom dynamically, since we can't use the wrapper's height for calculation, so I exposed a function.

	*Notes: because React-IScroll is mounted before the parent, if you want to use this feature, make sure to call `updateIScroll()` when the parent is mounted.*

- `wrapperStyle`

	If your wrapper's position is static, using this option the fast set wrapper's CSS attributes: `top`, `bottom`, `left` and `right`. If not specified, all will be `0`.

	*Note that `top` and `bottom` might be override by `dynamicTop` and `dynamicBottomFunc`.*

- `pullDownToRefresh`

	If you want to use pull-down-to-refresh feature, set this value. This option has sub props:

	- `labelInactive`

		Node showed when scroller is pulled down but not active. You can provide either your React Component or simply a string.

	- `labelActive`

		Node showed when pulldown is active. Provide either a React Component or string.

	- `appearDistance`

		If scroller's pull-down distance exceeds this value, `labelInactive` will be showed. Default is `20`.

	- `activeDistance`

		If scroller's pull-down distance exceeds this value, `labelActive` will be showed. Default is `55`.

		*Notes: if you have set the page's viewport, the above two values should be adjusted to get best experience.*

	- `onRefresh`

		*Required*, When touch is released, this function will be called if the pulldown is active.

## Functions
- `IScroll.updateIScroll`

	Update iScroll by calling `iScrollInstance.refresh()` and calculate wrapper's positions. Since React-IScroll don't know children updated or not, you might need to call this function manually, e.g. on async data loaded, or on children's state changed.

	```js
	import IScroll from "iscroll-react"
	import React, { Component } from 'react'
	import iscroll from "iscroll"

	class SomeComponent extends Component {
	    componentDidUpdate() {
	        if (this.refs.iscroll) {
	            this.refs.iscroll.updateIScroll()
	        }
	    }

		render() {
			return <IScroll iScroll={iscroll} ref="iscroll">
				These contents can be scrolled.
			</IScroll>
		}
	}
	```

- `IScroll.iScrollInstance`

    Used to get the iScroll instance, if initialized.

- `setDefaultIScrollOptions`

	As is explained above, it's used to set iScroll's default options.

## Examples
Clone this repo and run `npm run examples`, then navigate to <http://localhost:8080/> to see examples.
- Basic Scroll
- Always Scroll
- Dynamic Top
- Dynamic Bottom
- Scroller's Height Changes
- Async Request & Pull Down to Refresh

[iScroll]: http://iscrolljs.com/
[React]: https://github.com/facebook/react/

---
_Source: https://npm.io/package/iscroll-react · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._