0
# PagerView Component
1

2
Core ViewPager component that provides swipeable page navigation with native performance. Each child view is treated as a separate page and stretched to fill the PagerView container.
3

4
## Capabilities
5

6
### PagerView Class
7

8
Main container component for creating swipeable page interfaces with native ViewPager implementations.
9

10
```typescript { .api }
11
/**
12
 * Container that allows to flip left and right between child views. Each
13
 * child view of the PagerView will be treated as a separate page
14
 * and will be stretched to fill the PagerView.
15
 */
16
export default class PagerView extends React.Component<PagerViewProps> {
17
  /**
18
   * A helper function to scroll to a specific page in the PagerView.
19
   * The transition between pages will be animated.
20
   */
21
  setPage(selectedPage: number): void;
22
  
23
  /**
24
   * A helper function to scroll to a specific page in the PagerView.
25
   * The transition between pages will *not* be animated.
26
   */
27
  setPageWithoutAnimation(selectedPage: number): void;
28
  
29
  /**
30
   * A helper function to enable/disable scroll imperatively
31
   * The recommended way is using the scrollEnabled prop, however, there might be a case where a
32
   * imperative solution is more useful (e.g. for not blocking an animation)
33
   */
34
  setScrollEnabled(scrollEnabled: boolean): void;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import React, { useRef } from 'react';
42
import { View, Text, Button, StyleSheet } from 'react-native';
43
import PagerView from 'react-native-pager-view';
44

45
export default function PagerViewExample() {
46
  const pagerRef = useRef<PagerView>(null);
47

48
  const goToPage = (page: number) => {
49
    pagerRef.current?.setPage(page);
50
  };
51

52
  const goToPageWithoutAnimation = (page: number) => {
53
    pagerRef.current?.setPageWithoutAnimation(page);
54
  };
55

56
  return (
57
    <View style={styles.container}>
58
      <View style={styles.buttonContainer}>
59
        <Button title="Go to page 1" onPress={() => goToPage(1)} />
60
        <Button title="Jump to page 2" onPress={() => goToPageWithoutAnimation(2)} />
61
      </View>
62
      
63
      <PagerView
64
        ref={pagerRef}
65
        style={styles.pagerView}
66
        initialPage={0}
67
        onPageSelected={(e) => console.log('Page selected:', e.nativeEvent.position)}
68
      >
69
        <View style={[styles.page, { backgroundColor: '#ff6b6b' }]} key="1">
70
          <Text style={styles.text}>Page 1</Text>
71
        </View>
72
        <View style={[styles.page, { backgroundColor: '#4ecdc4' }]} key="2">
73
          <Text style={styles.text}>Page 2</Text>
74
        </View>
75
        <View style={[styles.page, { backgroundColor: '#45b7d1' }]} key="3">
76
          <Text style={styles.text}>Page 3</Text>
77
        </View>
78
      </PagerView>
79
    </View>
80
  );
81
}
82

83
const styles = StyleSheet.create({
84
  container: { flex: 1 },
85
  buttonContainer: { 
86
    flexDirection: 'row', 
87
    justifyContent: 'space-around', 
88
    padding: 20 
89
  },
90
  pagerView: { flex: 1 },
91
  page: { 
92
    justifyContent: 'center', 
93
    alignItems: 'center' 
94
  },
95
  text: { 
96
    fontSize: 24, 
97
    fontWeight: 'bold', 
98
    color: 'white' 
99
  },
100
});
101
```
102

103
### Props Configuration
104

105
Comprehensive configuration options for customizing PagerView behavior and appearance.
106

107
```typescript { .api }
108
interface PagerViewProps extends ViewProps {
109
  /** Enable or disable scrolling. Default: true */
110
  scrollEnabled?: boolean;
111
  
112
  /** Layout direction for the pager. Default: 'ltr' */
113
  layoutDirection?: 'ltr' | 'rtl';
114
  
115
  /** Index of the initially selected page. Default: 0 */
116
  initialPage?: number;
117
  
118
  /** Orientation of the pager. Default: 'horizontal' */
119
  orientation?: 'horizontal' | 'vertical';
120
  
121
  /** Number of pages to render and keep in memory on each side of the current page */
122
  offscreenPageLimit?: number;
123
  
124
  /** Margin between pages in density-independent pixels */
125
  pageMargin?: number;
126
  
127
  /** Overscroll behavior when reaching the end of pages. Default: 'auto' */
128
  overScrollMode?: 'auto' | 'always' | 'never';
129
  
130
  /** Enable overdrag effect (iOS). Default: false */
131
  overdrag?: boolean;
132
  
133
  /** Keyboard dismiss mode when dragging. Default: 'none' */
134
  keyboardDismissMode?: 'none' | 'on-drag';
135
  
136
  /** Callback fired when the page is being scrolled */
137
  onPageScroll?: (event: PagerViewOnPageScrollEvent) => void;
138
  
139
  /** Callback fired when a new page is selected */
140
  onPageSelected?: (event: PagerViewOnPageSelectedEvent) => void;
141
  
142
  /** Callback fired when the scroll state changes */
143
  onPageScrollStateChanged?: (event: PageScrollStateChangedNativeEvent) => void;
144
}
145
```
146

