react-native-swiper

The best Swiper component for React Native.

Roadmap

V2

Improve performance
Landscape mode

Please track in milestones:v2

Contribute code to branch:Android and branch:V2

Provide creative in issues

V1

Changelogs

[1.5.0]
- Improve develop workflow for support watch & use real pkg name in examples
- Update examples for support React-native 0.33 + Xcode8 + ios10 + iphone7
- Switch to standard code style
- Rewrite source code with ES6 syntex
- Cancel transform the source code when publish
- Add a demo for loadMinimal + lazyload
- Add a demo for multi-images viewer
[1.4.11]
- Adds loadMinimalSize property
[1.4.10]
- Adds loadMinimal to api (lazyloading-esque)
[1.4.9]
- Adds extra check for title
[1.4.8]
- Fixes loop and autoplay bugs in android
[1.4.7]
- Don't attempt to mutate this.props
- Fixes examples links
- Adds drag end handling to always reset state.isScrolling
- Fixes float calculation error
[1.4.6]
- refactors examples
- prevents mutation of this.props
- fixes android index loop issue
[1.4.5]
- renames scrollTo() to scrollBy()
- image index is now always an integer
- prevents parent state updates from reseting index counter
- fixes issue with scrolling not working sometimes
[1.4.4]
- Support for React Native latest(^0.26.0)
- Updates examples to work with react-native-swiper 1.4.4
- Examples now run on Android (some are still buggy, needs more work)
- Removes old examples folder
[1.4.3]
- Fixed auto play issue when only a child view
[v1.4.0]
- Support for React Native latest(^0.17.0) & Upgrade examples base on Xcode 7.2 / React Native 0.17.0
- Upgrade build tool to babel6
- Add missing deps react-timer-mixin
- 1f8643a Move Dimensions import to deconstructed React import for react-native (@thanks @jedrekk).
- e28af9b Support index property in combination with loop property (@thanks @almost).
- 6c832d fix warnings about keys for dots (@thanks @sunnylqm).
- 8de1afc Changes to make the example work in xcode 7 (@thanks @allomov).
[v1.3.0]
- 8d6d75c inject state in ScrollResponders (@thanks @smothers).
[v1.2.2]
- 890c0ce ensure onMomentumScrollEnd synchronous update index.
[v1.2.0]
- 838b24c Re-design a loop model for avoid img flickering.
- 9cb91c5 fixes #7 onMomentumScrollEnd lost event param. (thanks @smothers)
[v1.1.1]
- 21f0b00 fixes #6 a define-propType error. (thanks @benjamingeorge)
[v1.1.0]
- 44ec630 fixes #4 onMoementumScrollEnd gets overridden. (thanks @subpublicanders)
- 5de06a7 New prop: renderPagination. (thanks @aksonov)
[v1.0.4]
- 21cb373 fixes #2 Solve the problem of installation. (thanks @jamwaffles)
[v1.0.3]
- 0f796f3 fixes #1 Two 'horizontal' in propTypes. (thanks @MacyzZ)

Show Cases

Try these cases by yourself very easy, Just open examples/ios/swiper.xcodeproj in Xcode, then press Cmd + R; you may edit examples/index.ios.js for switch cases.

with react-native-photo-view

Installation

$ npm i react-native-swiper --save

Basic Usage

Install react-native first

$ npm i react-native -g

Initialization of a react-native project

$ react-native init myproject

Then, edit myproject/index.ios.js, like this:

import React, { Component } from 'react';
import {
  AppRegistry,
  StyleSheet,
  Text,
  View
} from 'react-native';

import Swiper from 'react-native-swiper';

var styles = StyleSheet.create({
  wrapper: {
  },
  slide1: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#9DD6EB',
  },
  slide2: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#97CAE5',
  },
  slide3: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#92BBD9',
  },
  text: {
    color: '#fff',
    fontSize: 30,
    fontWeight: 'bold',
  }
})

var swiper = React.createClass({
  render: function() {
    return (
      <Swiper style={styles.wrapper} showsButtons={true}>
        <View style={styles.slide1}>
          <Text style={styles.text}>Hello Swiper</Text>
        </View>
        <View style={styles.slide2}>
          <Text style={styles.text}>Beautiful</Text>
        </View>
        <View style={styles.slide3}>
          <Text style={styles.text}>And simple</Text>
        </View>
      </Swiper>
    )
  }
})

AppRegistry.registerComponent('myproject', () => swiper);

Properties

Basic

Prop	Default	Type	Description
horizontal	true	`bool`	If `true`, the scroll view's children are arranged horizontally in a row instead of vertically in a column.
loop	true	`bool`	Set to `false` to disable continuous loop mode.
index	0	`number`	Index number of initial slide.
showsButtons	false	`bool`	Set to `true` make control buttons visible.
autoplay	false	`bool`	Set to `true` enable auto play mode.

Custom basic style & content

