UNPKG

7.57 kBMarkdownView Raw
1# react-native-viewpager <img src="docs/viewpager-logo.png" alt="ViewPager" width="24" height="24">
2
3[![CircleCI branch](https://img.shields.io/circleci/build/github/callstack/react-native-viewpager/master.svg)](https://circleci.com/gh/callstack/react-native-viewpager/tree/master)
4[![npm package](https://badge.fury.io/js/%40react-native-community%2Fviewpager.svg)](https://badge.fury.io/js/%40react-native-community%2Fviewpager)
5[![Lean Core Extracted](https://img.shields.io/badge/Lean%20Core-Extracted-brightgreen.svg)](https://github.com/facebook/react-native/issues/23313)
6[![License](https://img.shields.io/github/license/react-native-community/react-native-viewpager?color=blue)](https://github.com/callstack/react-native-viewpager/blob/master/LICENSE)
7
8This component allows the user to swipe left and right through pages of data. Under the hood it is using the native [Android ViewPager](https://developer.android.com/reference/android/support/v4/view/ViewPager) and the [iOS UIPageViewController](https://developer.apple.com/documentation/uikit/uipageviewcontroller) implementations. [See it in action!](https://github.com/react-native-community/react-native-viewpager#preview)
9
10<br/>
11<p align="center">
12 <img src="docs/vp-carousel.gif" alt="ViewPager" width="300">
13</p>
14
15<br/>
16
17## Versions
18
19| 3.x | ~~4.0.x, 4.1.x~~ | >= 4.2.x | 5.x
20| ------------- | ------------- | ------------- | ------------- |
21| iOS support | Deprecated | iOS support | iOS support |
22| ViewPager1 support | Deprecated | [Reverted to 3.3.0](https://github.com/callstack/react-native-viewpager/issues/233#issue-711000654) | ViewPager2 support |
23
24## Getting started
25
26`yarn add @react-native-community/viewpager`
27
28## Linking
29
30### >= 0.60
31
32Autolinking will just do the job.
33
34### < 0.60
35
36#### Mostly automatic
37
38`react-native link @react-native-community/viewpager`
39
40#### Manual linking
41
42<details>
43<summary>Manually link the library on iOS</summary>
44</br>
45
46Follow the [instructions in the React Native documentation](https://facebook.github.io/react-native/docs/linking-libraries-ios#manual-linking) to manually link the framework or link using [Cocoapods](https://cocoapods.org) by adding this to your `Podfile`:
47
48```ruby
49pod 'react-native-viewpager', :path => '../node_modules/@react-native-community/viewpager'
50```
51
52</details>
53
54<details>
55<summary>Manually link the library on Android</summary>
56</br>
57Make the following changes:
58
59#### `android/settings.gradle`
60
61```groovy
62include ':@react-native-community_viewpager'
63project(':@react-native-community_viewpager').projectDir = new File(rootProject.projectDir, '../node_modules/@react-native-community/viewpager/android')
64```
65
66#### `android/app/build.gradle`
67
68```groovy
69dependencies {
70 ...
71 implementation project(':@react-native-community_viewpager')
72}
73```
74
75#### `android/app/src/main/.../MainApplication.java`
76
77On top, where imports are:
78
79```java
80import com.reactnativecommunity.viewpager.RNCViewPagerPackage;
81```
82
83Add the `RNCViewPagerPackage` class to your list of exported packages.
84
85```java
86@Override
87protected List<ReactPackage> getPackages() {
88 return Arrays.<ReactPackage>asList(
89 new MainReactPackage(),
90 new RNCViewPagerPackage()
91 );
92}
93```
94
95</details>
96
97## Usage
98
99```js
100import React from 'react';
101import {StyleSheet, View, Text} from 'react-native';
102import ViewPager from '@react-native-community/viewpager';
103
104const MyPager = () => {
105 return (
106 <ViewPager style={styles.viewPager} initialPage={0}>
107 <View key="1">
108 <Text>First page</Text>
109 </View>
110 <View key="2">
111 <Text>Second page</Text>
112 </View>
113 </ViewPager>
114 );
115};
116
117const styles = StyleSheet.create({
118 viewPager: {
119 flex: 1,
120 },
121});
122```
123
124**Attention:** Note that you can only use `View` components as children of `ViewPager` (cf. folder */example*)
125. For Android if `View` has own children, set prop `collapsable` to false <https://reactnative.dev/docs/view#collapsable>, otherwise react-native might remove those children views and and it's children will be rendered as separate pages
126
127## Advanced usage
128
129For advanced usage please take a look into our [example project](https://github.com/callstack/react-native-viewpager/blob/master/example/src/BasicViewPagerExample.tsx)
130
131## API
132
133|Prop|Description|Platform|
134|-|:-----:|:---:|
135|`initialPage`|Index of initial page that should be selected|both
136|`scrollEnabled: boolean`|Should viewpager scroll, when scroll enabled|both
137|`onPageScroll: (e: PageScrollEvent) => void`|Executed when transitioning between pages (ether because the animation for the requested page has changed or when the user is swiping/dragging between pages)|both
138|`onPageScrollStateChanged: (e: PageScrollStateChangedEvent) => void`|Function called when the page scrolling state has changed|both
139|`onPageSelected: (e: PageSelectedEvent) => void`|This callback will be called once the ViewPager finishes navigating to the selected page|both
140|`pageMargin: number`|Blank space to be shown between pages|both
141|`keyboardDismissMode: ('none' / 'on-drag')`| Determines whether the keyboard gets dismissed in response to a drag|both
142|`orientation: Orientation`|Set `horizontal` or `vertical` scrolling orientation (it does **not** work dynamically)|both
143|`transitionStyle: TransitionStyle`|Use `scroll` or `curl` to change transition style (it does **not** work dynamically)|iOS
144|`showPageIndicator: boolean`|Shows the dots indicator at the bottom of the view|iOS
145|`overScrollMode: OverScollMode`|Used to override default value of overScroll mode. Can be `auto`, `always` or `never`. Defaults to `auto`|Android
146|`offscreenPageLimit: number`|Set the number of pages that should be retained to either side of the currently visible page(s). Pages beyond this limit will be recreated from the adapter when needed. Defaults to RecyclerView's caching strategy. The given value must either be larger than 0.|Android
147|`overdrag: boolean`|Allows for overscrolling after reaching the end or very beginning or pages|iOS
148
149## Development workflow
150
151To get started with the project, run `yarn bootstrap` in the root directory to install the required dependencies.
152
153```sh
154yarn bootstrap
155```
156
157While developing, you can run the example to check your changes
158
159```sh
160cd example
161yarn android
162yarn ios
163```
164
165Before sending a pull rquest, make sure your code passes TypeScript and ESLint. Run the following to verify:
166
167```sh
168yarn typescript
169yarn lint
170```
171
172To fix formatting errors, run the following:
173
174```sh
175yarn lint --fix
176```
177
178## Preview
179
180### Android
181
182horizontal | vertical
183:-------------------------:|:-------------------------:
184<img src="docs/android-viewpager.gif" alt="ViewPager" width="325"> | <img src="docs/android-viewpager-vertical.gif" alt="ViewPager" width="325">
185
186### iOS
187
188horizontal - scroll | horizontal - curl
189:-------------------------:|:-------------------------:
190<img src="docs/ios-viewpager-scroll.gif" alt="ViewPager" width="325"> | <img src="docs/ios-viewpager-curl.gif" alt="ViewPager" width="325">
191
192vertical - scroll | vertical - curl
193:-------------------------:|:-------------------------:
194<img src="docs/ios-viewpager-vertical.gif" alt="ViewPager" width="325"> | <img src="docs/ios-viewpager-vertical-curl.gif" alt="ViewPager" width="325">