147
**Advanced Configuration Example:**
148

149
```typescript
150
import React from 'react';
151
import { View, Text, StyleSheet } from 'react-native';
152
import PagerView from 'react-native-pager-view';
153

154
export default function AdvancedPagerView() {
155
  const handlePageScroll = (event: PagerViewOnPageScrollEvent) => {
156
    const { position, offset } = event.nativeEvent;
157
    console.log(`Scroll progress: page ${position}, offset ${offset}`);
158
  };
159

160
  const handlePageSelected = (event: PagerViewOnPageSelectedEvent) => {
161
    console.log('Selected page:', event.nativeEvent.position);
162
  };
163

164
  const handleScrollStateChanged = (event: PageScrollStateChangedNativeEvent) => {
165
    console.log('Scroll state:', event.nativeEvent.pageScrollState);
166
  };
167

168
  return (
169
    <PagerView
170
      style={styles.pagerView}
171
      initialPage={1}
172
      orientation="horizontal"
173
      layoutDirection="ltr"
174
      scrollEnabled={true}
175
      pageMargin={20}
176
      offscreenPageLimit={2}
177
      overScrollMode="auto"
178
      overdrag={true}
179
      keyboardDismissMode="on-drag"
180
      onPageScroll={handlePageScroll}
181
      onPageSelected={handlePageSelected}
182
      onPageScrollStateChanged={handleScrollStateChanged}
183
    >
184
      <View style={styles.page} key="1">
185
        <Text>Configured Page 1</Text>
186
      </View>
187
      <View style={styles.page} key="2">
188
        <Text>Configured Page 2</Text>
189
      </View>
190
      <View style={styles.page} key="3">
191
        <Text>Configured Page 3</Text>
192
      </View>
193
    </PagerView>
194
  );
195
}
196

197
const styles = StyleSheet.create({
198
  pagerView: { flex: 1 },
199
  page: { 
200
    justifyContent: 'center', 
201
    alignItems: 'center',
202
    backgroundColor: '#f0f0f0',
203
  },
204
});
205
```
206

207
### Event Handling
208

209
Detailed event system for tracking scroll progress, page selection, and state changes.
210

211
```typescript { .api }
212
/** Event fired during page scrolling with position and offset information */
213
type PagerViewOnPageScrollEvent = ReactNative.NativeSyntheticEvent<{
214
  /** Current page index (can be fractional during scroll) */
215
  position: number;
216
  /** Scroll offset within the current page (0.0 to 1.0) */
217
  offset: number;
218
}>;
219

220
/** Event fired when a page is fully selected */
221
type PagerViewOnPageSelectedEvent = ReactNative.NativeSyntheticEvent<{
222
  /** Index of the selected page */
223
  position: number;
224
}>;
225

226
/** Event fired when scroll state changes */
227
type PageScrollStateChangedNativeEvent = ReactNative.NativeSyntheticEvent<{
228
  /** Current scroll state */
229
  pageScrollState: 'idle' | 'dragging' | 'settling';
230
}>;
231
```
232

233
**Event Handling Example:**
234

235
```typescript
236
import React, { useState } from 'react';
237
import { View, Text, StyleSheet } from 'react-native';
238
import PagerView from 'react-native-pager-view';
239

240
export default function EventHandlingExample() {
241
  const [currentPage, setCurrentPage] = useState(0);
242
  const [scrollProgress, setScrollProgress] = useState({ position: 0, offset: 0 });
243
  const [scrollState, setScrollState] = useState('idle');
244

245
  return (
246
    <View style={styles.container}>
247
      <Text style={styles.info}>
248
        Current Page: {currentPage} | 
249
        Scroll: {scrollProgress.position.toFixed(1)} + {scrollProgress.offset.toFixed(2)} |
250
        State: {scrollState}
251
      </Text>
252
      
253
      <PagerView
254
        style={styles.pagerView}
255
        initialPage={0}
256
        onPageScroll={(e) => setScrollProgress(e.nativeEvent)}
257
        onPageSelected={(e) => setCurrentPage(e.nativeEvent.position)}
258
        onPageScrollStateChanged={(e) => setScrollState(e.nativeEvent.pageScrollState)}
259
      >
260
        <View style={styles.page} key="1">
261
          <Text>Page 1</Text>
262
        </View>
263
        <View style={styles.page} key="2">
264
          <Text>Page 2</Text>
265
        </View>
266
        <View style={styles.page} key="3">
267
          <Text>Page 3</Text>
268
        </View>
269
      </PagerView>
270
    </View>
271
  );
272
}
273

274
const styles = StyleSheet.create({
275
  container: { flex: 1 },
276
  info: { padding: 16, backgroundColor: '#f0f0f0', textAlign: 'center' },
277
  pagerView: { flex: 1 },
278
  page: { justifyContent: 'center', alignItems: 'center' },
279
});
280
```