Prop	Default	Type	Description
width	-	`number`	If no specify default enable fullscreen mode by `flex: 1`.
height	-	`number`	If no specify default fullscreen mode by `flex: 1`.
style	{...}	`style`	See default style in source.
loadMinimal	false	`bool`	Only load current index slide , `loadMinimalSize` slides before and after.
loadMinimalSize	1	`number`	see `loadMinimal`

Pagination

Prop	Default	Type	Description
showsPagination	true	`bool`	Set to `true` make pagination visible.
paginationStyle	{...}	`style`	Custom styles will merge with the default styles.
renderPagination	-	`function`	Complete control how to render pagination with three params (`index`, `total`, `context`) ref to `this.state.index` / `this.state.total` / `this`, For example: show numbers instead of dots.
dot	`<View style={{backgroundColor:'rgba(0,0,0,.2)', width: 8, height: 8,borderRadius: 4, marginLeft: 3, marginRight: 3, marginTop: 3, marginBottom: 3,}} />`	`element`	Allow custom the dot element.
activeDot	`<View style={{backgroundColor: '#007aff', width: 8, height: 8, borderRadius: 4, marginLeft: 3, marginRight: 3, marginTop: 3, marginBottom: 3,}} />`	`element`	Allow custom the active-dot element.

Autoplay

Prop	Default	Type	Description
autoplay	true	`bool`	Set to `true` enable auto play mode.
autoplayTimeout	2.5	`number`	Delay between auto play transitions (in second).
autoplayDirection	true	`bool`	Cycle direction control.

Control buttons

Prop	Default	Type	Description
showsButtons	true	`bool`	Set to `true` make control buttons visible.
buttonWrapperStyle	`{backgroundColor: 'transparent', flexDirection: 'row', position: 'absolute', top: 0, left: 0, flex: 1, paddingHorizontal: 10, paddingVertical: 10, justifyContent: 'space-between', alignItems: 'center'}`	`style`	Custom styles.
nextButton	`<Text style={styles.buttonText}>›</Text>`	`element`	Allow custom the next button.
prevButton	`<Text style={styles.buttonText}>‹</Text>`	`element`	Allow custom the prev button.

Props of Children

Prop	Default	Type	Description
style	{...}	`style`	Custom styles will merge with the default styles.
title	{...}	`element`	If this parameter is not specified, will not render the title.

Basic props of `<ScrollView />`

Prop	Default	Type	Description
horizontal	true	`bool`	If `true`, the scroll view's children are arranged horizontally in a row instead of vertically in a column.
pagingEnabled	true	`bool`	If true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination.
showsHorizontalScrollIndicator	false	`bool`	Set to `true` if you want to show horizontal scroll bar.
showsVerticalScrollIndicator	false	`bool`	Set to `true` if you want to show vertical scroll bar.
bounces	false	`bool`	If `true`, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. If `false`, it disables all bouncing even if the alwaysBounce* props are true.
scrollsToTop	false	`bool`	If true, the scroll view scrolls to top when the status bar is tapped.
removeClippedSubviews	true	`bool`	If true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This canimprove scrolling performance on long lists.
automaticallyAdjustContentInsets	false	`bool`	Set to `true` if you need adjust content insets automation.

@see: http://facebook.github.io/react-native/docs/scrollview.html

Supported ScrollResponder

Prop	Params	Type	Description
onScrollBeginDrag	`e` / `state` / `context`	`function`	When animation begins after letting up
onMomentumScrollEnd	`e` / `state` / `context`	`function`	Makes no sense why this occurs first during bounce
onTouchStartCapture	`e` / `state` / `context`	`function`	Immediately after `onMomentumScrollEnd`
onTouchStart	`e` / `state` / `context`	`function`	Same, but bubble phase
onTouchEnd	`e` / `state` / `context`	`function`	You could hold the touch start for a long time
onResponderRelease	`e` / `state` / `context`	`function`	When lifting up - you could pause forever before * lifting

Note: each ScrollResponder be injected with two params: state and context, you can get state and context(ref to swiper's this) from params, for example:

var swiper = React.createClass({
  _onMomentumScrollEnd: function (e, state, context) {
    console.log(state, context.state)
  },
  render: function() {
    return (
      <Swiper style={styles.wrapper}
      onMomentumScrollEnd ={this._onMomentumScrollEnd}
     ...
      </Swiper>
    )
  }
})

More ScrollResponder info, see: https://github.com/facebook/react-native/blob/master/Libraries/Components/ScrollResponder.js

Methods

scrollBy(index)

Scroll by relative index.

Parameters:

Name	Type	Description
index	number	offset index

Examples

$ cd examples
$ npm i
$ react-native run-ios

Quick start with examples.

Development

$ cd examples
$ npm i
$ npm run dev
$ react-native run-ios

Then launch simulator for preview, note that, you just need edit the source file src/index.js, the change will auto sync to examples.

And now this project follow the standard code style, you'd better prepare it for IDE.

Contribution

@leecade The main author.
@rajkissu The secondary contributor.

Questions

Feel free to contact me or create an issue

Inspired by nolimits4web/Swiper & Design material from Dribbble & made with ♥.

nemophrost/react-native-swiper